Anil CRM

Guia de Integração

Conecte seu sistema ao Anil CRM: leia e crie contatos, acompanhe conversas, envie mensagens, aplique etiquetas, monte e ligue chatbots, converse com a sua equipe e receba eventos em tempo real por webhook.

Base https://api.anilcrm.com.br

O endereço antigo, https://api.msgflowapp.com.br, continua funcionando para sempre — integração que já usa ele não precisa mudar nada. As mudanças desta API ficam no histórico de mudanças, no fim da página.

1. Criar a chave de API

  1. Entre no Anil CRM e vá em Configurações → Chaves de API.
  2. Clique em Nova chave, dê um nome que diga para que ela serve (ERP produção, integração teste) e marque só os escopos que a integração realmente precisa.
  3. Copie a chave agora. Ela aparece uma única vez e não pode ser recuperada depois — nem por quem a criou. Se perder, revogue e crie outra.
Só o dono ou um administrador pode emitir chave. A chave alcança tudo o que o administrador dono dela alcança, e é pessoal: se essa pessoa for desativada ou rebaixada, a chave para de funcionar na mesma hora. Prefira uma chave por integração, para poder revogar uma sem derrubar as outras.
Restrição por canal. Ao criar a chave você pode limitá-la a canais específicos. Uma chave restrita não enxerga nem age em conversas e mensagens de outros canais — elas respondem 404, como se não existissem —, e campanha só sai pelos canais dela.
O que a restrição por canal NÃO filtra: contatos (o contato é da empresa, não do número), equipe, setores, etiquetas, respostas rápidas, a base de conhecimento e a lista de páginas de captura. Se a integração não deve ver esses dados, não marque os escopos deles na chave.
Seguem os números da chave (desde 18/10/2026): a lista de canais, os relatórios (sem filtro de canal, contam só os números dela), a agenda de mensagens, as campanhas, o funil e as respostas das páginas de captura.

2. Autenticar

Mande a chave no cabeçalho Authorization, em toda requisição.

curl https://api.anilcrm.com.br/v1/me \
  -H "Authorization: Bearer anil_live_xxxxxxxx_sua_chave_aqui"

A resposta confirma a credencial e mostra o alcance dela:

{
  "tenantId": "...",
  "tenant": {                  // a organização desta chave, por extenso
    "id": "...",
    "name": "Difafá Cosméticos",
    "slug": "difafa-cosmeticos"
  },
  "key": { "id": "...", "name": "ERP produção", "prefix": "anil_live_xxxxxxxx" },
  "scopes": ["contacts:read", "messages:send"],
  "channelIds": [],            // vazio = todos os canais
  "owner": { "id": "...", "role": "ADMIN" }
}

Chame este endpoint primeiro, sempre. Ele é a resposta rápida para "por que deu 401?" e para "esta chave é da empresa certa?".

Fixar a organização esperada (opcional)

Se você administra mais de uma empresa, um risco real é usar a chave de uma no ambiente de outra — e a requisição funcionar, agindo no lugar errado sem nenhum sinal. Para fechar isso, mande junto o cabeçalho X-Anil-Org com o slug da organização que você espera:

curl https://api.anilcrm.com.br/v1/me   -H "Authorization: Bearer SUA_CHAVE"   -H "X-Anil-Org: difafa-cosmeticos"

Se a chave for de outra empresa, a requisição para com 403 e a mensagem diz quais são as duas. O slug sai do slug em /v1/me.

O cabeçalho só sabe RECUSAR. Ele nunca escolhe a empresa — quem define a organização é a chave, e só ela. Mandar um slug diferente não dá acesso a lugar nenhum: derruba a requisição. É por isso que usá-lo é seguro em produção, e é também por isso que ele não substitui ter a chave certa.

É opcional e compatível: integração que não manda o cabeçalho continua funcionando igual. Vale a pena quando o mesmo código roda contra empresas diferentes, ou entre ambientes de teste e produção.

Nunca coloque a chave na URL. Query string vaza em log de proxy, histórico de navegador e no cabeçalho Referer. A chave só é aceita no cabeçalho Authorization.
/v1 é contrato; /api não é. O prefixo /api é o backend da nossa própria tela e muda junto com ela, sem aviso. Integre sempre por /v1.

3. Escopos

O escopo diz o que a chave faz; o papel de quem a emitiu diz até onde ela enxerga. Os dois se somam. Chamar uma rota sem o escopo dela devolve 403 nomeando o que falta.

GrupoEscopos
Contatos e etiquetascontacts:read contacts:write labels:read labels:write labels:manage
Atendimentoconversations:read conversations:write messages:read messages:send
Campanhas, agenda e relatórioscampaigns:read campaigns:write reports:read scheduled:read
Funil de negóciosdeals:read deals:write boards:write
Chatbotschatbots:read chatbots:write
Mensagens da equipe (as suas)team-messages:read team-messages:send
Organização (leitura)sectors:read users:read channels:read quick-replies:read boards:read capture:read tracking:read
Base de conhecimento (IA)knowledge:read knowledge:write
Criar e apagar etiqueta tem escopo próprio (labels:manage). labels:write só aplica e remove. Criar mexe na lista de etiquetas da empresa inteira e apagar tira a etiqueta de todo contato e conversa de uma vez — por isso fica numa caixa separada. Configuração da organização é só leitura: criar setor, usuário ou canal por API mudaria como a empresa atende, e um erro de integração ali é muito pior que um contato errado. A exceção é o chatbot: dá para montar e editar, mas ele nasce desligado e ligar é uma chamada à parte.

4. Endpoints

Contatos

RotaEscopo
GET /v1/contactscontacts:read
GET /v1/contacts/:idcontacts:read
POST /v1/contactscontacts:write
PATCH /v1/contacts/:idcontacts:write
DELETE /v1/contacts/:id — excluir (as conversas ficam)contacts:write
GET /v1/contact-fields — campos personalizados que existemcontacts:read
POST /v1/contacts/lookup — procurar até 100 telefonescontacts:read
Listagem — parâmetroO que faz
searchParte do nome ou do telefone.
labelIdSó quem tem esta etiqueta.
ownerUserIdSó a carteira deste atendente; sem-dono = quem ainda não tem dono.
originall (padrão), whatsapp ou instagram.
sortname_asc (padrão), name_desc, recent, oldest.
page, limitPágina (desde 1) e itens por página — padrão 20, máximo 100.
Criar / editar — campoO que é
nameObrigatório ao criar.
phoneObrigatório ao criar e não muda depois. Só dígitos, com DDI e DDD: 5517999998888. Telefone que já existe responde 409.
emailOpcional; "" apaga.
notesAs Notas do contato (até 10.000 caracteres). No PATCH substitui o texto inteiro.
customFieldsCampos personalizados, { "chave": valor }. No PATCH substitui o objeto inteiro — leia, mude e mande todos.
optedOuttrue = a pessoa pediu para não receber: sai de campanhas e automações. Só no PATCH.
ownerUserIdDono na carteira (id de /v1/users); null tira da carteira.

Conversas e atendimento

RotaEscopo
GET /v1/conversationsconversations:read
GET /v1/conversations/:id — uma conversaconversations:read
GET /v1/conversations/:id/window — a janela de 24h está aberta?conversations:read
GET /v1/ai-agents — agentes de IA (para ligar numa conversa)conversations:read
POST /v1/conversations — abrir com um númeroconversations:write
POST /v1/conversations/:id/assignconversations:write
POST /v1/conversations/:id/unassignconversations:write
POST /v1/conversations/:id/resolve — finalizar (com venda ou perda, opcional)conversations:write
POST /v1/conversations/:id/reopenconversations:write
POST /v1/conversations/:id/transfer-sectorconversations:write
POST /v1/conversations/:id/notes — nota internaconversations:write
POST /v1/conversations/:id/stop-chatbot — parar o chatbot nesta conversaconversations:write
PUT /v1/conversations/:id/ai-agent — ligar ou desligar a IAconversations:write
POST /v1/conversations/:id/read — marcar como lidaconversations:write
AçãoCorpo e efeito
resolveSem corpo, só finaliza. Com { "outcome": { "result": "WON", "amountCents": 15000 } } registra a venda (valor em centavos), ou { "outcome": { "result": "LOST", "lossReason": "preço" } } a perda — entra no relatório de vendas e fecha o negócio aberto no funil, igual à tela. Corpo inválido: 400, e a conversa não é finalizada.
stop-chatbotO chatbot deixa de esperar a resposta e os lembretes dele são cancelados. Ele continua ligado para os outros clientes.
ai-agent{ "aiAgentId": "…", "aiMode": "autopilot" } — a IA responde sozinha (Piloto); "copilot" — só sugere para a equipe; { "aiAgentId": null, "aiMode": null } desliga. Ligar gasta atendimento de IA da cota da organização: com a cota acabada, 409. Ligar com o cliente esperando faz a IA responder já.
readZera o "não lida". ⚠ O cliente recebe o "visto" (tiques azuis) — é a mesma ação de abrir a conversa na tela. Responde 204.
window{ insideWindow, restanteMs, kind, lastInboundAt, fepStartedAt }. insideWindow: true = dá para mandar texto livre agora; false no WhatsApp Oficial = só template. kind: service (atendimento aberto), fep (lead de anúncio: só template, mas grátis, até 7 dias) ou none. restanteMs = quanto falta para fechar.
Listagem — parâmetroO que faz
statusOPEN (na fila, aguardando), IN_PROGRESS (em atendimento) ou RESOLVED (finalizada).
assignedToSó as de um atendente (id de /v1/users).
channelId, labelIdSó de um canal / com uma etiqueta.
dateFrom, dateToData e hora com fuso (2026-10-01T00:00:00-03:00).
unreadtrue = com mensagem não lida.
unansweredtrue = o cliente escreveu e nenhuma pessoa respondeu depois (robô, saudação e nota não contam).
overduetrue = passaram do prazo dos timers de inatividade.
isGroup, archivedtrue/false: só grupos ou só individuais; arquivadas.
search, searchInBusca. searchIn: name, phone, messages (dentro do texto das conversas — a mais lenta) ou all (padrão).
page, pageSizePágina (desde 1) e itens por página — padrão 20, máximo 100. Aqui é pageSize, não limit.

