Messages#

With the API, a bot can write to a contact from your own system: remind them of an appointment, send a receipt, reply from a CRM. Use the sendMessage method for this — it sends text, an image or a file right away and tells you whether the message went out.

The sendMessageToQueue method is deprecated and will be switched off — use sendMessage in new integrations.

The message is saved in the contact's conversation under the name "API" — you can see it in Conversations and messaging. It does not start the bot's scenario.

sendMessage#

Sends a contact text, an image or a file.

The contact is specified in one of two ways: by contact ID — contact_id, or by bot and messenger ID — bot_id, messenger and contact_external_id together.

What to pass in contact_external_id:

The phone is compared with the contact's number (the phone field in the contact methods' responses) character for character. The most reliable option is contact_id — the contact methods return it.

If both image and file are passed, the image is sent.

curl -X POST "https://watbot.org/api/v1/sendMessage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "text": "Emily, your order #1042 has been shipped."}'

curl -X POST "https://watbot.org/api/v1/sendMessage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": 12345,
    "messenger": "telegram",
    "contact_external_id": "123456789",
    "file": "https://example.com/invoices/1042.pdf",
    "filename": "Invoice 1042.pdf",
    "text": "Your invoice"
  }'

{
  "success": true
}

{
  "message": "Contact not found"
}

Sending limit. No more than 10 messages per 10 seconds to one messenger. The counter is kept per account and separately for each messenger: the 10 seconds start with the first message, then the counter resets. Rejected requests do not count and do not extend the window. A 429 response carries a Retry-After header with the number of seconds to wait before retrying. The general API rate limit applies separately — see Limits.

Method errors (general ones are under Errors):

Error texts come in the language from the Accept-Language header.

sendMessageToQueue#

Warning

This method is deprecated and will be switched off on 1 December 2026 — use sendMessage instead. Until then, every response of the method carries the headers Deprecation: true and Sunset: Tue, 01 Dec 2026 00:00:00 GMT. From 1 December 2026 (00:00 UTC), the method responds with status 410: {"error": "This API method was removed on 2026-12-01.", "code": "method_removed"}.

Puts a text message to a contact in a queue. The queue is processed once a minute.

The contact is looked up among the contacts of all your bots, or, with bot_id, only among that bot's contacts. Pass at least one of contact_id, bitrix_contact_id, phone; if you pass several, the contact must match all of them. If several contacts match phone or bitrix_contact_id and bot_id is not passed, the message is queued for one of them: first a contact of a messenger the method can send to who has not blocked the bot, then one whose phone field (WhatsApp) matches exactly, then the one with the most recent conversation. The response headers X-Contact-Id and X-Contact-Ambiguous: true show who the message went to. With bot_id no choice is made: if several contacts of that bot match too, the method responds with 422 and does not queue the message — pass contact_id.

curl -X POST "https://watbot.org/api/v1/sendMessageToQueue" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "text": "Reminder: your appointment is tomorrow at 11:00 AM."}'

{
  "error": "Contact not found"
}

{
  "message": "Several contacts of the bot match this data — specify contact_id.",
  "errors": {
    "contact_id": ["Several contacts of the bot match this data — specify contact_id."]
  }
}

A successful response is status 201 with an empty body and the chosen contact's ID in the X-Contact-Id header. The cleaned-up phone must match the contact's number character for character. For a contact from a channel that sending is no longer supported for, the method responds with 422: {"error": "Messenger is not supported"}. Contacts who have unsubscribed from the bot or blocked it do not receive messages from the queue — such messages are removed from the queue on its next run.