Pular para o conteúdo

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) e RateLimit-Policy; no 429, também Retry-After, e o corpo diz em scope qual limite encheu. Os X-RateLimit-* continuam.

Erros

{ "error": "<frase>", "code": "<CÓDIGO>", "request_id": "<uuid>" }. Trate pelo code; a frase pode mudar.

Correlação

toda resposta inclui X-Request-Id (UUID), o mesmo request_id do 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álido
  • 401Nã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 recurso
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
Chamada
curl --request GET 'https://conta.biacrm.app/api/v1/token' \
  --header 'Authorization: Bearer SEU_TOKEN'
Resposta 200
{
  "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óriostring

Exemplo: minha-instancia

numberobrigatóriostring

Exemplo: 5511999999999

typeobrigatóriostring

text image video document audio

messagestring
mediaUrlstring
fileNamestring

Exemplo: proposta.pdf

mimetypestring

Exemplo: image/png

Respostas

  • 200Mensagem enviada
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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"}'
Resposta 200
{
  "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 caminho

ID da mensagem (ex.: retornado em data.key.id ao enviar).

Respostas

  • 200Status da mensagem
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
curl --request GET 'https://conta.biacrm.app/api/v1/messages/123' \
  --header 'Authorization: Bearer SEU_TOKEN'
Resposta 200
{
  "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 consulta
limitinteger · na consulta
phonestring · na consulta

Filtrar por prefixo do telefone (apenas dígitos).

qstring · na consulta

Busca pelo nome, pelo telefone ou pelo valor de um campo (o e-mail), com página.

statusstring · na consulta

active: nem arquivado nem bloqueado. Sem ele, todos.

active archived blocked unarchived

Respostas

  • 200Lista paginada
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
curl --request GET 'https://conta.biacrm.app/api/v1/contacts' \
  --header 'Authorization: Bearer SEU_TOKEN'
Resposta 200
{
  "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óriostring

Exemplo: 5511999999999

nameobrigatóriostring

Exemplo: Maria Silva

instanceNameobrigatóriostring

Exemplo: minha-instancia

assignedUserIdinteger
assignedDepartmentIdinteger
funnelStageIdinteger
tagIdsinteger[]
customDataobject

Respostas

  • 201Contato criado
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 409Contato já existe
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 201
{
  "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óriostring
contactsobrigatórioobject[]
contacts[].phoneobrigatóriostring
contacts[].nameobrigatóriostring
contacts[].customDataobject

Respostas

  • 200Um resultado por linha
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}]}'
Resposta 200
{
  "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 caminho

Respostas

  • 200Contato encontrado
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
curl --request GET 'https://conta.biacrm.app/api/v1/contacts/123' \
  --header 'Authorization: Bearer SEU_TOKEN'
Resposta 200
{
  "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 caminho

Corpo

namestring
assignedUserIdinteger
assignedDepartmentIdinteger
funnelStageIdinteger
tagIdsinteger[]
customDataobject

Troca o objeto inteiro (não junta): mande o que já existe junto.

archivedboolean

true arquiva; false desarquiva.

blockedboolean

true bloqueia (a mensagem nova dele não entra na Inbox); false desbloqueia.

Respostas

  • 200Contato atualizado
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 200
{
  "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 consulta
instanceNamestring · na consulta

Respostas

  • 200Conversas encontradas
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
curl --request GET 'https://conta.biacrm.app/api/v1/conversations' \
  --header 'Authorization: Bearer SEU_TOKEN'
Resposta 200
{
  "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óriostring

Exemplo: 5511999999999

nameobrigatóriostring

Exemplo: Maria Silva

instanceNameobrigatóriostring

Exemplo: minha-instancia

assignedUserIdinteger
assignedDepartmentIdinteger
funnelStageIdinteger
tagIdsinteger[]
customDataobject

Respostas

  • 200Conversa já existia
  • 201Conversa criada
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 409Conflito ao criar contato
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 200
{
  "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 caminho

ID da conversa (chatId)

Corpo

limitinteger

Respostas

  • 200Sync concluído
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 200
{
  "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 caminho

Corpo

stageIdobrigatóriointeger

ID da etapa ou null para remover.

Respostas

  • 200Etapa atualizada
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 200
{
  "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 caminho

Corpo

userIdobrigatóriointeger

ID do usuário ou null para desatribuir.

Respostas

  • 200Responsável atualizado
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 200
{
  "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 caminho

Corpo

tagIdobrigatóriointeger

Respostas

  • 200Tag adicionada
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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}'
Resposta 200
{
  "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 caminho
tagIdobrigatóriointeger · no caminho

Respostas

  • 200Tag removida
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
curl --request DELETE 'https://conta.biacrm.app/api/v1/contacts/123/tags/123' \
  --header 'Authorization: Bearer SEU_TOKEN'
Resposta 200
{
  "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 caminho

Chave da integração de formulário.

Corpo

idempotencyKeyobrigatóriostring

Exemplo: form-2026-09-02-001

phoneobrigatóriostring

Exemplo: 5511999999999

nameobrigatóriostring

Exemplo: Maria Silva

fieldsobject
utmobject
referrerstring
landingPagestring

Respostas

  • 200Envio já processado (idempotente)
  • 201Envio novo
  • 400Payload inválido
  • 401Nã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 recurso
  • 404Não encontrado
  • 429Limite de requisições excedido: o do token ou o da empresa (a soma dos tokens dela). O corpo diz qual em scope.
  • 500Erro interno
Chamada
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"}'
Resposta 200
{
  "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 token do caminho (o endereço completo aparece uma vez, na criação do canal). Sem chave sk_live_.
  • Assinatura: X-Webhook-Timestamp (segundos) e X-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 responde duplicate: true. Evento que falhou com 503 é reprocessado ao reenviar.
  • Limite: 600 eventos por minuto por canal.

Parâmetros

tokenobrigatóriostring · no caminho

Token do canal (ch_…).

X-Webhook-Timestampstring · no cabeçalho
X-Webhook-Signaturestring · no cabeçalho

Corpo

Respostas

  • 200Evento aceito, repetido (duplicate: true) ou teste
  • 400Formato inválido (issues aponta o campo) ou link de mídia recusado. Corrigir; não reenviar igual.
  • 401Endereço desconhecido ou assinatura ausente ou inválida
  • 413Corpo acima de 1 MB ou mídia acima de 50 MB
  • 429Mais de 600 eventos por minuto no canal. Reenviar depois.
  • 503Falha passageira. Reenviar o mesmo evento.
Chamada
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"}}'
Resposta 200
{
  "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) e X-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) e Idempotency-Key (o data.messageId, igual em todas as tentativas).
  • Responda 2xx em até 10 s quando aceitar a mensagem; pode devolver { "externalId": "…" }.
  • 5xx, 408, 429 ou sem resposta: novas tentativas por cerca de 20 a 30 minutos. Outros 4xx e redirecionamentos: a mensagem fica como falha na conversa.
  • Depois, informe o andamento com message.status no endereço de entrada, usando o mesmo messageId.

Corpo

idobrigatóriostring

Id do evento (evt_…), também em X-Webhook-Id.

typeobrigatóriostring

message.outgoing channel.test

occurredAtobrigatóriostring
channelobrigatórioobject
channel.idinteger
channel.namestring
dataobrigatórioobject
data.messageIdobrigatóriostring

Use em message.status e como chave de idempotência.

data.toobrigatórioobject
data.typeobrigatóriostring

text image video document audio

data.textstring | null
data.mediaobject ou null
data.replyTostring | null
O que chega
{
  "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
  1. Nos Webhooks do painel, cadastre uma URL HTTPS.
  2. Selecione os eventos desejados (ou todos).
  3. Copie o secret whsec_... exibido uma única vez ao criar ou rotacionar.
  4. Implemente validação HMAC no seu servidor (ver schema WebhookSignatureVerification).
Entrega
  • Método: POST com Content-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_idstring

ID da mensagem no WhatsApp.

chat_idinteger

ID da conversa (chatId).

remote_jidstring

JID WhatsApp do contato.

instancestring

Nome da instância/canal.

connectionobject

A conexão que recebeu a mensagem: o nome, se é a API oficial e o canal (whatsapp, instagram, messenger ou webchat).

connection.idinteger
connection.namestring
connection.officialboolean
connection.channelstring

whatsapp instagram messenger webchat

textstring
message_typestring

Exemplo: conversation

timestampstring
O que chega
{
  "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_idstring
chat_idinteger
remote_jidstring
textstring
message_typestring
statusstring

sent delivered read pending error

sourcestring

Origem: human, api, automation, campaign, ai…

timestampstring
internalboolean

true na nota interna escrita pela API v1: só a equipe vê, nada sai para o contato.

O que chega
{
  "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_idstring
statusstring

sent delivered read error pending

remote_jidstring
instancestring
O que chega
{
  "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_idstring
chat_idinteger
remote_jidstring | null
from_meboolean

true quando a mensagem apagada saiu da casa.

deleted_bystring

contact operator system

deleted_by_namestring | null

Quem da equipe apagou (só em operator).

deleted_atstring
O que chega
{
  "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óriostring

A mensagem que recebeu (ou perdeu) a reação.

chat_idobrigatóriointeger
contact_idinteger | null
emojiobrigatóriostring | null

null quando a reação saiu.

actionobrigatóriostring

add remove

from_meobrigatórioboolean

true na reação da equipe (uma por número).

reacted_by_user_idinteger | null

Quem da equipe reagiu (só na da equipe pela plataforma).

reacted_by_namestring | null

O nome de quem reagiu: a pessoa da equipe ou o contato.

O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

namestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

stageIdinteger
stageNamestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

tagIdinteger
tagNamestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

tagIdinteger
tagNamestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

targetUserIdinteger
agentNamestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

targetUserIdinteger
agentNamestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

departmentIdinteger
departmentNamestring
chatIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Contato de origem (lápide).

Exemplo: 75

canonicalContactIdinteger

Exemplo: 61

sourceContactIdinteger

Exemplo: 75

organizationIdinteger

Exemplo: 1

methodstring

deterministic_phone deterministic_email external_id manual

batchIdstring

Lote da fusão (o desfazer é por lote).

mergeIdinteger
mergedAtstring

Só em contact.merged.

undoneAtstring

Só em contact.merge_undone.

actorUserIdinteger | null

Quem confirmou (fusão manual ou desfazer); nulo quando foi o reconciliador.

conversationsRepointedinteger
opportunitiesRepointedinteger
rolestring

source

O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Contato de origem (lápide).

Exemplo: 75

canonicalContactIdinteger

Exemplo: 61

sourceContactIdinteger

Exemplo: 75

organizationIdinteger

Exemplo: 1

methodstring

deterministic_phone deterministic_email external_id manual

batchIdstring

Lote da fusão (o desfazer é por lote).

mergeIdinteger
mergedAtstring

Só em contact.merged.

undoneAtstring

Só em contact.merge_undone.

actorUserIdinteger | null

Quem confirmou (fusão manual ou desfazer); nulo quando foi o reconciliador.

conversationsRepointedinteger
opportunitiesRepointedinteger
rolestring

source

O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

chatIdinteger
departmentIdinteger
departmentNamestring
previousAssignedUserIdinteger
O que chega
{
  "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_typestring

Exemplo: contact

entity_idstring

Exemplo: 61

chatIdinteger
departmentIdinteger
departmentNamestring
previousAssignedUserIdinteger
O que chega
{
  "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_typestring

Exemplo: kb_document

entity_idstring

Exemplo: 18

titlestring
collectionPathstring

Exemplo: Comercial > Playbooks

versionstring

Exemplo: 1.2

previousVersionstring

Exemplo: 1.1

actorLabelstring

E-mail do usuário ou nome da chave de API que executou a ação.

O que chega
{
  "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_typestring

Exemplo: kb_document

entity_idstring

Exemplo: 18

titlestring
collectionPathstring

Exemplo: Comercial > Playbooks

versionstring

Exemplo: 1.2

previousVersionstring

Exemplo: 1.1

actorLabelstring

E-mail do usuário ou nome da chave de API que executou a ação.

O que chega
{
  "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_typestring

Exemplo: kb_document

entity_idstring

Exemplo: 18

titlestring
collectionPathstring

Exemplo: Comercial > Playbooks

versionstring

Exemplo: 1.2

previousVersionstring

Exemplo: 1.1

actorLabelstring

E-mail do usuário ou nome da chave de API que executou a ação.

O que chega
{
  "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_typestring

Exemplo: kb_document

entity_idstring

Exemplo: 18

titlestring
collectionPathstring

Exemplo: Comercial > Playbooks

versionstring

Exemplo: 1.2

previousVersionstring

Exemplo: 1.1

actorLabelstring

E-mail do usuário ou nome da chave de API que executou a ação.

O que chega
{
  "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_typestring

Exemplo: opportunity

entity_idstring

Exemplo: 391

pipelineIdinteger
outcomeIdinteger
outcomeKeystring
polaritystring

positive negative neutral

resultLabelstring
reasonLabelstring
valueCentsinteger
currencystring

Exemplo: BRL

O que chega
{
  "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_typestring

Exemplo: opportunity

entity_idstring

Exemplo: 391

pipelineIdinteger
outcomeIdinteger
outcomeKeystring
polaritystring

positive negative neutral

resultLabelstring
reasonLabelstring
valueCentsinteger
currencystring

Exemplo: BRL

O que chega
{
  "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órioobject
connection.idinteger
connection.namestring

O nome da conexão na tela de Conexões.

connection.numberstring | null

O número em E.164; nulo antes da primeira leitura do QR.

connection.kindstring

qr official

connection.channelstring

whatsapp instagram messenger webchat

stateobrigatóriostring

connected connecting disconnected

availabilityobrigatóriostring

ghost: a conexão sumiu do provedor e só serve para remover.

usable offline ghost

previousStateobrigatóriostring

connected connecting disconnected

previousAvailabilityobrigatóriostring

usable offline ghost

O que chega
{
  "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óriointeger

O limite passado, em porcentagem do teto (80, 100).

spentCentsobrigatóriointeger
limitCentsobrigatóriointeger
monthobrigatóriostring

AAAA-MM.

O que chega
{
  "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óriostring

O externalId do envio.

valueobrigatóriointeger

A nota (uma das opções enviadas; sem opções, de 0 a 10).

chat_idinteger | null
contact_idinteger | null
answered_atstring
viastring

choice: botão, item da lista ou o título de uma opção; text: o número digitado.

choice text

O que chega
{
  "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óriointeger

O id do modelo na plataforma.

nameobrigatóriostring

O nome do modelo na Meta.

languageobrigatóriostring

Exemplo: pt_BR

statusobrigatóriostring

A 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

previousStatusstring

A situação de antes, em minúsculas.

rejectedReasonstring | null

O motivo que a Meta deu (INVALID_FORMAT, INCORRECT_CATEGORY, TAG_CONTENT_MISMATCH… ou o texto da pausa); nulo quando ela não deu.

instanceIdobrigatóriointeger

A conexão do número oficial a que o modelo pertence (o id de GET /connections).

O que chega
{
  "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óriointeger

A sala (o roomId das ações read_team_chat e manage_team_chat).

room_kindobrigatóriostring

general: 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óriointeger
author_user_idobrigatóriointeger

Quem escreveu.

recipient_user_idsobrigatóriointeger[]

As pessoas ativas da sala, menos o autor.

mentioned_user_idsobrigatóriointeger[]

As pessoas mencionadas na mensagem.

O que chega
{
  "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óriostring

O id do lead na Meta. É a idempotência: o mesmo lead sai uma vez.

sourceobrigatóriostring

meta_lead_form

pageIdobrigatóriostring

O id da página na Meta.

pageNameobrigatóriostring
formIdobrigatóriostring

O id do formulário na Meta.

formNameobrigatóriostring
contactIdobrigatóriointeger | null

O 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 | null

A conversa do contato, quando existe.

namestring | null
phonestring | null
emailstring | null
answersobrigatórioobject[]

As respostas das perguntas do formulário, sem o nome, o telefone e o e-mail.

answers[].questionobrigatóriostring
answers[].answerobrigatóriostring
campaignstring | null

O nome da campanha; nulo sem a conta de anúncios escolhida.

adstring | null

O nome do anúncio; nulo sem a conta de anúncios escolhida.

organicobrigatórioboolean

O lead não veio de anúncio, como a Meta informa.

createdAtobrigatóriostring

Quando a pessoa preencheu o formulário.

O que chega
{
  "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 | null
contact_idobrigatóriointeger | null
instanceobrigatóriointeger | null

A conexão que liga.

callobrigatórioobject
call.idobrigatóriostring

O id da ligação (o do GET /calls/{id}).

call.chatIdinteger | null
call.contactIdinteger | null
call.connectionIdinteger | null
call.directionobrigatóriostring

inbound outbound

call.stateobrigatóriostring

initiating ringing connected ended failed

call.outcomeobrigatóriostring | null

completed no-answer busy canceled failed missed rejected

call.userIdinteger | null

Quem ligou ou atendeu.

call.startedAtstring | null
call.answeredAtstring | null
call.endedAtstring | null
call.durationSecobrigatóriointeger
call.fromstring | null
call.tostring | null
call.assignedUserIdinteger | null

Quem está com a conversa.

call.contactNamestring | null
O que chega
{
  "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 | null
contact_idobrigatóriointeger | null
instanceobrigatóriointeger | null

A conexão que liga.

callobrigatórioobject
call.idobrigatóriostring

O id da ligação (o do GET /calls/{id}).

call.chatIdinteger | null
call.contactIdinteger | null
call.connectionIdinteger | null
call.directionobrigatóriostring

inbound outbound

call.stateobrigatóriostring

initiating ringing connected ended failed

call.outcomeobrigatóriostring | null

completed no-answer busy canceled failed missed rejected

call.userIdinteger | null

Quem ligou ou atendeu.

call.startedAtstring | null
call.answeredAtstring | null
call.endedAtstring | null
call.durationSecobrigatóriointeger
call.fromstring | null
call.tostring | null
call.assignedUserIdinteger | null

Quem está com a conversa.

call.contactNamestring | null
O que chega
{
  "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 | null
contact_idobrigatóriointeger | null
instanceobrigatóriointeger | null

A conexão que liga.

callobrigatórioobject
call.idobrigatóriostring

O id da ligação (o do GET /calls/{id}).

call.chatIdinteger | null
call.contactIdinteger | null
call.connectionIdinteger | null
call.directionobrigatóriostring

inbound outbound

call.stateobrigatóriostring

initiating ringing connected ended failed

call.outcomeobrigatóriostring | null

completed no-answer busy canceled failed missed rejected

call.userIdinteger | null

Quem ligou ou atendeu.

call.startedAtstring | null
call.answeredAtstring | null
call.endedAtstring | null
call.durationSecobrigatóriointeger
call.fromstring | null
call.tostring | null
call.assignedUserIdinteger | null

Quem está com a conversa.

call.contactNamestring | null
O que chega
{
  "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"
    }
  }
}