Cada conversa aparece uma vez; na busca, matchTypes diz por onde ela casou (name, phone, message) e matchedMessage traz a mensagem que casou.

assign recebe { "userId": "..." }. transfer-sector recebe { "sectorId": "..." }, ou null para tirar do setor. Para desatribuir use /unassign — não um null no assign.

notes grava uma nota interna na conversa — a equipe vê, o cliente não recebe nada: { "content": "Combinado entrega na sexta" }. Com "saveToContact": true, a nota vai também para as Notas do contato (pede também o escopo contacts:write). Fica em nome do administrador dono da chave.

Mensagens

RotaEscopo
GET /v1/conversations/:id/messagesmessages:read
POST /v1/conversations/:id/messages — textomessages:send
POST /v1/conversations/:id/messages/media — mídiamessages:send
POST /v1/conversations/:id/messages/template — templatemessages:send
POST /v1/conversations/:id/messages/schedule — agendarmessages:send
POST /v1/conversations/:id/messages/schedule-chatbot — agendar um chatbotmessages:send
POST /v1/conversations/:id/messages/forward — reenviar uma mensagem que já existemessages:send + messages:read
POST /v1/conversations/:id/messages/location — localizaçãomessages:send
POST /v1/conversations/:id/messages/contact — cartão de contato
POST /v1/conversations/:id/messages/buttons — botões de resposta
POST /v1/conversations/:id/messages/list — lista de opções
POST /v1/conversations/:id/messages/link-button — botão com link
POST /v1/conversations/:id/messages/poll — enquete
POST /v1/messages/:id/react — reagir com emojimessages:send
POST /v1/messages/:id/transcribe — texto de um áudiomessages:read
POST /v1/media/upload-urlmessages:send
GET /v1/messages/:id/downloadmessages:read

Ler mensagens: vêm as mais recentes (pageSize: padrão 50, máximo 100). Para as anteriores, mande before com o createdAt da mais antiga que você já tem — é cursor, não página (page só vale junto com search, que procura no texto da conversa).

Enviar texto aceita, além de content (até 4.096 caracteres): quotedMessageId (responder citando uma mensagem), mentions (em grupo: telefones só com dígitos, ou "all" para todos) e signMessage: true (começa a mensagem com o nome do administrador dono da chave, em negrito). Se a empresa obriga assinatura nas configurações, ela vai de qualquer jeito.

/download devolve { url, fileName } — uma URL assinada e temporária, não os bytes. Baixe a partir dela.

Na tela do Anil, toda mensagem enviada pela API aparece com o selo Via API · Nome (o administrador dono da chave) — a equipe sabe que foi a integração, e de quem. Mensagem que a sua automação manda direto pelo WhatsApp conectado (sem passar pela API do Anil) também aparece como Via API, e não como "Celular".

Etiquetas

RotaEscopo
GET /v1/labelslabels:read
GET /v1/conversations/:id/labelslabels:read
POST /v1/contacts/:id/labels/:labelIdlabels:write
DELETE /v1/contacts/:id/labels/:labelIdlabels:write
POST /v1/conversations/:id/labels/:labelIdlabels:write
DELETE /v1/conversations/:id/labels/:labelIdlabels:write
POST /v1/labelslabels:manage
PATCH /v1/labels/:idlabels:manage
DELETE /v1/labels/:idlabels:manage
POST /v1/labels/sync-whatsapplabels:manage

Criar: { "name": "Lead quente", "color": "#22c55e" }. Sem visibility, a empresa toda vê; "SECTOR" pede sectorId, e "PRIVATE" fica só para o dono da chave. Nome repetido responde 409. Editar muda só o que vier. Apagar responde 204 e tira a etiqueta de todos os contatos e conversas — não tem desfazer. sync-whatsapp recebe { "channelId": "…" } e traz as etiquetas do WhatsApp Business daquele número (só o não oficial); devolve { "imported": 3 }.

Relatórios

RotaEscopo
GET /v1/reports/overviewreports:read
GET /v1/reports/team — cada atendente: conversas, tempos e resultado
GET /v1/reports/sources
GET /v1/reports/sales
GET /v1/reports/ai
GET /v1/reports/calls
GET /v1/reports/capture
GET /v1/reports/filters
ParâmetroO que faz
from, toPeríodo (AAAA-MM-DD ou data e hora). Sem eles, os últimos 7 dias.
channelId / channelIdsUm canal, ou vários separados por vírgula.
assignedTo / agentIdsUm atendente, ou vários.
sectorIdsSetores; none = conversas sem setor.
scopeindividual (padrão, sem grupos), group (só grupos) ou all.
timeModeComo contar 1ª resposta, atribuição e resolução: business conta só o horário de atendimento de cada canal, sem feriados (igual à tela); wall conta o relógio corrido. Sem o parâmetro, a API usa wall — é o que ela sempre fez, e mudar quebraria quem já integra.

/reports/filters devolve os canais, setores e atendentes disponíveis — use para montar os filtros das outras rotas de relatório. Relatório é a rota mais pesada da API: o limite é 30 por minuto. Chave presa a números: sem filtro de canal, o relatório conta só os números dela; pedir um número de fora responde 404.

Organização e campanhas (leitura)

RotaEscopo
GET /v1/sectorssectors:read
GET /v1/usersusers:read
GET /v1/channelschannels:read
GET /v1/channels/:id/instagram-media — posts e Reels (?after= pagina)channels:read
GET /v1/channels/:id/templates — templates do número oficialchannels:read
GET /v1/channels/:id/groups — os grupos do número (WhatsApp não oficial)channels:read
GET /v1/channels/:id/groups/:groupJid — um grupo: participantes, admins e link de convitechannels:read
GET /v1/quick-repliesquick-replies:read
GET /v1/boards — os funisboards:read
GET /v1/knowledge-basesknowledge:read
GET /v1/knowledge-bases/:id — a base e os documentosknowledge:read
POST /v1/knowledge-bases/:id/text — acrescentar textoknowledge:write
DELETE /v1/knowledge-bases/:id/documents/:documentId
GET /v1/capture-formscapture:read
GET /v1/capture-forms/:id/submissions — as respostas (?limit=, até 500)capture:read
GET /v1/tracking-linkstracking:read
GET /v1/scheduled-messagesscheduled:read
GET /v1/campaignscampaigns:read
GET /v1/campaigns/:idcampaigns:read
GET /v1/campaigns/:id/recipients — quem recebeu, um a um
GET /v1/campaigns/:id/stats — os totais
POST /v1/campaigns/preview — quantos vai atingir
POST /v1/campaigns — criarcampaigns:write
PATCH /v1/campaigns/:id — editar o rascunho
POST /v1/campaigns/:id/dispatch
POST /v1/campaigns/:id/pause
POST /v1/campaigns/:id/resume
POST /v1/campaigns/:id/cancel
GET /v1/menenhum

A lista de campanhas aceita status (DRAFT, SCHEDULED, RUNNING, PAUSED, COMPLETED, CANCELLED, FAILED), q (parte do nome), page e pageSize (padrão 20, máximo 100).

Chatbots

