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.
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 do Entagl. Abra-a com o link Para desenvolvedores: referência da API perto do topo desta página e compartilhe-a com seu desenvolvedor.
Recursos
Configuração e autenticação
Abra Configurações → Integrações, escolha API e clique em Gerar Chave da API. Ative o interruptor no cartão do Canal API, então chame a API em https://api.entagl.com com o cabeçalho Authorization: Bearer <sua chave>. Cada chave funciona apenas para um 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)
Cole uma URL de callback no cartão do Canal API e clique em Salvar. O Entagl então POSTa cada resposta do agente para ela, assinada com o cabeçalho X-Entagl-Signature (HMAC-SHA256). Use um endereço HTTPS público e clique em Enviar entrega de teste para verificar se funciona. Seu servidor deve verificar a assinatura e responder com um código 2xx em cerca de 5 segundos. Callbacks com falha não são reprocessados.
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- Abra Configurações → Integrações, escolha API e clique em Gerar Chave da API. Dê um nome se desejar, então copie a chave agora, pois ela é mostrada apenas uma vez.
- Ative o interruptor no cabeçalho do cartão do Canal API. Até que esteja ativado, mensagens enviadas para a API são recusadas.
- Recomendado: abra as configurações do cartão, cole sua URL de callback e clique em Salvar. Copie o segredo de assinatura que aparece, então clique em Enviar entrega de teste.
- 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
Perguntas frequentes
Esta página foi útil?