Summary

This article covers common questions about using Wati's API and webhooks, including how to add contacts via API, where to find your API token, how to enable read receipts using webhook events, and how to manage webhooks via API.

Important: Global Webhooks are supported only for WhatsApp messages. To receive alerts or trigger actions for Instagram or Facebook Messenger messages, use the Webhook node inside a chatbot flow instead.

Frequently Asked Questions (FAQs)

1. Can I add a contact via API?

Yes. Use one of the following endpoints:

v3 (recommended): POST https://live-mt-server.wati.io/api/ext/v3/contacts
Legacy v1: POST https://live-mt-server.wati.io/{tenantId}/api/v1/addContact/{whatsappNumber}

v3 is recommended for all new integrations. v1 is legacy but still supported.

2. Where can I find my Wati API token?

Go to Connector > API > Create API Token in your Wati account. You will find your Access Token and API endpoint URL there.

For v3 endpoints, create a token with the appropriate scope:

Scope	Used for
`contactsv3:*`	Contact operations
`conversationsv3:*`	Conversation operations
`messagetemplatev3:write`	Sending templates

3. How do I enable read receipts?

Enable the sentMessageREAD_v2 webhook event to receive a callback when a message you sent is read by the recipient.

To set this up:

Go to Connector > Webhooks in your Wati account.
Add your webhook URL.
Enable the sentMessageREAD_v2 event.

Wati webhooks can notify you via callback URL for the following:

Messages received
Messages sent (Template & Session)
Message status updates (Sent / Delivered / Read)

sentMessageREAD_v2 — Sample Payload

{
  "eventType": "sentMessageREAD_v2",
  "statusString": "Read",
  "id": "1a2b3b4d5e6f7g8h9i10j",
  "localMessageId": "...",
  "whatsappMessageId": "abcdefghi_jklmnop",
  "conversationId": "a1b2c3d4e5f6g7h8i9j10",
  "ticketId": "m1n2o3p4q5r6s7t8u9v10",
  "channelId": "...",
  "channelPhoneNumber": "85264318722",
  "text": null,
  "type": "template",
  "timestamp": "1665645642",
  "assigneeId": null,
  "operatorEmail": "[email protected]",
  "bsuid": "...",
  "parentBsuid": "...",
  "username": "..."
}

BSUID event variants

Wati supports _bsuid variants of webhook events. These payloads include bsuid, parentBsuid, and username fields to identify contacts by their BSUID — useful when contacts are referenced by BSUID in your system rather than by phone number.

4. How do I manage webhooks via API?

You can create, list, update, and delete webhooks programmatically.

Create a webhook (v2):

POST https://live-mt-server.wati.io/{tenantId}/api/v2/webhookEndpoints

List, get, update, and delete webhooks (v3 — recommended):

https://live-mt-server.wati.io/api/ext/v3/webhooks

v3 webhook management does not include /{tenantId}/ in the path. v3 is recommended for all new integrations.

For full details, see the Wati Webhooks Documentation.

General FAQs: Wati APIs & Webhooks