RotaEscopo
GET /v1/chatbotschatbots:read
GET /v1/chatbots/:id — com o fluxo inteirochatbots:read
GET /v1/chatbots/guide — formato do fluxonenhum
POST /v1/chatbots/:id/simulate — testar sem enviar nadachatbots:read
POST /v1/chatbots — criar (nasce desligado)chatbots:write
PATCH /v1/chatbots/:id
POST /v1/chatbots/:id/activate — ligar
POST /v1/chatbots/:id/deactivate — desligar
DELETE /v1/chatbots/:id
POST /v1/conversations/:id/run-chatbot — rodar numa conversamessages:send
GET /v1/chatbot-folders — pastas, com quantos chatbots em cadachatbots:read
POST /v1/chatbot-folders — criar pastachatbots:write
PATCH /v1/chatbot-folders/:folderId — renomear
DELETE /v1/chatbot-folders/:folderId — apagar (os chatbots vão para "Sem pasta")

A listagem aceita search, status (DRAFT ou PUBLISHED), isActive, folderId (uma pasta, ou none para os sem pasta), page e limit.

Pastas organizam os chatbots na tela (um nível só, da empresa inteira) e não mudam quem vê o chatbot nem quando ele dispara. Para pôr um chatbot numa pasta, mande folderId ao criar ou no PATCH; "folderId": null tira da pasta. Cada chatbot traz folder ({ id, name } ou null).

Mensagens da equipe

RotaEscopo
GET /v1/team/threads — as suas conversas (?unread=true)team-messages:read
GET /v1/team/threads/:threadId/messages
GET /v1/team/people — colegas
POST /v1/team/threads/:threadId/read — marcar como lida
POST /v1/team/threads/:threadId/messagesteam-messages:send
POST /v1/team/dm — abrir conversa com um colega

5. Abrir conversa com um número novo

Toda mensagem sai dentro de uma conversa. Se a pessoa já falou com você, a conversa existe — pegue o id dela em GET /v1/conversations e pule para o envio.

Se ela nunca falou com você, abra a conversa primeiro:

curl -X POST https://api.anilcrm.com.br/v1/conversations \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "uuid-do-canal",
    "phone": "5517999998888",
    "name": "Nadine"
  }'

Responde 201 com a conversa. Use o id dela para enviar. O channelId — ou seja, por qual número seu a conversa vai sair — você pega em GET /v1/channels. O name é opcional e só vale se o contato ainda não existir.

Chamar duas vezes com o mesmo número não cria duas conversas. A rota devolve a conversa que já existe naquele canal. Pode repetir sem medo.
A conversa nasce na fila, sem atendente (status OPEN, "Aguardando") — enviar mensagem por ela também não atribui ninguém. A que já existia continua com quem já atendia. Para dar dono, use POST /v1/conversations/:id/assign.
Esta é a rota que inicia contato com quem não te procurou. Abrir conversa não envia nada sozinho, mas é o primeiro passo do contato frio — e contato frio em volume é o jeito mais rápido de o WhatsApp bloquear o seu número. Se o seu caso é falar com muita gente de uma vez, não abra conversa por conversa: crie uma campanha, que aplica intervalo entre disparos, rodízio de números, janela de horário e cota diária.

6. Enviar e agendar mensagem

Este endpoint envia na hora, sem nenhum intervalo entre disparos. Ele não aplica atraso, rodízio de números, janela de horário nem cota diária — o ritmo é responsabilidade de quem chama. Um laço no seu código queima o número de WhatsApp, e o número é seu. Para envio em massa, crie uma campanha, que aplica o ritmo. Este endpoint é para mensagem avulsa, resposta e notificação.
curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4821-confirmado" \
  -d '{"content": "Seu pedido saiu para entrega!"}'

Para imagem, áudio ou documento veja enviar mídia.

Agendar para depois

Mesma ideia, com data e hora: a mensagem fica na Agenda do Anil e sai sozinha na hora marcada (com até 30 segundos de diferença). Texto ou template.

curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages/schedule \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lembrete-consulta-4821" \
  -d '{
    "content": "Oi, Nadine! Lembrete da sua consulta amanhã às 14h.",
    "scheduledAt": "2026-10-08T09:00:00-03:00",
    "cancelOnContactReply": true
  }'
CampoO que faz
scheduledAtData e hora com fuso (-03:00 para Brasília). Precisa estar no futuro.
contentO texto. Use este ou template.
template{ "templateName", "languageCode", "bodyParams" }, igual ao envio de template. Só canal Oficial.
cancelOnContactReplyNão envia se o contato escrever antes da hora.
cancelOnAgentReplyNão envia se alguém da equipe responder antes da hora.

Responde 201 com a mensagem agendada. Para conferir a agenda, use GET /v1/scheduled-messages?from=…&to=…&status=pending (escopo scheduled:read; from e to também com fuso). Para cancelar: DELETE /v1/scheduled-messages/:id (escopo messages:send) — com ?group=true, cancela o agendamento inteiro (a mensagem e os lembretes dela). Responde { "cancelled": n }; o que já saiu dá 409.

Agendar um chatbot (vários passos, mídia, botões): POST /v1/conversations/:id/messages/schedule-chatbot com { "chatbotId", "scheduledAt", "cancelOnContactReply", "cancelOnAgentReply" }. Na hora marcada o fluxo roda na conversa. O chatbot precisa estar publicado e ligado (senão 400) e no alcance da chave. Cancela igual, pelo DELETE /v1/scheduled-messages/:id.

No canal Oficial, texto agendado só sai se a janela de 24h estiver aberta na hora do envio — senão ele é marcado como falha. Se o contato pode ficar mais de 24h sem escrever até lá, agende um template. Lembretes automáticos e cabeçalho de template com mídia só pela tela.

7. Enviar mídia

São dois passos: você pede uma URL de upload, manda o arquivo direto para o storage, e depois envia a mensagem citando a chave que recebeu. O arquivo nunca passa pela API — por isso funciona com arquivo grande.

Passo 1 — pedir a URL

curl -X POST https://api.anilcrm.com.br/v1/media/upload-url \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"filename": "boleto.pdf", "contentType": "application/pdf"}'

# → { "uploadUrl": "https://...", "mediaKey": "...", "expiresInSec": 300 }

Passo 2 — subir o arquivo

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @boleto.pdf

Use PUT, e o mesmo Content-Type que você informou no passo 1. A URL vale 5 minutos.

Passo 3 — enviar

curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages/media \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: boleto-4821" \
  -d '{
    "type": "DOCUMENT",
    "mediaKey": "a-key-do-passo-1",
    "fileName": "boleto.pdf",
    "caption": "Segue o boleto"
  }'
typePara quê
IMAGEfoto, print, comprovante
VIDEOvídeo
AUDIOáudio
DOCUMENTPDF e afins — use fileName
STICKERfigurinha (webp)

A mediaKey tem que ser a que o passo 1 devolveu (ou de um arquivo que já está no Anil): chave de arquivo de outra organização é recusada com 400 e code: "MEDIA_OUTSIDE_TENANT". Também aceitos: quotedMessageId e, em grupo, mentions — iguais aos do texto.

Mídia pesa mais que texto no julgamento do WhatsApp. Rajada de imagem para quem não te procurou é o padrão clássico de conta bloqueada. Este endpoint também não aplica intervalo nenhum.

8. Template — falar depois das 24h

Só para canal Oficial (WhatsApp Business API). Em canal não oficial esta rota responde 422, e não é necessária: lá não existe janela de 24h.

No canal Oficial, se o contato não te responde há mais de 24 horas, mensagem comum é recusada com 422. O único jeito de falar com ele é um template aprovado pela Meta.

curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/messages/template \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "confirmacao_pedido",
    "languageCode": "pt_BR",
    "bodyParams": ["Nadine", "4821"]
  }'

bodyParams preenche {{1}}, {{2}}… na ordem. O template precisa estar aprovado na Meta antes. Para ver os que existem, com nome, idioma, status (só APPROVED envia) e o texto, use GET /v1/channels/:id/templates — a lista vem da Meta na hora. Para saber se precisa de template, GET /v1/conversations/:id/window.

8b. Botões, lista, enquete, localização e contato

Os mesmos tipos da tela, um caminho cada, todos em POST /v1/conversations/:id/messages/<tipo> com o escopo messages:send, Idempotency-Key e quotedMessageId opcional. Respondem 201 com a mensagem.

