Hedy API

O Que é a Hedy API?

A Hedy API fornece acesso programático aos seus dados de reuniões, transcrições, resumos e insights gerados por IA. Seja para construir integrações personalizadas, automatizar fluxos de trabalho ou conectar com ferramentas como o Zapier, a API oferece o poder de estender as capacidades do Hedy além do app. Todos os recursos da API requerem uma assinatura Pro com Cloud Sync ativado.

Primeiros Passos com a API

1. Abra o app Hedy e navegue até Account Settings

2. Role até a seção API Access

3. Clique em Generate New API Key (assinatura Pro obrigatória)

4. Copie sua chave de API e armazene-a com segurança — você não poderá vê-la novamente

5. Visite nossa documentação da API no SwaggerHub para informações detalhadas dos endpoints, ou acesse a especificação OpenAPI bruta em https://api.hedy.bot/v1/docs

Nota de Segurança: Sua chave de API fornece acesso completo aos seus dados do Hedy. Mantenha-a segura e nunca a compartilhe publicamente ou a inclua em controle de versão.

Capacidades da API

A Hedy API oferece acesso abrangente à sua inteligência de reuniões:

• Sessions: Liste e recupere suas sessões de reuniões, incluindo transcrições completas, resumos de IA e pontos-chave

• Highlights: Recupere momentos importantes das suas reuniões com insights gerados por IA

• Topics: Crie, atualize, exclua e organize sessões por tópicos com instruções de contexto personalizadas

• Todos: Recupere e gerencie itens de ação de todas as sessões

• Session Contexts: Crie e gerencie instruções reutilizáveis que orientam como o Hedy analisa suas reuniões

• Webhooks: Configure e gerencie endpoints de webhook via API para notificações de eventos em tempo real

• User Info: Recupere os detalhes da sua conta via o endpoint /me

Autenticação

Todas as solicitações da API requerem autenticação usando sua chave de API. Inclua-a no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Webhooks

Configure webhooks para receber notificações em tempo real quando eventos ocorrem na sua conta Hedy:

1. Na seção API Access, clique em Manage Webhooks

2. Clique no botão + para adicionar um novo webhook

3. Insira a URL do seu endpoint HTTPS

4. Selecione os eventos que deseja receber:

   • session.created - Quando uma nova sessão de gravação começa

   • session.ended - Quando uma sessão de gravação conclui o processamento

   • session.exported - Quando uma sessão é exportada manualmente pelo usuário

   • highlight.created - Quando um novo destaque é adicionado

   • todo.exported - Quando tarefas são exportadas de uma sessão

5. Salve seu webhook e anote o segredo de assinatura para verificação do payload

Você também pode gerenciar webhooks programaticamente via API usando GET, POST e DELETE no endpoint /webhooks. Cada conta pode ter até 50 webhooks.

Verificação de Assinatura do Webhook

Cada entrega de webhook inclui uma assinatura no cabeçalho X-Hedy-Signature para que você possa verificar que veio do Hedy. A assinatura é um hash HMAC-SHA256 do corpo bruto da solicitação, assinado com o segredo de assinatura do seu webhook. Verifique a assinatura no seu servidor antes de processar o payload para garantir autenticidade. Cada entrega também inclui um cabeçalho X-Hedy-Event indicando o tipo de evento (ex.: session.ended).

Session Contexts

Os Session Contexts permitem que você crie conjuntos reutilizáveis de instruções personalizadas que dizem ao Hedy como analisar suas reuniões. Por exemplo, você pode criar um contexto para “Ligações de Vendas” que foca em itens de ação e objeções de clientes, ou um para “Reuniões Diárias” que rastreia bloqueios e atualizações.

Use a API para gerenciar seus contextos de sessão:

• GET /contexts - Liste todos os seus contextos de sessão

• GET /contexts/{id} - Obtenha um contexto específico por ID

• POST /contexts - Crie um novo contexto (título e conteúdo)

• PATCH /contexts/{id} - Atualize um contexto existente

• DELETE /contexts/{id} - Remova um contexto

Defina um contexto como padrão e ele será aplicado automaticamente a todas as novas sessões. Contas do plano gratuito estão limitadas a 1 contexto de sessão.

Gerenciando Tópicos via API

Os tópicos ajudam você a organizar suas sessões em categorias. A API suporta gerenciamento completo de tópicos:

• GET /topics - Liste todos os tópicos com insights gerados por IA e contagens de sessões

• GET /topics/{id} - Obtenha detalhes de um tópico específico

