Canais e integrações

Canal de API

Conecte a Entagl ao seu próprio app ou ao Make: envie mensagens, receba respostas e gerencie seu workspace.

Visão geral

O channel de API permite usar o mesmo agente de AI que alimenta seus DMs no chat do seu próprio site, app mobile ou backend. Você envia uma mensagem, o agente pensa (com o mesmo buffering e respostas em várias mensagens, como um DM real) e a resposta chega um pouco depois, por um webhook callback ou via polling. Configure em Canais → API: gere uma API key, ative o channel e escolha callback ou polling. A mesma API também permite que seu desenvolvedor, ou o Make, trabalhe com contatos, conversas, bookings, pedidos e muito mais. Veja a aba Workspace API.

Para desenvolvedores: referência da API

Todos os endpoints, campos e eventos de webhook, com exemplos de código.

Abas nesta página

A API não serve só para chat. Seu desenvolvedor, ou uma ferramenta como o Make, pode usá-la para ler e atualizar a maior parte do seu workspace.

O que você pode fazer com ela

Além de enviar mensagens, a API cobre:

Contacts: criar, atualizar, consultar, mesclar, adicionar notas, marcar como do-not-contact
Tags e lifecycle stages: adicionar ou remover tags, mover um contato para outra etapa
Conversations: atribuir a um membro da equipe, encerrar com uma nota de fechamento, pausar ou retomar a AI, adicionar comentários da equipe, enviar uma mensagem como sua empresa
Bookings e reminders: verificar horários livres, agendar, reagendar, cancelar, criar e encerrar reminders
Orders e products: criar e atualizar pedidos e seus itens, gerenciar seu catálogo
Calls: iniciar uma ligação telefônica com AI ou colocá-la na fila, ler o resultado
Campaigns: ver suas campaigns e enviar uma

Quando algo muda, a Entagl pode avisar suas ferramentas imediatamente por meio de webhooks.

Duas formas de fazer sign-in

Make. Quando você conecta o Make, faz sign-in com sua própria conta da Entagl. O Make então age como você, com exatamente as suas permissões: um owner ou admin pode fazer tudo, e um membro da equipe apenas o que seus privilégios permitem. Se o seu login tiver mais de um workspace, você escolhe qual usar.

API key. Para o seu próprio server, crie uma key em Canais → API ou Configurações → API keys e envie como Authorization: Bearer <your key>. Uma key pertence a um único workspace e tem acesso total de owner a ele, então trate-a como uma senha.

Seguro para retry: o header Idempotency-Key

Às vezes a request é processada, mas a resposta se perde no caminho de volta. Se o seu sistema não tiver certeza de que a request funcionou, ele pode enviá-la de novo com o mesmo header Idempotency-Key. Em até 24 horas a Entagl reconhece a key, ignora o trabalho e retorna a primeira resposta, para que você não acabe com dois pedidos ou dois contatos. Usar a mesma key para uma request diferente é recusado com erro.

Quantas requests você pode enviar

Até 120 requests por minuto para cada workspace. Se passar disso, a Entagl responde com erro 429 (rate_limited). Aguarde um momento e tente novamente. A maioria das automações nem chega perto disso.

A referência completa da API

Cada endpoint, campo e código de erro está listado na referência da API da Entagl. Se seu desenvolvedor ainda não a tiver, envie um email para support@entagl.com e peça a API reference.

Uma API key dá acesso total de owner ao workspace dela. Guarde-a no seu server, nunca dentro de um site ou app que seus clientes possam abrir, e revogue-a assim que suspeitar que vazou.

As alterações feitas pela API são marcadas como vindas da API nos seus eventos de webhook, então um cenário do Make pode ignorar as próprias alterações em vez de entrar em loop.

Recursos

Configuração e autenticação

Gere uma chave de API em Channels → API, ative o interruptor do canal e chame a API em https://api.entagl.com com o cabeçalho Authorization: Bearer <sua chave>. As chaves são restritas ao espaço de trabalho.

Enviar uma mensagem

Faça POST em /api/v1/messages com { message, externalUserId }. Você recebe um 202 e um conversationId imediatamente. Reutilize esse conversationId para continuar a conversa. A resposta do agente chega depois, não nesta response.

Webhook (callback) (recomendado)

Adicione um URL de callback HTTPS público e a Entagl enviará cada resposta do agente para lá via POST, assinada com o cabeçalho X-Entagl-Signature (HMAC-SHA256). Verifique a assinatura e responda 2xx em cerca de 5 segundos. Não há nova tentativa automática.

Sondagem (Polling)

Se você não puder hospedar um URL de callback, chame GET /api/v1/conversations/:id/messages?since=<cursor> para obter as respostas novas. Passe o cursor de cada resposta como ?since= para receber apenas mensagens novas.

Segurança e isolamento

As API keys são armazenadas com hash e o signing secret é criptografado (ambos mostrados apenas uma vez). Toda consulta fica restrita ao workspace: um conversation ID de outro workspace retorna 404, e você não pode passar um user ID (ele é derivado da sua key).

Tarefas comuns

Configurar o canal de API

Cerca de 3 min

Vá em Channels → API e clique em Generate API Key. Copie agora, porque ela é exibida apenas uma vez.
Ative o interruptor do canal no cabeçalho do cartão de API.
Recomendado: expanda o cartão, cole um URL de callback HTTPS público, salve e copie o segredo de assinatura.
Do seu app, envie mensagens via POST para https://api.entagl.com/api/v1/messages e receba as respostas por callback ou por sondagem.

Dicas

As respostas são assíncronas. O POST retorna 202, e a resposta do agente chega via callback ou polling, não na response.

Uma mensagem pode gerar várias respostas após um breve atraso de buffering (cerca de 8 segundos, configurável até ~5 minutos). Exiba todas, em ordem.

Um 202 não garante uma resposta. O agente pode ficar em silêncio se a automação estiver pausada, um guardrail bloquear a mensagem ou o workspace estiver sem créditos.

Os callbacks não têm nova tentativa automática. Mantenha a sondagem como reserva e sempre verifique o cabeçalho X-Entagl-Signature antes de confiar em uma entrega.

Reutilize o conversationId para continuar uma conversa; externalUserId é apenas o seu próprio rótulo para o usuário final.

Por enquanto, apenas texto. Mantenha sua API key e seu signing secret em segurança: ambos são exibidos apenas uma vez.

Perguntas frequentes

Esta página foi útil?