TipoCorpo
location{ "lat": -20.27, "lng": -50.54, "name": "Loja", "address": "Rua A, 1" } (nome e endereço opcionais)
contact{ "displayName": "Suporte", "phone": "5517999990000", "organization", "email", "url" } — o cartão que a pessoa salva com um toque
buttons{ "bodyText": "Quer seguir?", "buttons": [{ "id": "sim", "title": "Sim" }], "footer", "header": { "type": "text", "text": "…" } } — 1 a 3 botões, título até 20 letras. O toque chega como mensagem (BUTTON_REPLY).
list{ "bodyText", "buttonText": "Ver opções", "sections": [{ "title", "rows": [{ "rowId": "a", "title": "A", "description" }] }] } — até 10 opções no total, título até 24 letras
link-button{ "bodyText", "displayText": "Abrir", "url": "https://…" } — um botão que abre o site
poll{ "bodyText": "Qual cor?", "choices": ["Azul", "Rosa"], "selectableCount": 1 } — 2 a 12 opções; os votos chegam na conversa
O suporte varia por canal. Quando o canal não tem aquele tipo, a resposta é 422 e nada sai. No não oficial, a aparência dos botões depende da versão do WhatsApp de quem recebe. Nenhum destes aplica intervalo entre envios — o mesmo aviso do envio de texto.

Reagir e transcrever

POST /v1/messages/:id/react com { "emoji": "👍" } reage (o cliente vê); "" tira a reação. Responde 204. POST /v1/messages/:id/transcribe devolve { "transcription", "cached" } de um áudio (outro tipo: 422; áudio ainda baixando: 409). A segunda chamada devolve o que já foi transcrito, sem custo.

9. Campanhas — o caminho seguro para volume

Se você vai falar com muita gente, é por aqui. Diferente do envio avulso, a campanha passa pelo motor de disparo: intervalo entre mensagens, rodízio de números, janela de horário e cota diária. É o anti-ban que o envio direto não tem.

Criar

curl -X POST https://api.anilcrm.com.br/v1/campaigns \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Promo de setembro",
    "channelId": "uuid-do-canal",
    "contentMode": "TEXT",
    "messageText": "Oi {nome}! Temos novidade.",
    "recipientSource": "SEGMENT",
    "recipientIds": ["uuid-da-etiqueta"],
    "minDelaySec": 30,
    "maxDelaySec": 60,
    "sendWeekdays": [1,2,3,4,5],
    "sendHours": [9,10,11,14,15,16],
    "dailyLimit": 200
  }'

Ela nasce em DRAFT — criar não dispara. Confira e então dispare:

curl -X POST https://api.anilcrm.com.br/v1/campaigns/ID/dispatch \
  -H "Authorization: Bearer SUA_CHAVE"
AçãoQuando vale
POST /v1/campaigns/:id/dispatchsó em DRAFT
POST /v1/campaigns/:id/pausesó em execução
POST /v1/campaigns/:id/resumesó pausada
POST /v1/campaigns/:id/cancelenquanto não encerrou
GET /v1/campaigns/:idacompanhar o progresso
Disparo não tem desfazer. Cancelar segura o que ainda não saiu; o que já foi entregue, já foi. Por isso criar e disparar são duas chamadas — dá para conferir os destinatários em GET /v1/campaigns/:id antes.
Ritmo: minDelaySec/maxDelaySec é o intervalo aleatório entre mensagens (o padrão é 30–60s, e mais lento é mais seguro). sendWeekdays usa 1=segunda. sendHours são as horas cheias liberadas. sendChannelIds liga o rodízio entre vários números.
Corrigido em 18/10/2026: até essa data, o exemplo acima mostrava segmentLabelIds, um campo que a API não lia — a campanha nascia sem ninguém. O certo é recipientIds (na origem SEGMENT, os ids das etiquetas). segmentLabelIds passou a ser aceito como sinônimo, então quem copiou o exemplo antigo volta a funcionar sem mudar nada.

Antes de disparar: quantos vai atingir

curl -X POST https://api.anilcrm.com.br/v1/campaigns/preview \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "campaignId": "ID", "recipientSource": "SEGMENT", "recipientIds": ["uuid-da-etiqueta"] }'

Devolve quantas pessoas a campanha atinge e quantas ficam de fora por terem pedido para não receber — o mesmo recorte do disparo. Com campaignId, conta como o disparo daquela campanha vai contar (o público de quem a criou).

Editar e acompanhar

PATCH /v1/campaigns/:id muda o rascunho (os mesmos campos de criar; só o que vier muda). Depois de disparada, 409. Para acompanhar: GET /v1/campaigns/:id/stats (enviadas, entregues, lidas, respondidas, falhas) e GET /v1/campaigns/:id/recipients — pessoa a pessoa, com status, responded=true|false, q (nome ou telefone), page e pageSize (até 100).

10. Chatbots

Monte o fluxo do chatbot por API: o que ele pergunta, os botões, as condições, para qual setor ele passa a conversa. O desenho é o mesmo da tela — um chatbot criado aqui abre e edita normalmente no editor visual.

Criar não liga. O chatbot nasce em DRAFT e não responde ninguém. Ligar é POST /v1/chatbots/:id/activate, numa chamada separada — o mesmo cuidado da campanha, em que criar e disparar também são duas chamadas. Toda resposta de chatbot traz ligado (true só quando ele responde sozinho) e situacao por extenso. isActive: true num rascunho não é ligado: só quer dizer que dá para testá-lo numa conversa.

O formato do fluxo

Um fluxo é uma lista de nós (os passos) e de fios (qual passo vem depois de qual). O guia completo, com todos os campos de cada nó, sai da própria API — é a mesma tabela que valida o que você manda:

curl https://api.anilcrm.com.br/v1/chatbots/guide \
  -H "Authorization: Bearer SUA_CHAVE"
ParaNós — campo typeSaídas — campo sourceHandle
ComeçarstartTrigger — o gatilhouma
EnviarsendMessage, sendTemplate (Oficial), sendLocation, sendContact, sendPoll e sendCarousel (não oficial), replyComment (Instagram)uma
Perguntar e esperaraskInput (resposta livre, com validação opcional: e-mail, telefone, CPF, número, data ou regex), askChoice (lista), buttons, followUpaskInput: uma — com validação, valid / invalid · askChoice: opt-0, opt-1… e noMatch · buttons: o id de cada botão e noResponse · followUp: responded / noResponse
DecidirconditionData, conditionWeekday, conditionTime, randomSplittrue / false · randomSplit: A / B
FazercreateNote, saveContactField, editLabels, statusWaiting, waitLimited, saveContact, openWhatsappuma · saveContact: saved / invalid · openWhatsapp: sent / failed
EncerrartransferAgent, transferSector, endConversation, activateAiAgent, triggerFlownenhuma
Anotar o quadronota — post-it para a equipe; o chatbot ignoranenhuma (não tem fio)

Limites: até 200 nós e 500 fios. A validação por regex roda num motor de tempo linear (RE2): não aceita lookaround ((?=…)) nem retrorreferência (\1).

createNote grava uma nota interna na conversa — a equipe vê, o cliente não. Com "saveToContact": true, a nota vai também para as Notas do contato (fica na ficha e aparece em qualquer canal).

O gatilho fica no nó startTrigger, em triggerType: manual (só roda quando alguém executa), firstMessage (toda primeira mensagem de um contato novo), keyword (mensagem que contém o termo), both, windowExpiring, e no Instagram commentKeyword, liveCommentKeyword e storyReply.

Para o commentKeyword valer só num post ou Reel, pegue o post em GET /v1/channels/:id/instagram-media e preencha no gatilho: mediaId (o id), mediaPermalink (o permalink) e mediaCaption (a legenda, até 160 caracteres — a lista já devolve cortada). Sem mediaId, vale para comentário em qualquer post.

Criar

curl -X POST https://api.anilcrm.com.br/v1/chatbots \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bot-orcamento-v1" \
  -d '{
    "name": "Orçamento",
    "channelId": "uuid-do-canal",
    "flow": {
      "nodes": [
        { "id": "inicio", "type": "startTrigger",
          "data": { "triggerType": "keyword", "keyword": "orçamento, preço" } },
        { "id": "oi", "type": "sendMessage",
          "data": { "message": "Oi, ${contact.firstName}! Já te ajudo." } },
        { "id": "menu", "type": "buttons",
          "data": { "bodyText": "O que você procura?",
                    "buttons": [ { "id": "produto", "label": "Produtos" },
                                 { "id": "humano", "label": "Falar com alguém" } ] } },
        { "id": "catalogo", "type": "sendMessage",
          "data": { "message": "Nosso catálogo: https://exemplo.com" } },
        { "id": "fila", "type": "transferSector", "data": { "sectorId": "uuid-do-setor" } }
      ],
      "edges": [
        { "source": "inicio", "target": "oi" },
        { "source": "oi", "target": "menu" },
        { "source": "menu", "sourceHandle": "produto", "target": "catalogo" },
        { "source": "menu", "sourceHandle": "humano", "target": "fila" },
        { "source": "menu", "sourceHandle": "noResponse", "target": "fila" }
      ]
    }
  }'