• POST /topics - Crie um novo tópico com nome, descrição, cor e ícone

• PATCH /topics/{id} - Atualize as propriedades de um tópico ou contexto personalizado

• DELETE /topics/{id} - Remova um tópico (sessões são desvinculadas, não excluídas)

• GET /topics/{id}/sessions - Liste todas as sessões dentro de um tópico

Os tópicos podem incluir um campo topicContext com instruções personalizadas (até 20.000 caracteres) que orientam como o Hedy analisa sessões atribuídas a esse tópico.

Casos de Uso Comuns

• Integração com Gerenciamento de Projetos: Crie automaticamente tarefas na sua ferramenta de PM a partir dos itens de ação das reuniões

• Gestão do Conhecimento: Indexe o conteúdo das reuniões na base de conhecimento da sua empresa

• Integração com CRM: Atualize registros de clientes com insights das reuniões

• Dashboards Analíticos: Construa relatórios personalizados sobre padrões de reuniões e produtividade

• Automação de Fluxos de Trabalho: Acione ações com base no conteúdo ou conclusão de reuniões

• Integração com Zapier: Conecte o Hedy a milhares de apps usando o Zapier (adicione ?format=zapier aos endpoints para respostas de array plano compatíveis com o Zapier)

Limites e Melhores Práticas da API

• Limites de taxa: 200 solicitações por minuto por chave de API

• Paginação: Use o parâmetro limit (padrão 50, máximo 100) e o parâmetro cursor after para paginar os resultados

• Armazene respostas em cache quando possível para reduzir chamadas à API

• Trate erros de forma elegante com backoff exponencial

• Use webhooks para atualizações em tempo real em vez de polling

Exportação Automática de Tarefas

Ative a exportação automática de tarefas para enviar itens de ação aos seus sistemas integrados:

1. Na seção API Access, ative Auto Export Todos

2. As tarefas serão automaticamente enviadas aos seus endpoints de webhook configurados

3. Cada tarefa inclui contexto, sugestões de responsável e referência da reunião

Exemplos de Código

Aqui está um exemplo simples para obter suas sessões recentes:

curl -X GET "https://api.hedy.bot/v1/sessions?limit=10" \  -H "Authorization: Bearer YOUR_API_KEY"

Para mais exemplos e a referência completa de endpoints, visite nossa documentação da API.

Solução de Problemas

Erro 401 Unauthorized

• Verifique se sua chave de API está correta e devidamente formatada

• Certifique-se de que você tem uma assinatura Pro ativa

• Verifique se o Cloud Sync está ativado na sua conta

• Confirme que a chave de API não foi regenerada (chaves antigas são invalidadas)

Resposta Vazia ou Dados Ausentes

• Certifique-se de que o Cloud Sync está ativado — a API só acessa dados sincronizados na nuvem

• Aguarde alguns minutos após a gravação para os dados sincronizarem

• Verifique seus filtros de data e parâmetros de paginação

• Verifique se você está usando o endpoint correto para seu tipo de dados

Webhook Não Está Recebendo Eventos

• Confirme que a URL do seu endpoint usa HTTPS (obrigatório)

• Verifique se seu servidor responde com status 200 OK

• Verifique o cabeçalho X-Hedy-Signature se estiver implementando verificação de assinatura

• Teste seu webhook usando o botão “Test Webhook”

• Verifique se regras de firewall não estão bloqueando os servidores do Hedy

Limite de Taxa Excedido

• Implemente cache para reduzir chamadas redundantes à API

• Use webhooks para atualizações em tempo real em vez de polling

• Agrupe operações quando possível

• Entre em contato com o suporte se precisar de limites maiores

Dica profissional: Use webhooks em vez de polling para atualizações em tempo real. Isso é mais eficiente e fornece notificações instantâneas quando seus dados mudam.

Privacidade e Segurança

A segurança dos seus dados é nossa prioridade:

• Toda a comunicação da API usa criptografia HTTPS

• As chaves de API podem ser regeneradas a qualquer momento (invalida a chave antiga)

• Os payloads de webhook são assinados com HMAC-SHA256 para verificação

• Os dados são acessíveis apenas com autenticação válida

• Todos os endpoints aplicam cabeçalhos de segurança rigorosos

Obtendo Ajuda

Para perguntas específicas sobre a API:

• Consulte a documentação da API para detalhes de endpoints e schemas

• Leia nosso post do blog sobre a API para exemplos e casos de uso

• Participe da nossa comunidade no Slack para suporte e compartilhar suas integrações