A API do Entagl permite que o seu próprio software trabalhe com um workspace do Entagl: contatos, conversas, mensagens, agendamentos, lembretes, pedidos, produtos, chamadas de IA e campanhas. Os webhooks avisam seus sistemas no instante em que algo acontece. É a mesma API que o app do Entagl para o Make usa.

Requisições e respostas são JSON sobre HTTPS. Os nomes dos campos usam snake_case. Os IDs são números inteiros, a menos que um endpoint diga outra coisa. Os horários são strings ISO 8601; as respostas usam UTC.

Envie um token em toda requisição, no header Authorization: Authorization: Bearer <token>. Dois tipos de token funcionam:

Um header ausente responde 401 unauthenticated. Uma chave errada ou revogada responde 401 invalid_api_key. Um token OAuth expirado responde 401 invalid_token: renove-o e tente de novo.

Cada requisição trabalha em exatamente um workspace. Uma API key sempre usa o próprio workspace. Um login OAuth pode pertencer a vários workspaces (próprios ou em que entrou como membro da equipe): envie o header X-Entagl-Workspace com o ID do workspace para escolher um. Com um único workspace, o header é opcional. GET /me funciona sem o header e lista todos os workspaces que o login pode usar.

Sem o header em um login com vários workspaces, você recebe 400 workspace_required; um workspace a que o login não tem acesso responde 403 workspace_forbidden. Um ID que pertence a outro workspace sempre responde 404 not_found, nunca 403.

Cada endpoint abaixo mostra a permissão de que precisa. Proprietários, admins e API keys passam em todas as verificações. Membros da equipe passam quando o papel deles tem essa permissão marcada nas configurações da equipe: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns ou integrations. Sem ela, a API responde 403 insufficient_permissions.

Envie os corpos como JSON com Content-Type: application/json. A maioria dos endpoints rejeita campos desconhecidos no corpo com 422, então um erro de digitação nunca passa em silêncio. Todo erro usa o mesmo formato: um code estável para você tratar no código, uma message legível e, nos erros de validação, uma lista details que aponta cada campo inválido.

As rotas marcadas como Formato de resposta legado são anteriores a estas convenções: retornam objetos ou arrays JSON simples e respondem à maioria dos erros como { "message": "…" }.

Os endpoints marcados como Paginado retornam primeiro os itens mais recentes, dentro de um envelope de lista. Peça até 100 itens com limit (padrão 25). Quando has_more for true, passe next_cursor como starting_after para obter a próxima página. As outras listas retornam tudo de uma vez com has_more: false.

Todo endpoint POST no formato padrão aceita o header Idempotency-Key (até 200 caracteres). Use um valor único por operação, como um UUID. A Entagl guarda a primeira resposta por 24 horas: uma nova tentativa com a mesma chave e o mesmo body recebe essa resposta com Idempotent-Replayed: true, e nada é executado duas vezes. Rotas marcadas como Formato de resposta legado funcionam de outro jeito, veja abaixo.

• A mesma chave com um corpo diferente responde 409 idempotency_key_reused.
• Enquanto a primeira requisição ainda está em andamento, ou se ela nunca terminou, uma nova tentativa responde 409 request_in_progress. Confira o resultado e tente de novo com uma chave nova.
• Todo resultado é guardado, inclusive erros. Para tentar de novo uma requisição que falhou, use uma chave nova.
• As chaves valem para o workspace e a credencial.

Rotas legadas. POST /messages também aceita Idempotency-Key (ou um message_id no body): repetir uma mensagem já aceita responde 202 com o mesmo conversationId e ela não é processada duas vezes, e a mesma chave com outro body responde 409. POST /chat não tem proteção contra repetição: uma nova tentativa roda a IA de novo, então confira o resultado antes de tentar outra vez.

Cada workspace pode fazer 120 requisições por minuto, compartilhadas por todas as suas API keys e conexões. As respostas trazem RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (segundos até a janela reiniciar). Acima do limite, você recebe 429 rate_limited com um header Retry-After: espere esse número de segundos e tente de novo. As rotas legadas do canal de API não contam neste limite.