Responde 201 com o chatbot e uma lista avisos — coisas que não impedem, mas que você deveria saber (um termo curto demais no gatilho, um nó que nunca é alcançado). A posição dos nós no editor é calculada sozinha; mande position só se quiser escolher. Sem flow, o chatbot nasce só com o gatilho manual.

Fluxo com problema é recusado inteiro, com a lista do que corrigir. Nó vazio, saída que não existe, nó que o canal não suporta, id de etiqueta, setor ou atendente que não é da sua empresa — e nó sem fio de entrada, que seria executado logo no começo, junto com o gatilho. A resposta é 400 com problemas:
{
  "error": "Fluxo inválido (2 problemas): (1) nó \"oi\" (sendMessage): precisa de message ou media (2) …",
  "problemas": [
    "nó \"oi\" (sendMessage): precisa de message ou media",
    "fio menu → fila [talvez]: sourceHandle \"talvez\" não existe; use: produto, humano, noResponse"
  ]
}

Testar numa conversa antes de ligar

curl -X POST https://api.anilcrm.com.br/v1/conversations/CONV_ID/run-chatbot \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"chatbotId": "ID_DO_CHATBOT"}'

Roda o fluxo agora, naquela conversa. Chatbot que nunca foi ligado roda o que você gravou. Chatbot que já está no ar roda a versão publicada — para testar as suas mudanças antes de publicar, mande "rascunho": true. Responde {"status":"concluido"}, ou "aguardando_resposta" quando o fluxo parou numa pergunta, junto com passos (o que ele fez). Se o fluxo demorar (há pausa de até 5 minutos), a resposta é 202 com "em_andamento" e ele segue sozinho. Chatbot desligado ou canal desconectado: 409. O escopo é messages:send: o efeito é mensagem chegando numa pessoa real. Use uma conversa sua para testar.

Ligar

curl -X POST https://api.anilcrm.com.br/v1/chatbots/ID/activate \
  -H "Authorization: Bearer SUA_CHAVE"

# → { …, "status": "PUBLISHED", "isActive": true,
#     "gatilhos": ["responde a qualquer mensagem que contenha: orçamento, preço"] }

Ligar publica o que está gravado e põe no ar. Antes, confere o fluxo (ele pode ter sido mexido na tela) e recusa com 422 se houver problema. gatilhos diz, em português, quando ele vai responder.

Chatbot ligado responde sozinho a clientes reais. firstMessage responde a todo contato novo do canal — e só pode haver um ligado por canal (o segundo dá 409). keyword casa pedaço de palavra: oi dispara em boi e noite.

Editar, desligar e excluir

AçãoComo funciona
PATCH /v1/chatbots/:idTroca name, description, visibility, sectorId, folderId e o flow inteiro — leia com GET /v1/chatbots/:id e mande de volta com a mudança. Num chatbot ligado, a mudança vai para o rascunho: os clientes continuam recebendo a versão no ar até você chamar /activate, que publica. Quem está no meio de um fluxo termina na versão em que começou. O canal não muda por API.
POST /v1/chatbots/:id/deactivatePara de disparar e cancela os follow-ups pendentes. O fluxo continua salvo.
DELETE /v1/chatbots/:idApaga de vez — fluxo, versões e números. Não tem desfazer. Chatbot ligado precisa ser desligado antes; chatbot em uso por campanha, horário de atendimento, agendamento ou outro fluxo responde 409 dizendo onde.

Lead do Instagram chamado no WhatsApp

Dois nós fazem a ponte: o fluxo do Instagram pede o número, grava na lista de Contatos e chama a pessoa no WhatsApp pelo número que você escolher.

NóO que faz
saveContactGrava o contato pelo telefone (phone, normalmente ${var:telefone}), com name e email opcionais. Quem já tem o número é atualizado; o lead do Instagram ganha o telefone no próprio contato. Sem DDI, assume Brasil. Sai por saved ou invalid (peça o número de novo).
openWhatsappAbre a conversa no canal de WhatsApp escolhido (channelId) e envia a primeira mensagem em até 30 segundos: message no não oficial, template no Oficial. Opcional: sectorId da fila. Sai por sent ou failed.
No canal Oficial a primeira mensagem tem que ser template aprovado — quem nunca falou com o número não recebe texto livre. E quem pediu para não receber mensagens (PARAR) não é chamado: o nó sai por failed.

O exemplo completo — com a volta para pedir o número quando ele vem errado — está em exemploInstagramParaWhatsapp, no guia.

Simular sem enviar nada

curl -X POST https://api.anilcrm.com.br/v1/chatbots/ID/simulate \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "texto": "quero um orçamento" }'

O ensaio da tela: roda o rascunho no motor de verdade e devolve saidas (o que o chatbot mandaria), caminho (os nós por onde passou), tipoDoPasso e estado. Para a próxima mensagem do "cliente", mande de volta o estado junto com o texto; sem estado, começa do início. Nada sai para o WhatsApp e nada é gravado.

10b. Funil de negócios

O funil da tela: etapas, negócios com valor e responsável, ganho e perda. Escopos deals:read (ver) e deals:write (mexer) — chaves criadas antes de 18/10/2026 não os têm; crie uma chave nova com eles. A lista de funis é GET /v1/boards (escopo boards:read). Criar, configurar e arquivar o funil em si é boards:write (02/11/2026) — veja logo abaixo.

RotaEscopo
GET /v1/boards/:id — o funil: etapas, totais e negócios abertos (?mine=true = só os do dono da chave)deals:read
GET /v1/boards/:id/people — quem enxerga o funil: só essas pessoas podem ser o ownerUserId de um negócio dele
GET /v1/deals/:id — um negócio, com o histórico
GET /v1/conversations/:id/deals — os negócios abertos do cliente da conversa (o desta conversa primeiro); ganho ou perdido sai da lista
POST /v1/boards/:id/deals — criardeals:write
PATCH /v1/deals/:id — editar
POST /v1/deals/:id/move — { "columnId" }
POST /v1/deals/:id/win — { "valueCents" } opcional
POST /v1/deals/:id/lose — { "lossReason", "lossNote" }
POST /v1/deals/:id/reopen
POST /v1/deals/:id/undo-ai — o "Desfazer" do movimento da IA (só enquanto ela foi a última a mexer; senão 409)
Criar / editar — campoO que é
contactIdObrigatório ao criar.
columnIdA etapa (de GET /v1/boards/:id). Sem ela, a primeira.
conversationIdA conversa do negócio (opcional) — finalizar essa conversa com venda ou perda fecha o negócio junto.
title, valueCents, ownerUserId, nextStep, nextStepAt, notesO que se vende, o valor em centavos, o responsável (de /v1/boards/:id/people), o próximo passo (e quando, com fuso) e notas. No PATCH, null apaga.
lossReasonpreco, prazo, sem_resposta, concorrente, fora_perfil ou outro (com lossNote).
Como na tela, criar e ganhar negócio podem avisar a Meta (lead qualificado e venda, pela API de Conversões), quando a empresa ligou esse aviso. Mover para outra etapa também conta como qualificado. Negócio fechado não muda de etapa (409) — reabra antes.
Chave presa a números: alcança só o funil cujos números estão todos dentro dos dela — o funil de "todos os números" fica de fora. O resto responde 404, e a lista de funis também filtra.

Criar e configurar o funil

RotaEscopo
GET /v1/boards/templates — os modelos (etapas prontas e a regra da IA de cada uma)boards:read
POST /v1/boards — criarboards:write
PATCH /v1/boards/:id — configurar (só o que vier muda)
DELETE /v1/boards/:id — arquivar
curl -X POST https://api.anilcrm.com.br/v1/boards \
  -H "Authorization: Bearer $ANIL_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Loja", "template": "loja", "channelIds": ["ID_DO_NUMERO"],
        "captureNewLeads": true, "aiAutoMoveEnabled": true }'
CampoO que é
name, templateNome e o id do modelo. Obrigatórios ao criar.
channelIdsOs números do funil (pelo menos um). Quem atende esses números passa a ver o funil.
sectorIdOpcional: só quem é do setor vê. null no PATCH tira.
captureNewLeadsToda conversa nova desses números vira negócio na primeira etapa. Obrigatório ao criar.
aiAutoMoveEnabledA IA lê a conversa e muda o negócio de etapa sozinha (cada leitura gasta a cota de IA). Obrigatório ao criar.
columnsAs etapas, na ordem: [{ "id", "name", "color", "aiRule" }]. Ao criar, sem ela vêm as do modelo.
columns no PATCH é a lista INTEIRA. Etapa com id fica (e é renomeada), sem id nasce, e a que ficar de fora sai — os negócios dela vão para a primeira etapa que fica (nunca somem). Para renomear uma só, mande todas com os ids. Arquivar tira o funil da tela de todos, mas os negócios e o histórico ficam (o relatório de vendas não perde nada). Com a chave presa a números, o funil só pode usar números da chave.

