Skip to main content
The Chatwoot integration lets WhatsApp traffic for a VZaps instance show up in Chatwoot and routes agent replies from Chatwoot back to the contact on WhatsApp. There is one Chatwoot configuration per VZaps instance.

​
Overview

  • The instance worker syncs WhatsApp -> Chatwoot (contacts, conversations, text and media where supported).
  • Chatwoot posts events to the VZaps webhook; the API forwards them to the worker for Chatwoot -> WhatsApp (agent messages).
  • The webhook_url field returned by GET or POST must be set on the Chatwoot API inbox (or applied automatically when auto_create = true on save).
  • Messages that originated on WhatsApp use a source_id prefixed with WAID: so the webhook can ignore them and prevent loops.

​
Configuration fields

FieldDescription
enabledTurns the integration on or off for the instance.
urlChatwoot API base URL (e.g. https://app.chatwoot.com).
account_idNumeric account id in Chatwoot.
tokenAPI token (api_access_token) for a Chatwoot user or agent.
name_inboxName of the API inbox to create or bind when auto_create is used.
sign_msgWhen true, prefixes outbound WhatsApp messages with the agent signature.
sign_delimiterText between agent name and message body (e.g. newline).
numberPhone number context for the inbox (E.164 or format accepted by Chatwoot).
reopen_conversationReopens an existing conversation when the contact writes again.
conversation_pendingOpens new conversations in pending state.
import_contacts / import_messagesFlags for the initial history import flow.
days_limit_import_messagesDay window for message import; minimum valid value is 1.
auto_createWhen true, the API tries to create/update the API inbox and set the webhook.
organization / logoOptional metadata for Chatwoot display.
ignore_jidsJSON array of JIDs to ignore (e.g. specific groups or contacts).
ignore_groupsWhen true, group messages are not sent to Chatwoot.
webhook_urlRead-only in responses: URL to configure in Chatwoot (GET/POST).

​
Endpoints

  • GET /instances/{id}/chatwoot - read configuration (includes webhook_url and token_masked when applicable).
  • POST /instances/{id}/chatwoot - create or update configuration (body InstanceChatwootUpsertDto).
  • DELETE /instances/{id}/chatwoot - remove configuration from the instance.
  • POST /instances/{id}/chatwoot/import/{what} - schedule a manual import; what = contacts, messages, or all.
  • POST /chatwoot/webhook/{instanceId} - Chatwoot callback (no JWT); use only in inbox settings or controlled tests; this is not the VZaps instance webhook.

​
Example: save configuration

curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/chatwoot" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://app.chatwoot.com",
    "account_id": "1",
    "token": "YOUR_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": "My company",
    "logo": "",
    "ignore_groups": false,
    "ignore_jids": []
  }'
Copy webhook_url from the response into the Chatwoot API inbox if auto_create did not apply it automatically.

​
Best practices

  • Treat token like any API secret; prefer a dedicated integration user with minimal scope in Chatwoot.
  • Use ignore_groups or ignore_jids to filter groups or numbers that should not open Chatwoot conversations.
  • After changing URL or account, confirm the Chatwoot inbox webhook still points at this instance webhook_url.