Referência da API
As 17 chamadas da API da Bia CRM, grupo a grupo, com o exemplo de cada uma, e os 31 eventos que chegam por webhook.
Comece por aqui
API REST para integrar mensagens WhatsApp, contatos, conversas e CRM ao seu sistema.
- Endereço base
https://conta.biacrm.app/api/v1- Autenticação
Authorization: Bearer sk_live_.... O token é da organização (sem filtro de agente ou departamento) e só aparece inteiro ao criar ou girar.- Escopos
um token pode ter acesso total ou só os escopos escolhidos:
contacts:read,contacts:write,pipelines:write,messaging:read,messaging:write,automations:write. Cada rota diz o escopo que pede; fora dele,403 SCOPE_REQUIRED.- Validade e IPs
o token pode ter validade (vencido,
401 TOKEN_EXPIRED) e uma lista de IPs ou faixas aceitos (fora dela,403 IP_NOT_ALLOWED). Ao girar, o segredo anterior pode valer por até 24 horas.- Limite
120 requisições por minuto por token e 600 por minuto somando os tokens da organização. Cabeçalhos em toda resposta:
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset(segundos) eRateLimit-Policy; no429, tambémRetry-After, e o corpo diz emscopequal limite encheu. OsX-RateLimit-*continuam.- Erros
{ "error": "<frase>", "code": "<CÓDIGO>", "request_id": "<uuid>" }. Trate pelocode; a frase pode mudar.- Correlação
toda resposta inclui
X-Request-Id(UUID), o mesmorequest_iddo erro. É por ele que a chamada aparece no registro de uso do painel.
A referência sai da especificação OpenAPI 3.1.0 de Bia CRM API, versão 1.7.0.
Token 1
Conferir a chave: de quem é, o que alcança e até quando vale.
GET/token
Conferir o token
Diz de qual organização o token é, os escopos dele (null = acesso total), a validade e as rotas que alcança. Qualquer token entra, com ou sem escopos: use para testar a chave antes de integrar. O limite vem nos cabeçalhos RateLimit-*.
Respostas
200O token é válido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.
curl --request GET 'https://conta.biacrm.app/api/v1/token' \
--header 'Authorization: Bearer SEU_TOKEN'{
"success": true,
"data": {
"organization": {
"id": 163,
"name": "Clínica Exemplo"
},
"token": {
"id": 12,
"name": "ERP",
"scopes": [
"contacts:read"
],
"expiresAt": null,
"usingPreviousSecret": false
},
"routes": [
"GET /contacts",
"GET /contacts/{id}"
]
}
}Mensagens 2
Envio e status de mensagens WhatsApp.
POST/send
Enviar mensagem
Escopo messaging:write
Envia texto, imagem, vídeo, documento ou áudio. O instanceName é o nome de um número conectado no painel. Em sucesso, dispara webhook message.sent.
Corpo
instanceNameobrigatóriostringExemplo: minha-instancia
numberobrigatóriostringExemplo: 5511999999999
typeobrigatóriostringtext image video document audio
messagestringmediaUrlstringfileNamestringExemplo: proposta.pdf
mimetypestringExemplo: image/png
Respostas
200Mensagem enviada400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/send' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"instanceName":"minha-instancia","number":"5511999999999","type":"text","message":"texto","mediaUrl":"texto","fileName":"proposta.pdf","mimetype":"image/png"}'{
"success": true,
"data": {
"key": {
"id": "3EB0C767D26A8D1F7A2B",
"fromMe": true
},
"status": "PENDING"
}
}GET/messages/{id}
Consultar status da mensagem
Escopo messaging:read
Retorna status de entrega/leitura e metadados de uma mensagem pelo ID do WhatsApp (data.key.id retornado ao enviar).
Parâmetros
idobrigatóriostring · no caminhoID da mensagem (ex.: retornado em data.key.id ao enviar).
Respostas
200Status da mensagem400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request GET 'https://conta.biacrm.app/api/v1/messages/123' \
--header 'Authorization: Bearer SEU_TOKEN'{
"success": true,
"data": {
"id": "texto",
"chatId": 1,
"phone": "texto",
"instanceId": 1,
"fromMe": true,
"type": "texto",
"status": "sent",
"timestamp": "texto",
"source": "texto",
"sourceLabel": "texto",
"errorMessage": "texto",
"preview": "texto"
}
}Contatos 5
CRUD de contatos da organização.
GET/contacts
Listar contatos
Escopo contacts:read
Lista contatos da organização (escopo completo da org, sem filtro de agente).
Parâmetros
pageinteger · na consultalimitinteger · na consultaphonestring · na consultaFiltrar por prefixo do telefone (apenas dígitos).
qstring · na consultaBusca pelo nome, pelo telefone ou pelo valor de um campo (o e-mail), com página.
statusstring · na consultaactive: nem arquivado nem bloqueado. Sem ele, todos.
active archived blocked unarchived
Respostas
200Lista paginada400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request GET 'https://conta.biacrm.app/api/v1/contacts' \
--header 'Authorization: Bearer SEU_TOKEN'{
"success": true,
"data": [
{
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 120
}
}POST/contacts
Criar contato
Escopo contacts:write
Cria contato + conversa para um telefone e instância WhatsApp. Dispara webhook contact.created quando o contato é novo.
Corpo
phoneobrigatóriostringExemplo: 5511999999999
nameobrigatóriostringExemplo: Maria Silva
instanceNameobrigatóriostringExemplo: minha-instancia
assignedUserIdintegerassignedDepartmentIdintegerfunnelStageIdintegertagIdsinteger[]customDataobjectRespostas
201Contato criado400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado409Contato já existe429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/contacts' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"phone":"5511999999999","name":"Maria Silva","instanceName":"minha-instancia","assignedUserId":1,"assignedDepartmentId":1,"funnelStageId":1,"tagIds":[1],"customData":null}'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
}POST/contacts/batch
Criar ou atualizar contatos em quantidade
Escopo contacts:write
Até 100 por chamada, na ordem, upsert pelo telefone na instância. O contato que já existe só muda se o nome ou o customData mudou; o customData do lote junta com o gravado. Um resultado por linha.
Corpo
instanceNameobrigatóriostringcontactsobrigatórioobject[]contacts[].phoneobrigatóriostringcontacts[].nameobrigatóriostringcontacts[].customDataobjectRespostas
200Um resultado por linha400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/contacts/batch' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"instanceName":"texto","contacts":[{"phone":"texto","name":"texto","customData":null}]}'{
"success": true,
"results": [
{
"index": 1,
"status": "created",
"contactId": 1,
"code": "INVALID_PHONE"
}
]
}GET/contacts/{id}
Buscar contato
Escopo contacts:read
Parâmetros
idobrigatóriointeger · no caminhoRespostas
200Contato encontrado400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request GET 'https://conta.biacrm.app/api/v1/contacts/123' \
--header 'Authorization: Bearer SEU_TOKEN'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
}PUT/contacts/{id}
Atualizar contato
Escopo contacts:write
Parâmetros
idobrigatóriointeger · no caminhoCorpo
namestringassignedUserIdintegerassignedDepartmentIdintegerfunnelStageIdintegertagIdsinteger[]customDataobjectTroca o objeto inteiro (não junta): mande o que já existe junto.
archivedbooleantrue arquiva; false desarquiva.
blockedbooleantrue bloqueia (a mensagem nova dele não entra na Inbox); false desbloqueia.
Respostas
200Contato atualizado400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request PUT 'https://conta.biacrm.app/api/v1/contacts/123' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"name":"texto","assignedUserId":1,"assignedDepartmentId":1,"funnelStageId":1,"tagIds":[1],"customData":null,"archived":true,"blocked":true}'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
}Conversas 3
Criar, buscar e sincronizar conversas.
GET/conversations
Buscar conversa por telefone
Escopo messaging:read
Retorna conversas da organização para o número informado. Use instanceName para filtrar uma instância.
Parâmetros
phoneobrigatóriostring · na consultainstanceNamestring · na consultaRespostas
200Conversas encontradas400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request GET 'https://conta.biacrm.app/api/v1/conversations' \
--header 'Authorization: Bearer SEU_TOKEN'{
"success": true,
"data": [
{
"id": 1,
"chatId": 1,
"phone": "texto",
"jid": "texto",
"name": "texto",
"instanceId": 1,
"instanceName": "texto",
"contactId": 1,
"contact": {
"id": null,
"name": null,
"phone": null,
"jid": null,
"chatId": null,
"instanceId": null,
"instanceName": null,
"assignedUserId": null,
"assignedDepartmentId": null,
"funnelStageId": null,
"customData": null,
"archived": null,
"archivedAt": null,
"blocked": null,
"blockedAt": null,
"createdAt": null,
"updatedAt": null
},
"lastMessageText": "texto",
"lastMessageTimestamp": "texto",
"unreadCount": 1
}
]
}POST/conversations
Criar conversa
Escopo messaging:write
Cria conversa + contato (mesmo contrato de criar contato). Retorna alreadyExisted: true se já existir. Novo contato dispara contact.created.
Corpo
phoneobrigatóriostringExemplo: 5511999999999
nameobrigatóriostringExemplo: Maria Silva
instanceNameobrigatóriostringExemplo: minha-instancia
assignedUserIdintegerassignedDepartmentIdintegerfunnelStageIdintegertagIdsinteger[]customDataobjectRespostas
200Conversa já existia201Conversa criada400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado409Conflito ao criar contato429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/conversations' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"phone":"5511999999999","name":"Maria Silva","instanceName":"minha-instancia","assignedUserId":1,"assignedDepartmentId":1,"funnelStageId":1,"tagIds":[1],"customData":null}'{
"success": true,
"alreadyExisted": true,
"data": {
"id": 1,
"chatId": 1,
"phone": "texto",
"jid": "texto",
"name": "texto",
"instanceId": 1,
"instanceName": "texto",
"contactId": 1,
"contact": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
},
"lastMessageText": "texto",
"lastMessageTimestamp": "texto",
"unreadCount": 1
}
}POST/conversations/{id}/sync
Sincronizar mensagens
Escopo messaging:write
Importa mensagens históricas do WhatsApp para a conversa (id = chatId).
Parâmetros
idobrigatóriointeger · no caminhoID da conversa (chatId)
Corpo
limitintegerRespostas
200Sync concluído400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/conversations/123/sync' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"limit":1}'{
"success": true,
"data": {
"chatId": 1,
"imported": 1,
"skipped": 1,
"total": 1
}
}CRM 4
Etapa do funil, responsável e tags.
PUT/contacts/{id}/stage
Mover etapa do funil
Escopo pipelines:write
Atualiza funnelStageId do contato. Dispara webhook contact.stage_changed.
Parâmetros
idobrigatóriointeger · no caminhoCorpo
stageIdobrigatóriointegerID da etapa ou null para remover.
Respostas
200Etapa atualizada400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request PUT 'https://conta.biacrm.app/api/v1/contacts/123/stage' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"stageId":1}'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
},
"stageName": "texto"
}PUT/contacts/{id}/assignee
Atribuir responsável
Escopo contacts:write
Define assignedUserId. userId: null remove o responsável. Dispara contact.assigned ou contact.unassigned.
Parâmetros
idobrigatóriointeger · no caminhoCorpo
userIdobrigatóriointegerID do usuário ou null para desatribuir.
Respostas
200Responsável atualizado400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request PUT 'https://conta.biacrm.app/api/v1/contacts/123/assignee' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"userId":1}'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
}POST/contacts/{id}/tags
Adicionar tag
Escopo contacts:write
Vincula uma tag existente ao contato. O webhook contact.tag_added sai quando a tag de fato entra no contato: repetir a chamada com a tag já vinculada não dispara de novo.
Parâmetros
idobrigatóriointeger · no caminhoCorpo
tagIdobrigatóriointegerRespostas
200Tag adicionada400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/contacts/123/tags' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"tagId":1}'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
}DELETE/contacts/{id}/tags/{tagId}
Remover tag
Escopo contacts:write
Remove vínculo da tag. O webhook contact.tag_removed sai quando a tag de fato sai do contato: remover uma tag que não estava vinculada não dispara.
Parâmetros
idobrigatóriointeger · no caminhotagIdobrigatóriointeger · no caminhoRespostas
200Tag removida400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request DELETE 'https://conta.biacrm.app/api/v1/contacts/123/tags/123' \
--header 'Authorization: Bearer SEU_TOKEN'{
"success": true,
"data": {
"id": 1,
"name": "texto",
"phone": "texto",
"jid": "texto",
"chatId": 1,
"instanceId": 1,
"instanceName": "texto",
"assignedUserId": 1,
"assignedDepartmentId": 1,
"funnelStageId": 1,
"customData": null,
"archived": true,
"archivedAt": "texto",
"blocked": true,
"blockedAt": "texto",
"createdAt": "texto",
"updatedAt": "texto"
}
}Formulários 1
Ingestão de lead a partir de um formulário cadastrado na organização.
POST/forms/{key}/submissions
Registrar envio de formulário
Escopo contacts:write
Ingere um lead a partir de um formulário cadastrado na organização. {key} é a chave da integração no app. Idempotente por idempotencyKey.
Parâmetros
keyobrigatóriostring · no caminhoChave da integração de formulário.
Corpo
idempotencyKeyobrigatóriostringExemplo: form-2026-09-02-001
phoneobrigatóriostringExemplo: 5511999999999
nameobrigatóriostringExemplo: Maria Silva
fieldsobjectutmobjectreferrerstringlandingPagestringRespostas
200Envio já processado (idempotente)201Envio novo400Payload inválido401Não autorizado: token ausente, inválido, revogado (UNAUTHORIZED) ou vencido (TOKEN_EXPIRED)403Permissão negada: o token não tem o escopo da rota (SCOPE_REQUIRED), o IP não está na lista do token (IP_NOT_ALLOWED) ou o plano não inclui o recurso404Não encontrado429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual emscope.500Erro interno
curl --request POST 'https://conta.biacrm.app/api/v1/forms/sua-chave/submissions' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"idempotencyKey":"form-2026-09-02-001","phone":"5511999999999","name":"Maria Silva","fields":null,"utm":null,"referrer":"texto","landingPage":"texto"}'{
"success": true,
"duplicated": true,
"contactId": 1,
"chatId": 1,
"created": true,
"opportunityAction": "texto",
"submissionId": 1
}Canal API 2
Conexão em que um sistema externo entrega e recebe as mensagens do WhatsApp. O endereço de entrada recebe os eventos dele; o message.outgoing é o que a plataforma manda a ele.
POST/canal/{token}/eventos
Receber evento do sistema externo
Sem token: o endereço do canal autentica
O sistema externo manda aqui as mensagens dos clientes, as respostas dadas por ele e o andamento das mensagens enviadas pela plataforma.
- Autenticação: o
tokendo caminho (o endereço completo aparece uma vez, na criação do canal). Sem chavesk_live_. - Assinatura:
X-Webhook-Timestamp(segundos) eX-Webhook-Signature: v1=<HMAC-SHA256 hex de "{timestamp}.{body}">com o segredo do canal. Exigida na entrada enquanto a opção do canal estiver ligada (tolerância de 5 min); sempre presente na saída. - Corpo JSON de até 1 MB. Mídia vem por link https público (até 50 MB); a plataforma baixa e guarda.
- Idempotente por
id: o mesmo evento repetido respondeduplicate: true. Evento que falhou com 503 é reprocessado ao reenviar. - Limite: 600 eventos por minuto por canal.
Parâmetros
tokenobrigatóriostring · no caminhoToken do canal (ch_…).
X-Webhook-Timestampstring · no cabeçalhoX-Webhook-Signaturestring · no cabeçalhoCorpo
Respostas
200Evento aceito, repetido (duplicate: true) ou teste400Formato inválido (issuesaponta o campo) ou link de mídia recusado. Corrigir; não reenviar igual.401Endereço desconhecido ou assinatura ausente ou inválida413Corpo acima de 1 MB ou mídia acima de 50 MB429Mais de 600 eventos por minuto no canal. Reenviar depois.503Falha passageira. Reenviar o mesmo evento.
curl --request POST 'https://conta.biacrm.app/api/v1/canal/ch_SEU_TOKEN/eventos' \
--header 'Content-Type: application/json' \
--data '{"id":"evt_1001","type":"message.received","occurredAt":"2026-10-06T14:00:00Z","data":{"messageId":"wamid.ABC123","from":{"phone":"+5541999998888","name":"Maria Souza"},"type":"text","text":"Oi, quero um orçamento"}}'{
"received": true,
"duplicate": true,
"test": true,
"messageId": "texto",
"error": "texto",
"issues": [
{
"path": "texto",
"message": "texto"
}
]
}SAImessage.outgoing
Mensagem que sai para o sistema externo (documentação)
Só documentação: esta rota não existe na API. Descreve o POST JSON que a plataforma faz no endereço do sistema externo cadastrado no Canal API, a cada mensagem enviada pela IA, por um atendente ou por uma automação.
- Assinatura:
X-Webhook-Timestamp(segundos) eX-Webhook-Signature: v1=<HMAC-SHA256 hex de "{timestamp}.{body}">com o segredo do canal. Exigida na entrada enquanto a opção do canal estiver ligada (tolerância de 5 min); sempre presente na saída. - Cabeçalhos:
X-Webhook-Id(id do evento) eIdempotency-Key(odata.messageId, igual em todas as tentativas). - Responda
2xxem até 10 s quando aceitar a mensagem; pode devolver{ "externalId": "…" }. 5xx,408,429ou sem resposta: novas tentativas por cerca de 20 a 30 minutos. Outros4xxe redirecionamentos: a mensagem fica como falha na conversa.- Depois, informe o andamento com
message.statusno endereço de entrada, usando o mesmomessageId.
Corpo
idobrigatóriostringId do evento (evt_…), também em X-Webhook-Id.
typeobrigatóriostringmessage.outgoing channel.test
occurredAtobrigatóriostringchannelobrigatórioobjectchannel.idintegerchannel.namestringdataobrigatórioobjectdata.messageIdobrigatóriostringUse em message.status e como chave de idempotência.
data.toobrigatórioobjectdata.typeobrigatóriostringtext image video document audio
data.textstring | nulldata.mediaobject ou nulldata.replyTostring | null{
"id": "evt_5b2f0c",
"type": "message.outgoing",
"occurredAt": "2026-10-06T14:00:05Z",
"channel": {
"id": 42,
"name": "Atendimento"
},
"data": {
"messageId": "api:42:out:9f1c",
"to": {
"phone": "+5541999998888"
},
"type": "text",
"text": "Olá, Maria! Já te mando o orçamento.",
"media": null,
"replyTo": null
}
}Webhooks 31 eventos
Eventos em tempo real entregues via POST na URL HTTPS que você cadastra. Não são rotas REST: é a documentação do payload que seu servidor recebe. Inclui mensagens WhatsApp, CRM e ciclo de atendimento.
Configuração
- Nos Webhooks do painel, cadastre uma URL HTTPS.
- Selecione os eventos desejados (ou todos).
- Copie o secret
whsec_...exibido uma única vez ao criar ou rotacionar. - Implemente validação HMAC no seu servidor (ver schema
WebhookSignatureVerification).
Entrega
- Método:
POSTcomContent-Type: application/json - Headers:
X-Webhook-Id,X-Webhook-Timestamp,X-Webhook-Signature - Corpo: envelope
OutboundWebhookEnvelope - Timeout: 10s por tentativa
- Retries: backoff exponencial
min(3600, 2^n × 5)s, até 8 tentativas - Entregas: cada tentativa fica na lista de entregas do webhook, no painel, com o corpo e a resposta
Eventos da plataforma
Os eventos desta documentação (message.*, contact.*, conversation.*) são da plataforma: chegam já processados, com os nomes e o formato daqui, e não dependem do provedor do WhatsApp nem dos nomes dele.
message.receivedMensagem recebida (inbound)
Quando dispara: Mensagem do cliente recebida pelo WhatsApp, já processada. Não é o evento bruto do provedor do WhatsApp: é evento da plataforma.
Os campos de data
message_idstringID da mensagem no WhatsApp.
chat_idintegerID da conversa (chatId).
remote_jidstringJID WhatsApp do contato.
instancestringNome da instância/canal.
connectionobjectA conexão que recebeu a mensagem: o nome, se é a API oficial e o canal (whatsapp, instagram, messenger ou webchat).
connection.idintegerconnection.namestringconnection.officialbooleanconnection.channelstringwhatsapp instagram messenger webchat
textstringmessage_typestringExemplo: conversation
timestampstring{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "message.received",
"data": {
"message_id": "3EB0C1D2",
"chat_id": 42,
"remote_jid": "5511999999999@s.whatsapp.net",
"instance": "minha-instancia",
"connection": {
"id": 7,
"name": "Loja Centro",
"official": false,
"channel": "whatsapp"
},
"text": "Olá!",
"message_type": "conversation",
"timestamp": "2026-06-20T12:00:00.000Z"
}
}message.sentMensagem enviada (outbound)
Quando dispara: Mensagem enviada com sucesso pela plataforma (API, inbox, automação, campanha).
Os campos de data
message_idstringchat_idintegerremote_jidstringtextstringmessage_typestringstatusstringsent delivered read pending error
sourcestringOrigem: human, api, automation, campaign, ai…
timestampstringinternalbooleantrue na nota interna escrita pela API v1: só a equipe vê, nada sai para o contato.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "message.sent",
"data": {
"message_id": "3EB0C1D3",
"chat_id": 42,
"remote_jid": "5511999999999@s.whatsapp.net",
"text": "Resposta automática",
"message_type": "conversation",
"status": "sent",
"source": "api",
"timestamp": "2026-06-20T12:00:01.000Z"
}
}message.status_updatedStatus da mensagem atualizado
Quando dispara: Atualização de entrega/leitura (sent, delivered, read, error) vinda do provedor do WhatsApp.
Os campos de data
message_idstringstatusstringsent delivered read error pending
remote_jidstringinstancestring{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "message.status_updated",
"data": {
"message_id": "3EB0C1D3",
"status": "delivered",
"remote_jid": "5511999999999@s.whatsapp.net",
"instance": "minha-instancia"
}
}message.deletedMensagem apagada
Quando dispara: A mensagem foi apagada para todos: pelo contato no aparelho (deleted_by: contact) ou pela equipe (operator, com o nome de quem apagou). O conteúdo segue guardado na plataforma e a leitura da conversa traz a marca deleted. Sai uma vez por mensagem.
Os campos de data
message_idstringchat_idintegerremote_jidstring | nullfrom_mebooleantrue quando a mensagem apagada saiu da casa.
deleted_bystringcontact operator system
deleted_by_namestring | nullQuem da equipe apagou (só em operator).
deleted_atstring{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "message.deleted",
"data": {
"message_id": "3EB0C1D3",
"chat_id": 42,
"remote_jid": "5511999999999@s.whatsapp.net",
"from_me": false,
"deleted_by": "contact",
"deleted_by_name": null,
"deleted_at": "2026-06-20T12:05:00.000Z"
}
}message.reactionReação a uma mensagem
Quando dispara: Alguém reagiu a uma mensagem da conversa, ou tirou a reação (emoji: null, action: remove): a equipe (from_me: true, com quem reagiu, pela tela ou pela API v1) ou o contato no aparelho. A equipe tem uma reação por número, como no WhatsApp: a nova troca a anterior. A leitura das mensagens traz as reações de cada uma.
Os campos de data
message_idobrigatóriostringA mensagem que recebeu (ou perdeu) a reação.
chat_idobrigatóriointegercontact_idinteger | nullemojiobrigatóriostring | nullnull quando a reação saiu.
actionobrigatóriostringadd remove
from_meobrigatóriobooleantrue na reação da equipe (uma por número).
reacted_by_user_idinteger | nullQuem da equipe reagiu (só na da equipe pela plataforma).
reacted_by_namestring | nullO nome de quem reagiu: a pessoa da equipe ou o contato.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "message.reaction",
"data": {
"message_id": "3EB0C1D3",
"chat_id": 42,
"contact_id": 61,
"emoji": "👍",
"action": "add",
"from_me": true,
"reacted_by_user_id": 7,
"reacted_by_name": "Ana"
}
}contact.createdContato criado
Quando dispara: Novo contato CRM: API v1, UI, ou primeiro inbound WhatsApp em chat sem contato (contact.created).
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
namestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.created",
"data": {
"entity_type": "contact",
"entity_id": "61",
"name": "Maria Silva",
"chatId": 42
}
}contact.stage_changedEtapa do funil alterada
Quando dispara: CRM ou PUT /contacts/{id}/stage na API v1.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
stageIdintegerstageNamestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.stage_changed",
"data": {
"entity_type": "contact",
"entity_id": "61",
"stageId": 3,
"stageName": "Negociação",
"chatId": 42
}
}contact.tag_addedTag adicionada
Quando dispara: CRM ou POST /contacts/{id}/tags na API v1.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
tagIdintegertagNamestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.tag_added",
"data": {
"entity_type": "contact",
"entity_id": "61",
"tagId": 5,
"tagName": "VIP",
"chatId": 42
}
}contact.tag_removedTag removida
Quando dispara: CRM ou DELETE /contacts/{id}/tags/{tagId} na API v1.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
tagIdintegertagNamestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.tag_removed",
"data": {
"entity_type": "contact",
"entity_id": "61",
"tagId": 5,
"tagName": "VIP",
"chatId": 42
}
}contact.assignedResponsável atribuído
Quando dispara: Inbox/CRM ou PUT /contacts/{id}/assignee com userId preenchido.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
targetUserIdintegeragentNamestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.assigned",
"data": {
"entity_type": "contact",
"entity_id": "61",
"targetUserId": 7,
"agentName": "João",
"chatId": 42
}
}contact.unassignedResponsável removido
Quando dispara: Inbox/CRM ou PUT /contacts/{id}/assignee com userId: null.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
targetUserIdintegeragentNamestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.unassigned",
"data": {
"entity_type": "contact",
"entity_id": "61",
"targetUserId": null,
"chatId": 42
}
}contact.department_changedDepartamento alterado
Quando dispara: Atribuição de departamento no CRM/inbox.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
departmentIdintegerdepartmentNamestringchatIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.department_changed",
"data": {
"entity_type": "contact",
"entity_id": "61",
"departmentId": 2,
"departmentName": "Comercial",
"chatId": 42
}
}contact.mergedContato unificado (fusão de duplicado)
Quando dispara: Um contato duplicado foi fundido na pessoa canônica (reconciliador determinístico ou fusão confirmada na tela/MCP). entity_id é o contato de origem, que vira lápide: guarde canonicalContactId e passe a usá-lo. Um evento por contato de origem.
Os campos de data
entity_typestringExemplo: contact
entity_idstringContato de origem (lápide).
Exemplo: 75
canonicalContactIdintegerExemplo: 61
sourceContactIdintegerExemplo: 75
organizationIdintegerExemplo: 1
methodstringdeterministic_phone deterministic_email external_id manual
batchIdstringLote da fusão (o desfazer é por lote).
mergeIdintegermergedAtstringSó em contact.merged.
undoneAtstringSó em contact.merge_undone.
actorUserIdinteger | nullQuem confirmou (fusão manual ou desfazer); nulo quando foi o reconciliador.
conversationsRepointedintegeropportunitiesRepointedintegerrolestringsource
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.merged",
"data": {
"entity_type": "contact",
"entity_id": "75",
"canonicalContactId": 61,
"sourceContactId": 75,
"organizationId": 1,
"method": "deterministic_phone",
"batchId": "6f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
"mergeId": 12,
"mergedAt": "2026-06-20T12:00:00.000Z",
"actorUserId": null,
"conversationsRepointed": 1,
"opportunitiesRepointed": 1,
"role": "source"
}
}contact.merge_undoneFusão de contato desfeita
Quando dispara: O lote de fusão foi desfeito: o contato de origem (entity_id) volta a existir sozinho, com o que era dele. Um evento por contato de origem.
Os campos de data
entity_typestringExemplo: contact
entity_idstringContato de origem (lápide).
Exemplo: 75
canonicalContactIdintegerExemplo: 61
sourceContactIdintegerExemplo: 75
organizationIdintegerExemplo: 1
methodstringdeterministic_phone deterministic_email external_id manual
batchIdstringLote da fusão (o desfazer é por lote).
mergeIdintegermergedAtstringSó em contact.merged.
undoneAtstringSó em contact.merge_undone.
actorUserIdinteger | nullQuem confirmou (fusão manual ou desfazer); nulo quando foi o reconciliador.
conversationsRepointedintegeropportunitiesRepointedintegerrolestringsource
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "contact.merge_undone",
"data": {
"entity_type": "contact",
"entity_id": "75",
"canonicalContactId": 61,
"sourceContactId": 75,
"organizationId": 1,
"method": "manual",
"batchId": "6f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
"mergeId": 12,
"undoneAt": "2026-06-21T09:30:00.000Z",
"actorUserId": 7,
"role": "source"
}
}conversation.service_startedAtendimento assumido
Quando dispara: Agente assume o atendimento (claim) no inbox.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
chatIdintegerdepartmentIdintegerdepartmentNamestringpreviousAssignedUserIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "conversation.service_started",
"data": {
"entity_type": "contact",
"entity_id": "61",
"chatId": 42,
"departmentId": 2,
"departmentName": "Comercial"
}
}conversation.service_finishedAtendimento finalizado
Quando dispara: Agente finaliza o atendimento no inbox.
Os campos de data
entity_typestringExemplo: contact
entity_idstringExemplo: 61
chatIdintegerdepartmentIdintegerdepartmentNamestringpreviousAssignedUserIdinteger{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "conversation.service_finished",
"data": {
"entity_type": "contact",
"entity_id": "61",
"chatId": 42,
"previousAssignedUserId": 7
}
}knowledge.document.createdDocumento criado na Central de Conhecimento
Quando dispara: Upload no painel ou tool MCP create_document.
Os campos de data
entity_typestringExemplo: kb_document
entity_idstringExemplo: 18
titlestringcollectionPathstringExemplo: Comercial > Playbooks
versionstringExemplo: 1.2
previousVersionstringExemplo: 1.1
actorLabelstringE-mail do usuário ou nome da chave de API que executou a ação.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "knowledge.document.created",
"data": {}
}knowledge.document.updatedDocumento atualizado
Quando dispara: Edição no painel ou tool MCP update_document.
Os campos de data
entity_typestringExemplo: kb_document
entity_idstringExemplo: 18
titlestringcollectionPathstringExemplo: Comercial > Playbooks
versionstringExemplo: 1.2
previousVersionstringExemplo: 1.1
actorLabelstringE-mail do usuário ou nome da chave de API que executou a ação.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "knowledge.document.updated",
"data": {}
}knowledge.document.publishedDocumento publicado
Quando dispara: Publicação de versão pelo painel ou pelas tools MCP publish_document / publish_presentation.
Os campos de data
entity_typestringExemplo: kb_document
entity_idstringExemplo: 18
titlestringcollectionPathstringExemplo: Comercial > Playbooks
versionstringExemplo: 1.2
previousVersionstringExemplo: 1.1
actorLabelstringE-mail do usuário ou nome da chave de API que executou a ação.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "knowledge.document.published",
"data": {}
}knowledge.document.archivedDocumento arquivado
Quando dispara: Arquivamento no painel ou tool MCP archive_document.
Os campos de data
entity_typestringExemplo: kb_document
entity_idstringExemplo: 18
titlestringcollectionPathstringExemplo: Comercial > Playbooks
versionstringExemplo: 1.2
previousVersionstringExemplo: 1.1
actorLabelstringE-mail do usuário ou nome da chave de API que executou a ação.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "knowledge.document.archived",
"data": {}
}opportunity.result_setResultado da oportunidade definido
Quando dispara: Fechamento da participação em um pipeline (resultado positivo, negativo ou neutro).
Os campos de data
entity_typestringExemplo: opportunity
entity_idstringExemplo: 391
pipelineIdintegeroutcomeIdintegeroutcomeKeystringpolaritystringpositive negative neutral
resultLabelstringreasonLabelstringvalueCentsintegercurrencystringExemplo: BRL
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "opportunity.result_set",
"data": {}
}opportunity.reopenedOportunidade reaberta
Quando dispara: Reabertura da participação em um pipeline após um resultado.
Os campos de data
entity_typestringExemplo: opportunity
entity_idstringExemplo: 391
pipelineIdintegeroutcomeIdintegeroutcomeKeystringpolaritystringpositive negative neutral
resultLabelstringreasonLabelstringvalueCentsintegercurrencystringExemplo: BRL
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "opportunity.reopened",
"data": {}
}connection.status_changedEstado da conexão mudou
Quando dispara: O estado da conexão (o state e o availability de GET /connections) mudou: o provedor avisou que conectou, caiu ou está conectando, ou o vigia dos canais achou a conexão muda, fora do ar ou fora do provedor. Só sai quando o par muda de fato; o aviso repetido do provedor não vira evento.
Os campos de data
connectionobrigatórioobjectconnection.idintegerconnection.namestringO nome da conexão na tela de Conexões.
connection.numberstring | nullO número em E.164; nulo antes da primeira leitura do QR.
connection.kindstringqr official
connection.channelstringwhatsapp instagram messenger webchat
stateobrigatóriostringconnected connecting disconnected
availabilityobrigatóriostringghost: a conexão sumiu do provedor e só serve para remover.
usable offline ghost
previousStateobrigatóriostringconnected connecting disconnected
previousAvailabilityobrigatóriostringusable offline ghost
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "connection.status_changed",
"data": {
"connection": {
"id": 7,
"name": "Loja Centro",
"number": "+5511999999999",
"kind": "qr",
"channel": "whatsapp"
},
"state": "disconnected",
"availability": "offline",
"previousState": "connected",
"previousAvailability": "usable"
}
}billing.budget_thresholdGasto do mês passou de um limite do teto
Quando dispara: O gasto do mês com as mensagens da API oficial (todos os números oficiais da organização, com a tabela de tarifas da revenda) passou de um dos limites do teto (PUT /billing/budget, 80% e 100% por padrão). Sai uma vez por limite e por mês; sem teto ou sem tabela da revenda, não sai.
Os campos de data
thresholdobrigatóriointegerO limite passado, em porcentagem do teto (80, 100).
spentCentsobrigatóriointegerlimitCentsobrigatóriointegermonthobrigatóriostringAAAA-MM.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "billing.budget_threshold",
"data": {
"threshold": 80,
"spentCents": 40120,
"limitCents": 50000,
"month": "2026-11"
}
}survey.answeredO cliente deu a nota da pesquisa no chat
Quando dispara: O cliente respondeu no chat a pesquisa que o produto mandou por POST /conversations/{id}/survey: o botão, o item da lista ou o número digitado. external_id é o externalId do envio. Sai uma vez por envio; a nota dada na página do produto (formato pagina) não passa pela plataforma.
Os campos de data
external_idobrigatóriostringO externalId do envio.
valueobrigatóriointegerA nota (uma das opções enviadas; sem opções, de 0 a 10).
chat_idinteger | nullcontact_idinteger | nullanswered_atstringviastringchoice: botão, item da lista ou o título de uma opção; text: o número digitado.
choice text
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "survey.answered",
"data": {
"external_id": "7f3c2a9e-envio-81",
"value": 5,
"chat_id": 42,
"contact_id": 61,
"answered_at": "2026-11-18T13:05:00.000Z",
"via": "choice"
}
}template.status_updatedA Meta mudou a situação de um modelo
Quando dispara: A Meta avisou que um modelo da API oficial foi aprovado, recusado, pausado ou desligado, e a situação guardada mudou de fato. templateId é o id do modelo na plataforma; status vem em minúsculas. O aviso repetido da Meta não vira evento, e a mesma WABA em duas conexões sai uma vez por modelo guardado.
Os campos de data
templateIdobrigatóriointegerO id do modelo na plataforma.
nameobrigatóriostringO nome do modelo na Meta.
languageobrigatóriostringExemplo: pt_BR
statusobrigatóriostringA situação nova, em minúsculas: approved, rejected, paused, disabled, pending, pending_deletion, in_appeal, reinstated, flagged, deleted, archived e as que a Meta criar.
Exemplo: rejected
previousStatusstringA situação de antes, em minúsculas.
rejectedReasonstring | nullO motivo que a Meta deu (INVALID_FORMAT, INCORRECT_CATEGORY, TAG_CONTENT_MISMATCH… ou o texto da pausa); nulo quando ela não deu.
instanceIdobrigatóriointegerA conexão do número oficial a que o modelo pertence (o id de GET /connections).
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "template.status_updated",
"data": {
"templateId": 318,
"name": "confirmacao_visita",
"language": "pt_BR",
"status": "rejected",
"previousStatus": "pending",
"rejectedReason": "INVALID_FORMAT",
"instanceId": 7
}
}team_chat.message_createdMensagem nova na comunicação interna da equipe
Quando dispara: Alguém da organização escreveu numa sala da comunicação interna (a geral, a de uma equipe, a pessoa a pessoa ou um canal). Não leva o texto: o produto lê pela ação read_team_chat em nome de quem recebe. recipient_user_ids são as pessoas ativas da sala, menos o autor; mentioned_user_ids, as mencionadas. Sai uma vez por mensagem (o reenvio com a mesma clientKey não repete).
Os campos de data
room_idobrigatóriointegerA sala (o roomId das ações read_team_chat e manage_team_chat).
room_kindobrigatóriostringgeneral: a sala de toda a empresa; department: a de uma equipe; dm: pessoa a pessoa; channel: um canal criado à mão.
general department dm channel
message_idobrigatóriointegerauthor_user_idobrigatóriointegerQuem escreveu.
recipient_user_idsobrigatóriointeger[]As pessoas ativas da sala, menos o autor.
mentioned_user_idsobrigatóriointeger[]As pessoas mencionadas na mensagem.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "team_chat.message_created",
"data": {
"room_id": 81,
"room_kind": "department",
"message_id": 5120,
"author_user_id": 18,
"recipient_user_ids": [
17,
251
],
"mentioned_user_ids": [
17
]
}
}lead.createdChegou um lead de formulário da Meta
Quando dispara: Uma pessoa preencheu um formulário de leads (Lead Ads) de uma página ligada por POST /leads/meta/pages. A plataforma já gravou o lead, criou ou achou o contato (por telefone e por e-mail) e registrou o evento na linha do tempo dele. leadId é o id do lead na Meta e a idempotência: sai uma vez por lead. contactId vem nulo quando o lead não tem telefone válido nem contato com o mesmo e-mail, ou quando a organização ainda não tem conexão de WhatsApp. campaign e ad vêm nulos enquanto a conta de anúncios não é escolhida.
Os campos de data
leadIdobrigatóriostringO id do lead na Meta. É a idempotência: o mesmo lead sai uma vez.
sourceobrigatóriostringmeta_lead_form
pageIdobrigatóriostringO id da página na Meta.
pageNameobrigatóriostringformIdobrigatóriostringO id do formulário na Meta.
formNameobrigatóriostringcontactIdobrigatóriointeger | nullO contato criado ou achado; nulo quando o lead não pôde virar contato (sem telefone válido e sem contato com o mesmo e-mail, ou sem conexão de WhatsApp).
chatIdobrigatóriointeger | nullA conversa do contato, quando existe.
namestring | nullphonestring | nullemailstring | nullanswersobrigatórioobject[]As respostas das perguntas do formulário, sem o nome, o telefone e o e-mail.
answers[].questionobrigatóriostringanswers[].answerobrigatóriostringcampaignstring | nullO nome da campanha; nulo sem a conta de anúncios escolhida.
adstring | nullO nome do anúncio; nulo sem a conta de anúncios escolhida.
organicobrigatóriobooleanO lead não veio de anúncio, como a Meta informa.
createdAtobrigatóriostringQuando a pessoa preencheu o formulário.
{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "lead.created",
"data": {
"leadId": "1203948571620394",
"source": "meta_lead_form",
"pageId": "104857291038475",
"pageName": "Loja Centro",
"formId": "938475610293847",
"formName": "Orçamento sem compromisso",
"contactId": 61,
"chatId": 42,
"name": "Marina Souza",
"phone": "+5511999999999",
"email": "marina@exemplo.com",
"answers": [
{
"question": "Qual serviço você procura?",
"answer": "Reforma completa"
}
],
"campaign": null,
"ad": null,
"organic": false,
"createdAt": "2026-11-19T13:05:00.000Z"
}
}call.incomingComeçou a tocar uma ligação de WhatsApp
Quando dispara: Alguém ligou para um número que faz ligação (a conexão com calls: true). A ligação já está gravada, sem dono; quem atende primeiro pelo POST /calls/{id}/accept fica com ela. Sai uma vez por ligação. call.assignedUserId é quem está com a conversa (nulo sem responsável).
Os campos de data
chat_idobrigatóriointeger | nullcontact_idobrigatóriointeger | nullinstanceobrigatóriointeger | nullA conexão que liga.
callobrigatórioobjectcall.idobrigatóriostringO id da ligação (o do GET /calls/{id}).
call.chatIdinteger | nullcall.contactIdinteger | nullcall.connectionIdinteger | nullcall.directionobrigatóriostringinbound outbound
call.stateobrigatóriostringinitiating ringing connected ended failed
call.outcomeobrigatóriostring | nullcompleted no-answer busy canceled failed missed rejected
call.userIdinteger | nullQuem ligou ou atendeu.
call.startedAtstring | nullcall.answeredAtstring | nullcall.endedAtstring | nullcall.durationSecobrigatóriointegercall.fromstring | nullcall.tostring | nullcall.assignedUserIdinteger | nullQuem está com a conversa.
call.contactNamestring | null{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "call.incoming",
"data": {
"chat_id": 42,
"contact_id": 61,
"instance": 7,
"call": {
"id": "704",
"chatId": 42,
"contactId": 61,
"connectionId": 7,
"direction": "inbound",
"state": "ringing",
"outcome": null,
"userId": null,
"startedAt": "2026-11-19T15:00:00.000Z",
"answeredAt": null,
"endedAt": null,
"durationSec": 0,
"from": "5511999999999",
"to": "5511988887777",
"assignedUserId": 18,
"contactName": "Marina Souza"
}
}
}call.answeredA ligação foi atendida
Quando dispara: A pessoa do outro lado atendeu a ligação feita, ou alguém da equipe atendeu a recebida. call.answeredAt é a hora do atendimento. Sai uma vez por ligação.
Os campos de data
chat_idobrigatóriointeger | nullcontact_idobrigatóriointeger | nullinstanceobrigatóriointeger | nullA conexão que liga.
callobrigatórioobjectcall.idobrigatóriostringO id da ligação (o do GET /calls/{id}).
call.chatIdinteger | nullcall.contactIdinteger | nullcall.connectionIdinteger | nullcall.directionobrigatóriostringinbound outbound
call.stateobrigatóriostringinitiating ringing connected ended failed
call.outcomeobrigatóriostring | nullcompleted no-answer busy canceled failed missed rejected
call.userIdinteger | nullQuem ligou ou atendeu.
call.startedAtstring | nullcall.answeredAtstring | nullcall.endedAtstring | nullcall.durationSecobrigatóriointegercall.fromstring | nullcall.tostring | nullcall.assignedUserIdinteger | nullQuem está com a conversa.
call.contactNamestring | null{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "call.answered",
"data": {
"chat_id": 42,
"contact_id": 61,
"instance": 7,
"call": {
"id": "704",
"chatId": 42,
"contactId": 61,
"connectionId": 7,
"direction": "outbound",
"state": "connected",
"outcome": null,
"userId": 18,
"startedAt": "2026-11-19T15:00:00.000Z",
"answeredAt": "2026-11-19T15:00:06.000Z",
"endedAt": null,
"durationSec": 0,
"from": "5511999999999",
"to": "5511988887777",
"assignedUserId": 18,
"contactName": "Marina Souza"
}
}
}call.endedA ligação terminou
Quando dispara: A ligação acabou: call.outcome diz como (completed, no-answer, busy, canceled, failed, missed ou rejected) e call.durationSec, quanto durou depois de atendida. A perdida (missed) soma uma não lida na conversa e manda a mensagem de ligação perdida, quando a organização tem uma. Sai uma vez por desfecho: a correção do servidor só reavisa se o desfecho mudou.
Os campos de data
chat_idobrigatóriointeger | nullcontact_idobrigatóriointeger | nullinstanceobrigatóriointeger | nullA conexão que liga.
callobrigatórioobjectcall.idobrigatóriostringO id da ligação (o do GET /calls/{id}).
call.chatIdinteger | nullcall.contactIdinteger | nullcall.connectionIdinteger | nullcall.directionobrigatóriostringinbound outbound
call.stateobrigatóriostringinitiating ringing connected ended failed
call.outcomeobrigatóriostring | nullcompleted no-answer busy canceled failed missed rejected
call.userIdinteger | nullQuem ligou ou atendeu.
call.startedAtstring | nullcall.answeredAtstring | nullcall.endedAtstring | nullcall.durationSecobrigatóriointegercall.fromstring | nullcall.tostring | nullcall.assignedUserIdinteger | nullQuem está com a conversa.
call.contactNamestring | null{
"id": "12345",
"created_at": "2026-06-20T12:00:00.000Z",
"organization_id": 1,
"type": "call.ended",
"data": {
"chat_id": 42,
"contact_id": 61,
"instance": 7,
"call": {
"id": "704",
"chatId": 42,
"contactId": 61,
"connectionId": 7,
"direction": "outbound",
"state": "ended",
"outcome": "completed",
"userId": 18,
"startedAt": "2026-11-19T15:00:00.000Z",
"answeredAt": "2026-11-19T15:00:06.000Z",
"endedAt": "2026-11-19T15:02:20.000Z",
"durationSec": 134,
"from": "5511999999999",
"to": "5511988887777",
"assignedUserId": 18,
"contactName": "Marina Souza"
}
}
}