10c. Base de conhecimento

O que o agente de IA consulta para responder: catálogo, preços, perguntas frequentes. Pela API, você mantém a base em dia a partir do seu sistema. Escopos knowledge:read (ver) e knowledge:write (acrescentar e tirar) — o segundo é novo (18/10/2026): crie uma chave com ele.

curl -X POST https://api.anilcrm.com.br/v1/knowledge-bases/ID/text \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Idempotency-Key: precos-2026-10" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Tabela de preços — outubro", "content": "Vestido azul: R$ 189…" }'
Muda o que a IA responde aos clientes, em segundos (o tempo de processar o texto). Texto velho não some sozinho: veja os documentos em GET /v1/knowledge-bases/:id e tire o antigo com DELETE /v1/knowledge-bases/:id/documents/:documentId. Até 50 mil caracteres por texto.

11. Mensagens da equipe

As conversas internas da aba Mensagens → Equipe: o que os colegas escreveram para você, direto ou em grupo. Serve para o seu assistente (ou automação) ler o que chegou e responder por você.

São só as SUAS conversas. A chave é pessoal: ela lê as conversas de que o administrador dono dela participa — e nunca a de dois colegas, nem sendo dono ou administrador. Conversa de que você não participa responde 404.
curl "https://api.anilcrm.com.br/v1/team/threads?unread=true" \
  -H "Authorization: Bearer SUA_CHAVE"

Para ler uma conversa, use o id dela. Vêm as 30 mais recentes (até 100 com pageSize), da mais antiga para a mais nova. Para as anteriores, mande before com o nextBefore da resposta; nextBefore: null quer dizer que acabou.

curl "https://api.anilcrm.com.br/v1/team/threads/THREAD_ID/messages?before=NEXT_BEFORE" \
  -H "Authorization: Bearer SUA_CHAVE"

Responder (só texto; replyToId, opcional, cita uma mensagem):

curl -X POST https://api.anilcrm.com.br/v1/team/threads/THREAD_ID/messages \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"content": "Pode dar o desconto."}'
O que acontece
Ler pela APINão marca como lida nem como entregue — quem mandou não vê diferença. Marcar é POST …/read.
ResponderSai em seu nome, na hora, com notificação para o colega — sem marca de que veio da integração. E marca a conversa como lida.
Conversa novaPOST /v1/team/dm com o userId do colega (de /v1/team/people): abre ou devolve a que já existe.

Fica de fora, de propósito: anexo, encaminhar, figurinha, criar grupo e as conversas com pessoas de outras empresas. Também não existe webhook dessas mensagens: o webhook é da empresa, e a conversa é sua.

12. Idempotência

Rede falha e bibliotecas HTTP repetem requisição sozinhas. Sem proteção, um retry de "enviar mensagem" vira mensagem duplicada no WhatsApp de uma pessoa real — dano visível e que não dá para desfazer.

Mande o cabeçalho Idempotency-Key com um valor único por operação (o id do pedido no seu sistema serve bem). Repetir a mesma chave devolve o mesmo resultado, sem executar de novo.

RotaAceita
POST /v1/conversations/:id/messagessim
POST /v1/conversations/:id/messages/mediasim
POST /v1/conversations/:id/messages/templatesim
POST /v1/conversations/:id/messages/schedulesim
POST /v1/conversations/:id/messages/schedule-chatbotsim
POST /v1/conversations/:id/messages/forwardsim
POST /v1/conversationssim
POST /v1/campaignssim
POST /v1/contactssim
POST /v1/chatbotssim
POST /v1/conversations/:id/run-chatbotsim
POST /v1/conversations/:id/notessim
POST /v1/team/threads/:threadId/messagessim
Regra
Quanto tempo vale24 horas.
O que conta como "a mesma"A mesma chave de API, o mesmo método, o mesmo caminho (com os ids) e o mesmo valor de Idempotency-Key. O mesmo valor numa rota diferente, ou para outra conversa, executa normalmente. O corpo não entra na conta: não reaproveite o valor para outra operação na mesma rota.
O que fica guardadoSó resposta de sucesso (2xx). Deu erro (400, 404, 409, 422, 5xx)? A chave é liberada: corrija e repita com o mesmo valor.
Repetiu enquanto a primeira roda409 — espere e tente de novo, não troque o valor.

13. Limites de uso

O limite é por chave, não por IP — sua integração sai de um servidor só e não seria justo dividir balde com terceiros. Janela de 1 minuto, e cada rota tem o seu balde: estourar o envio não trava a leitura. Requisição sem chave (ou com chave malformada) conta pelo IP.

RotaPor minuto
Leitura (contatos, conversas, uma conversa, janela, mensagens, etiquetas, campos de contato, agentes de IA, organização, campanhas, destinatários e totais de campanha, respostas de captura, base de conhecimento, simular chatbot, chatbots, equipe, funil e negócios)120
/v1/me, guia de chatbot, filtros de relatório, link de download, posts do Instagram, templates60
Escrita e exclusão de contato, procurar telefones, aplicar e remover etiqueta, pedir URL de upload, atribuir, devolver, finalizar, reabrir, transferir, nota interna, parar chatbot, IA na conversa, marcar como lida, cancelar agendamento, reagir, criar e mexer em negócio, marcar mensagem da equipe como lida60
Relatórios (overview, team, sources, sales, ai, calls, capture)30
Editar campanha, prévia do público, acrescentar e tirar da base de conhecimento, grupos do número, criar, editar e apagar etiqueta, criar, configurar e arquivar funil30
Importar etiquetas do WhatsApp10
Envio e agendamento de mensagem (texto, mídia, template, reenviar, localização, contato, botões, lista, botão com link, enquete), agendar chatbot, transcrever30
Abrir conversa30
Campanhas: criar, disparar, pausar, retomar, cancelar30
Chatbots e pastas: criar, editar, ligar, desligar, excluir, rodar numa conversa30
Mensagens da equipe: responder e abrir conversa30
Estourou, a resposta é 429. Toda resposta traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset (segundos até o balde encher de novo); o 429 traz também retry-after. Trate com espera progressiva.
Este limite protege a nossa infraestrutura, não o seu número. São coisas diferentes: caber no limite de 30 envios por minuto não significa que o WhatsApp vai achar o ritmo natural. Veja o aviso do envio de mensagem.

14. Páginas e formatos

As listas não têm todas o mesmo formato — confira a de cada rota. Datas vêm em ISO 8601 (UTC, com Z); as que você manda levam fuso (-03:00 para Brasília). Telefone é sempre só dígitos, com DDI: 5517999998888.

RotaRespostaComo andar
Contatos{ data, total, page, limit }page + limit
Conversas, campanhas{ data, total }page + pageSize
Chatbots{ items, total, page, limit }page + limit
Mensagens de uma conversa{ data, total }cursor: before = createdAt da mais antiga
Mensagens da equipe{ data, nextBefore }cursor: before = nextBefore (null = acabou)
Posts do Instagram{ items, nextCursor }cursor: after = nextCursor
Setores, equipe, canais, etiquetas, respostas rápidas, kanban, base, captura, linkslista simples [ … ]vem tudo

Ações sem nada a devolver (aplicar e remover etiqueta, apagar pasta) respondem 204, sem corpo. Criar responde 201.

15. Erros

Todo erro devolve JSON com error (a mensagem, em português, para gente ler). Pode vir junto: details (no 400, o problema de cada campo), problemas (no fluxo de chatbot) e code (um código fixo, para o seu programa decidir sem ler a mensagem — a lista está abaixo).

