Pular para o conteúdo principal
A integracao com o Chatwoot permite que mensagens do WhatsApp da instancia aparecam no Chatwoot e que respostas feitas no Chatwoot sejam entregues de volta ao contato no WhatsApp. Ha uma unica configuracao Chatwoot por instancia VZaps.

​
Visao geral

  • O worker da instancia sincroniza mensagens WhatsApp -> Chatwoot (contatos, conversas, texto e midia conforme suportado).
  • O Chatwoot envia eventos para o webhook da VZaps; a API encaminha ao worker para Chatwoot -> WhatsApp (mensagens de agente).
  • O campo webhook_url retornado pelo GET ou POST da configuracao deve ser cadastrado no inbox API do Chatwoot (ou aplicado automaticamente quando auto_create = true no salvamento).
  • Mensagens originadas no WhatsApp e replicadas no Chatwoot usam source_id com prefixo WAID: para evitar loop; o webhook ignora esses eventos na volta.

​
Campos da configuracao

CampoDescricao
enabledLiga ou desliga a integracao para a instancia.
urlURL base da API do Chatwoot (ex.: https://app.chatwoot.com).
account_idID numerico da conta no Chatwoot.
tokenToken de API (api_access_token) do usuario ou agente no Chatwoot.
name_inboxNome da inbox API a criar ou associar quando auto_create estiver ativo.
sign_msgQuando true, prefixa mensagens enviadas ao WhatsApp com assinatura do agente.
sign_delimiterTexto entre nome do agente e o corpo da mensagem (ex.: \n).
numberNumero exibido/contexto da inbox (E.164 ou formato aceito pelo Chatwoot).
reopen_conversationReabre conversa existente quando o contato escreve de novo.
conversation_pendingAbre novas conversas no estado pendente.
import_contacts / import_messagesFlags usadas no fluxo de importacao inicial (historico).
days_limit_import_messagesJanela em dias para importacao de mensagens; valor minimo valido 1.
auto_createSe true, a API tenta criar/atualizar a inbox API e configurar o webhook.
organization / logoMetadados opcionais para exibicao no Chatwoot.
ignore_jidsJSON array de JIDs a ignorar (ex.: grupos ou contatos especificos).
ignore_groupsQuando true, mensagens de grupos nao sao enviadas ao Chatwoot.
webhook_urlSomente leitura na resposta: URL a configurar no Chatwoot (GET/POST).

​
Endpoints

  • GET /instances/{id}/chatwoot - le a configuracao (inclui webhook_url e token_masked quando aplicavel).
  • POST /instances/{id}/chatwoot - cria ou atualiza a configuracao (body InstanceChatwootUpsertDto).
  • DELETE /instances/{id}/chatwoot - remove a configuracao da instancia.
  • POST /instances/{id}/chatwoot/import/{what} - agenda importacao manual; what = contacts, messages ou all.
  • POST /chatwoot/webhook/{instanceId} - callback do Chatwoot (sem autenticacao JWT); use apenas na configuracao do inbox ou testes; nao e o webhook de eventos da instancia VZaps.

​
Exemplo: salvar configuracao

curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/chatwoot" \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://app.chatwoot.com",
    "account_id": "1",
    "token": "SEU_API_ACCESS_TOKEN",
    "name_inbox": "WhatsApp VZaps",
    "sign_msg": true,
    "sign_delimiter": "\n",
    "number": "5532988776655",
    "reopen_conversation": true,
    "conversation_pending": false,
    "import_contacts": true,
    "import_messages": true,
    "days_limit_import_messages": 30,
    "auto_create": true,
    "organization": "Minha empresa",
    "logo": "",
    "ignore_groups": false,
    "ignore_jids": []
  }'
Na resposta, copie webhook_url para o inbox API do Chatwoot se o auto_create nao tiver aplicado sozinho.

​
Boas praticas

  • Guarde o token com o mesmo cuidado de qualquer segredo de API; prefira usuario de integracao com escopo minimo no Chatwoot.
  • Use ignore_groups ou ignore_jids para filtrar grupos ou numeros que nao devem abrir conversas no Chatwoot.
  • Apos alterar URL ou conta, valide se o webhook no Chatwoot ainda aponta para webhook_url da instancia.