CódigoO que significa
400Corpo ou parâmetro inválido. Em fluxo de chatbot, vem junto problemas com tudo que corrigir.
401Chave ausente, malformada, revogada, expirada — ou o dono dela foi desativado ou rebaixado, ou a organização foi fechada. Todos respondem igual, para não revelar qual prefixo existe. Reativar o usuário ou reabrir a organização religa a chave sozinho.
403A chave é válida, mas (a) não tem o escopo da rota — a mensagem nomeia o que falta; ou (b) o X-Anil-Org enviado não é a organização da chave.
404Não existe ou está fora dos canais da chave. Os dois casos respondem igual, de propósito: distinguir permitiria descobrir o que existe sem ter acesso.
409Outra requisição com a mesma Idempotency-Key ainda está em andamento — ou o estado não permite a ação: canal desconectado (no envio), disparar campanha que já saiu, pausar o que não está rodando, retomar o que não está pausado, excluir chatbot ligado ou em uso, segundo chatbot de primeira mensagem no canal, rodar chatbot desligado, ligar a IA com a cota de IA acabada, cancelar agendamento que já saiu, mover negócio fechado, reabrir negócio aberto, editar campanha que já saiu do rascunho.
422Pedido válido que não dá para cumprir: janela de 24h fechada no canal Oficial (use template), template em canal não oficial, contato sem telefone, disparar campanha sem destinatários, sem conteúdo ou com canal desconectado, ligar um chatbot cujo fluxo gravado tem problema.
429Limite por minuto estourado.
5xxErro nosso. A mensagem é genérica de propósito; tente de novo com espera, e com Idempotency-Key nas rotas que enviam.
codeQuando
MEDIA_OUTSIDE_TENANTA mediaKey (ou o fileKey de um cabeçalho de template ou de uma mídia de campanha) não é um arquivo da sua organização. Suba o arquivo por POST /v1/media/upload-url e use a chave que ela devolver.

A lista de code cresce aos poucos — trate um code que você não conhece pelo status HTTP.

16. Webhooks

Em vez de ficar perguntando "tem novidade?", receba um POST assim que algo acontece. Cadastre o endpoint em Configurações → Webhooks (só dono ou administrador), escolha os eventos e guarde o segredo que aparece na criação (começa com whsec_) — ele também só é mostrado uma vez. A URL precisa ser https.

Eventos

EventoQuando sai
message.receivedO cliente mandou mensagem (em conversa individual ou grupo). É o evento de maior volume — só assine se for tratar.
message.sentSaiu uma mensagem pelo Anil: atendente, IA, chatbot, campanha, agendada ou API. Mensagem que falhou não conta; agendada avisa quando sai, não quando é agendada. O que é digitado direto no WhatsApp do celular não entra.
message.statusUma mensagem que saiu foi entregue, lida, ouvida (áudio) ou falhou. Só avanço: um "entregue" que chega atrasado, depois do "lida", não gera evento. Volume alto — cada envio gera dois ou três.
conversation.createdAbriu conversa com alguém: primeira mensagem de um número novo, pela tela, pela API, por comentário no Instagram, por página de captura ou pelo chatbot ("Chamar no WhatsApp"). Conversa aberta por campanha não avisa — são milhares de uma vez, e o message.sent de cada envio já conta a história.
conversation.assignedA conversa ficou com um atendente — pela tela, pela API, por um chatbot ou pela carteira do cliente.
conversation.transferredA conversa mudou de setor (e voltou para a fila dele, sem atendente).
conversation.resolvedO atendimento foi finalizado. Traz o resultado comercial (venda ou perda) quando houve.
capture.submittedAlguém concluiu uma página de captura (formulário) — também quando não deixou telefone.
deal.created · deal.moved · deal.won · deal.lost · deal.reopenedUm negócio do funil nasceu (tela, API ou captura), mudou de etapa (por gente ou pela IA do funil — byAi), foi ganho, perdido ou reaberto. Finalizar a conversa com venda ou perda também gera deal.won/deal.lost.
contact.createdEntrou um contato novo, um por vez: pela tela, pela API, pela primeira mensagem de um número novo, por comentário no Instagram, por página de captura ou pelo chatbot. Reativar um contato excluído também conta. Não disparam: importação por planilha, agenda do celular, membros de grupo e sincronização de histórico — são lotes de milhares de uma vez.
Os eventos message.sent, conversation.assigned, conversation.resolved e contact.created só passaram a sair em 17/10/2026. Antes disso a tela deixava assiná-los, mas só message.received era entregue. Ver o histórico.

O que chega

Um POST com Content-Type: application/json e este envelope — o que muda de um evento para outro é o data:

{
  "event": "message.received",
  "timestamp": "2026-10-17T14:02:11.402Z",
  "data": {
    "conversationId": "…", "messageId": "…", "channelId": "…",
    "type": "TEXT", "content": "Oi, ainda tem o vestido azul?",
    "isGroup": false, "externalId": "…",
    "contact": { "id": "…", "name": "Nadine", "phone": "5517999998888" }
  }
}
EventoCampos de data
message.receivedconversationId, messageId, channelId, type, content, isGroup, externalId, contact (id, name, phone — null em grupo e no Instagram)
message.sentos mesmos de cima, mais hasMedia, sentAt, origin (atendente, ia, chatbot ou automatico — campanha, saudação), viaApi (true quando saiu pela API) e agent ({ id, name } de quem enviou, ou null)
conversation.assignedconversationId, channelId, status, isGroup, contact, assignedTo ({ id, name }), sector, previousAssigneeId, actorUserId (quem atribuiu; null = o sistema), viaApi, e reason: "carteira" quando foi a carteira do cliente
message.statusmessageId, conversationId, channelId, externalId, status (DELIVERED, READ, PLAYED ou FAILED), at e, na falha, errorCode e errorMessage (os do WhatsApp)
conversation.createdconversationId, channelId, status, isGroup, contact, assignedTo, sector e origin: message, manual, api, instagram_comment, capture ou chatbot
conversation.transferredos mesmos da atribuição (o sector é o NOVO), mais fromSectorId e previousAssigneeId
conversation.resolvedos mesmos da atribuição, mais outcome: { result: "WON" | "LOST", amountCents, lossReason } ou null
capture.submittedformId, formTitle, submissionId, contactId (null sem telefone), phone, name, email, endScreenId (o desfecho), answers ([{ questionId, question, fieldKey, value }], na ordem do formulário), utm e submittedAt
deal.*dealId, boardId, boardName, columnId, columnName, status, title, valueCents, ownerUserId, conversationId, contact, source, actorUserId, viaApi; em deal.moved, fromColumnId e byAi; em deal.lost, lossReason e lossNote; em ganho e perda, closedAt
contact.createdcontactId, name, phone, email, instagramId, createdAt e origin: manual, api, message, instagram_comment, capture ou chatbot

O webhook avisa; o detalhe completo está na API. Com o conversationId ou o contactId na mão, busque o resto em /v1. Campos novos podem aparecer no data com o tempo — ignore o que você não conhece.

Cabeçalhos

CabeçalhoO que é
X-Anil-Signaturesha256= + o HMAC-SHA256 em hexadecimal (ver abaixo).
X-Anil-TimestampQuando assinamos, em segundos desde 1970.
X-Anil-EventO evento (o mesmo do corpo).
X-Anil-Delivery-IdId desta entrega. Uma retentativa chega com o mesmo id — use para não processar duas vezes.
User-AgentAnil-CRM-Webhook/1

Validar a assinatura

Valide sempre — sem isso qualquer um que descubra sua URL pode postar nela. A assinatura é o HMAC-SHA256, com o seu segredo, do texto {X-Anil-Timestamp}.{corpo cru}:

// Node.js — use o corpo CRU (os bytes que chegaram), antes de qualquer parse
const crypto = require('node:crypto')

function webhookValido(corpoCru, cabecalhos, segredo) {
  const ts = cabecalhos['x-anil-timestamp']
  const recebida = cabecalhos['x-anil-signature'] || ''
  // mais de 5 minutos: recuse (protege contra replay)
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const esperada = 'sha256=' + crypto.createHmac('sha256', segredo)
    .update(`${ts}.${corpoCru}`).digest('hex')
  // tamanhos diferentes: o timingSafeEqual lançaria erro
  if (recebida.length !== esperada.length) return false
  return crypto.timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada))
}
O timestamp entra no cálculo justamente para impedir replay: sem ele, um corpo capturado poderia ser reenviado para sempre e a assinatura continuaria conferindo. Não reformate o JSON antes de validar — um espaço a mais muda o HMAC.

Entrega e retentativa

Responda 2xx em até 15 segundos — processe depois, em fila sua. Qualquer outra resposta (ou demora) é falha, e tentamos de novo: 5 tentativas no total, com esperas de 10 s, 20 s, 40 s e 80 s (uns 2,5 minutos do primeiro ao último). A ordem de chegada não é garantida: use o timestamp do corpo para ordenar.

Quando 10 eventos seguidos esgotam as 5 tentativas, o endpoint é desligado sozinho e o sino do Anil avisa o dono e os administradores. Uma entrega que dá certo zera a conta. Arrumou? Religue em Configurações → Webhooks. O histórico de cada entrega (status, tentativas e o começo da resposta do seu servidor) fica lá.

O webhook é da organização inteira. A restrição de canal de uma chave de API não vale aqui: o endpoint recebe os eventos de todos os canais. Organização fechada não envia nada.

17. Conectar ao Claude (MCP)

O Anil expõe um servidor MCP, o padrão que o Claude usa para falar com sistemas externos. Com ele você conversa com o CRM em linguagem natural: "quantas conversas estão na fila do setor de vendas?", "resume o atendimento do contato X".

No Claude, adicione um conector com:

URL https://mcp.anilcrm.com.br/mcp/sua-organização

Autentique com a mesma chave de API, no cabeçalho Authorization: Bearer. A URL exata da sua organização aparece em Configurações → Chaves de API, ao lado da chave — copie as duas do mesmo lugar.

Administra mais de uma empresa? Use um conector por empresa. O Claude identifica conector pela URL, então dois conectores na mesma URL não coexistem — é para isso que existe o trecho da organização no fim do endereço. Com Difafá e S4R41VA ligadas ao mesmo tempo, dá para pedir comparações entre elas (“mensagens recebidas em cada uma no mês passado”): o assistente consulta as duas e junta os números.
A empresa continua vindo da CHAVE, não da URL. O trecho final do endereço é só conferência: se você configurar um conector da empresa A com a chave da empresa B, toda chamada falha com 403 em vez de agir na empresa errada em silêncio. O endereço rotula; quem autoriza é a chave.

Os endereços antigos — /mcp sem a organização, e o domínio mcp.msgflowapp.com.br — continuam funcionando para quem já tem um conector configurado.

São 103 ferramentas: ler contatos, conversas, mensagens, relatórios, agendamentos e campanhas (contatos e conversas também por etiqueta); criar, editar e excluir contato (inclusive marcar que a pessoa não quer receber) e procurar vários telefones; aplicar e ver etiquetas, e criar, editar, apagar e importar do WhatsApp as etiquetas da organização; atribuir e finalizar atendimento (registrando venda ou perda); ver uma conversa e a janela de 24h; parar o chatbot; ligar ou desligar a IA numa conversa; marcar como lida; listar os templates do número oficial; cancelar agendamento; mandar localização, cartão de contato, botões, lista, botão com link e enquete; reagir; transcrever um áudio; ver o funil e criar, editar, mover, ganhar, perder e reabrir negócio (e desfazer o movimento da IA); criar, configurar e arquivar funil; editar campanha, ver quantos ela atinge, os destinatários e os totais; ler as respostas das páginas de captura; ver a base de conhecimento, acrescentar e tirar texto; simular um chatbot; ver os grupos do número; relatório por atendente; enviar mensagem, arquivo e template; agendar mensagem ou chatbot; reenviar uma mensagem para outra conversa; abrir conversa; criar, disparar, pausar ou cancelar campanha; escrever nota interna (e salvar nas Notas do contato); ler e responder as suas mensagens da equipe; listar os posts do Instagram; criar, renomear e apagar pastas de chatbot; e montar, editar, ligar, desligar, excluir e testar chatbot — peça em português ("cria um chatbot que pergunta o nome e passa para Vendas") e o assistente lê o guia do formato antes de montar.

Use uma chave separada e estreita para o MCP. O assistente enxerga tudo o que a chave enxerga — inclusive o conteúdo das conversas. Marque só os escopos que você quer que ele alcance, e não reaproveite a chave da sua integração de sistema.
Com campaigns:write na chave, o assistente pode disparar campanha para milhares de pessoas. O disparo não tem desfazer. As ferramentas que mudam alguma coisa (enviar, atribuir, etiquetar, editar, disparar…) são marcadas para o Claude pedir sua confirmação antes de executar — só "marcar mensagem da equipe como lida" e "preparar envio de arquivo" não pedem. Mas a decisão de dar esse escopo ao MCP é sua: se não quiser, deixe a caixa desmarcada e ele continua podendo ler e acompanhar campanhas.
Com chatbots:write na chave, o assistente pode ligar um chatbot que responde sozinho aos seus clientes. Ligar também pede sua confirmação e a resposta diz quando ele vai disparar — confira antes de aprovar. Sem esse escopo, ele continua podendo ler os chatbots.
O MCP é um cliente desta mesma API. Ele não tem atalho para o banco e não faz nada que a chave não permita — escopo faltando vira erro, igual a qualquer integração.

Histórico de mudanças

O /v1 só muda acrescentando: campo novo na resposta, rota nova, parâmetro opcional novo. Quando um comportamento muda — mesmo para consertar —, ele aparece aqui.

DataO que mudou
02/11/2026 Etiquetas: criar (POST /v1/labels), editar (PATCH /v1/labels/:id), apagar (DELETE /v1/labels/:id) e importar as do WhatsApp do número (POST /v1/labels/sync-whatsapp), com o escopo novo labels:manage — labels:write continua só aplicando e removendo. Etiqueta de setor recusa (400) setor de outra organização.
Funil: criar (POST /v1/boards), configurar (PATCH /v1/boards/:id) e arquivar (DELETE /v1/boards/:id), com o escopo novo boards:write; os modelos (GET /v1/boards/templates), quem pode ser responsável (GET /v1/boards/:id/people), ?mine=true no funil e o "Desfazer" da IA (POST /v1/deals/:id/undo-ai).
Agendar chatbot: POST /v1/conversations/:id/messages/schedule-chatbot. MCP: 103 ferramentas.
18/10/2026 Campanhas: editar o rascunho (PATCH), prévia do público, destinatários e totais. Corrigido: o exemplo de criar mostrava segmentLabelIds, que a API não lia — agora é recipientIds, e o nome antigo é aceito como sinônimo.
Base de conhecimento: ver a base, acrescentar texto e tirar documento (escopo novo knowledge:write).
Também: respostas das páginas de captura, simular chatbot, grupos do número, relatório por atendente (/v1/reports/team) e o webhook capture.submitted.
Chave presa a números: a lista de canais, os relatórios e a agenda de mensagens passaram a seguir os números da chave (antes mostravam a empresa inteira).
Funil de negócios: escopos novos deals:read/deals:write; ver o funil, ver/criar/editar/mover/ganhar/perder/reabrir negócio, os negócios da conversa; webhooks deal.created, deal.moved, deal.won, deal.lost, deal.reopened. GET /v1/boards passou a filtrar pelos números da chave.
Mensagens: localização, cartão de contato, botões, lista, botão com link e enquete (…/messages/<tipo>); reagir e transcrever áudio. Webhook message.status (entregue, lida, ouvida, falhou).
Atendimento: GET /v1/conversations/:id e …/window (janela de 24h); resolve aceita outcome (venda ou perda); stop-chatbot; PUT …/ai-agent (ligar e desligar a IA, com a trava de cota); …/read (marcar como lida); GET /v1/ai-agents.
Templates: GET /v1/channels/:id/templates.
Agenda: DELETE /v1/scheduled-messages/:id.
Contatos: DELETE /v1/contacts/:id, GET /v1/contact-fields, POST /v1/contacts/lookup.
Webhooks novos: conversation.created e conversation.transferred. MCP: 92 ferramentas.
17/10/2026 Webhooks: message.sent, conversation.assigned, conversation.resolved e contact.created passaram a ser entregues (antes, só message.received saía). message.received ganhou contact.phone.
Limite de uso: passou a contar por chave de fato — antes, por um defeito, contava pelo IP de quem chamava.
Idempotência: o mesmo valor de Idempotency-Key em outra rota (ou para outra conversa) executa; antes devolvia a resposta da primeira. Erro deixou de ficar guardado.
Lista de conversas com chave restrita a canal: a página vem cheia e o total certo (antes vinha curta).
Arquivos: mediaKey/fileKey de outra organização é recusado com 400 MEDIA_OUTSIDE_TENANT.
Erros passaram a trazer code quando existe; erro interno (5xx) não expõe mais a mensagem técnica.
Endereço novo: api.anilcrm.com.br e mcp.anilcrm.com.br (os antigos seguem). MCP: 54 ferramentas.
16/10/2026Template enviado pela API aparece no chat com o texto do template (antes, só o nome).
15/10/2026Chatbot: editar grava o rascunho; o /activate publica. run-chatbot aceita "rascunho": true. Validação nas perguntas (askInput com valid/invalid) e o nó nota.
13/10/2026Relatórios aceitam vários canais, atendentes e setores e o timeMode (sem ele, segue o relógio corrido).
12/10/2026Mensagens da equipe (/v1/team/*); conversa aberta pela API nasce sem atendente; lista de conversas sem repetidas; posts do Instagram; pastas de chatbot; ligado/situacao nos chatbots.
11/10/2026Nota interna (POST /v1/conversations/:id/notes).
10/10/2026Chatbots pela API: criar, editar, ligar, desligar, excluir, rodar numa conversa e o guia.
07/10/2026Agendar mensagem (…/messages/schedule).