Отправка сообщений

Текст, файлы, геолокация, контакт, опрос и пересылка — одним методом. Правка и удаление своих сообщений.

Отправить сообщение

POST/v1/accounts/:id/messages

API-ключ клиентаУспех: 202

Ставит сообщение в очередь номера и сразу отвечает 202 с сообщением в статусе queued. Дальше статус меняется sending → sent → delivered → read (или failed) — это приходит событиями message.status.

Тип сообщения задаёт поле type. Общие поля — для всех типов, остальные — у своего типа.

Параметры пути

iduuidобязательно

id номера

Тело запроса

тип сообщения

to.chatIdstring

адрес чата в мессенджере (externalId чата): 79991234567@c.us, id чата Telegram/MAX

to.phonestring

телефон получателя — только WhatsApp. Нужно одно из двух: to.chatId или to.phone

clientIdstring ≤ 100

ваш ключ операции: повтор с тем же clientId не отправит второй раз (подробнее)

quote.messageIduuid

ответить цитатой на сообщение (наш id)…

quote.externalIdstring

…или на сообщение по id мессенджера

typingTimeint, мс ≤ 60000

показать «печатает…» перед отправкой

textstring ≤ 20000

text: текст сообщения

linkPreviewboolean

text: показывать превью ссылки

attachmentIduuid

file: файл, загруженный через /v1/attachments…

urlurl

file: …или ссылка, по которой провайдер сам скачает файл

fileNamestring ≤ 255

file: имя файла у получателя

captionstring ≤ 4096

file: подпись

latitude, longitudenumber

location: координаты

name, addressstring

location: название места и адрес

contact{phone, firstName?, lastName?, company?}

contact: карточка контакта

question, options[], multipleAnswersstring, string[2…12], boolean

poll: вопрос, варианты, можно ли несколько ответов

messageIdsuuid[1…100]

forward: наши id сообщений для пересылки

Возможность	WhatsApp	Telegram	MAX
Текст `text`	да	да	да
Файл по ссылке `file_url`	да	да	да
Загрузка файла `file_upload`	да	да	да
Опрос `poll`	да	да	нет
Геолокация `location`	да	да	не проверено
Контакт `contact`	да	да	не проверено
Пересылка `forward`	да	нет	не проверено

Ответ 200 вместо 202 значит, что сообщение с таким clientId уже было принято раньше — второй раз оно не отправляется.

Ошибки

400	`bad_request`	не прошёл проверку (например, `to.phone` для Telegram/MAX — им нужен `chatId`)
402	`billing_suspended`	номер приостановлен за неоплату
409	`account_not_ready`	номер не авторизован / заблокирован / ждёт облачный пароль
409	`groups_disabled`	адресат — группа, а группы у номера выключены
409	`attachment_not_ready`	файл ещё не сохранён
409	`quote_not_sent / forward_not_sent`	цитируемое или пересылаемое сообщение ещё не отправлено
422	`unsupported`	мессенджер номера не умеет эту операцию
404	`not_found`	номера нет или он принадлежит другому клиенту

Текст по номеру телефона (WhatsApp)

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "to": {
      "phone": "+7 999 123-45-67"
    },
    "text": "Здравствуйте!",
    "clientId": "order-1001-notify"
  }'

Ответ в чат с цитатой

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "text": "Да, есть 👍",
    "quote": {
      "messageId": "0b8e4d2a-6c1f-4a3e-9b7d-5e2f1c0a9d8b"
    }
  }'

Файл, загруженный заранее

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "attachmentId": "f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
    "caption": "Счёт №42"
  }'

Файл по ссылке

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "url": "https://example.ru/price.pdf",
    "fileName": "price.pdf"
  }'

Геолокация

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "location",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "latitude": 44.894,
    "longitude": 37.316,
    "name": "Офис",
    "address": "Анапа, ул. Пушкина, 1"
  }'

Контакт

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contact",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "contact": {
      "phone": "+79990001122",
      "firstName": "Ирина",
      "lastName": "Смирнова",
      "company": "Ресепшен"
    }
  }'

Опрос (не в MAX)

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "poll",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "question": "Во сколько удобно заселиться?",
    "options": [
      "12:00",
      "14:00",
      "16:00"
    ],
    "multipleAnswers": false
  }'

Переслать сообщения

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/messages" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "forward",
    "to": {
      "chatId": "79991234567@c.us"
    },
    "messageIds": [
      "0b8e4d2a-6c1f-4a3e-9b7d-5e2f1c0a9d8b"
    ]
  }'

Ответ 202

{
  "id": "0b8e4d2a-6c1f-4a3e-9b7d-5e2f1c0a9d8b",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "chatId": "9e2f7a1c-3b4d-4e5f-8a6b-7c8d9e0f1a2b",
  "externalId": null,
  "clientId": "order-1001-notify",
  "direction": "out",
  "origin": "api",
  "kind": "text",
  "text": "Здравствуйте!",
  "data": {},
  "quotedExternalId": null,
  "sender": {
    "id": null,
    "name": null,
    "phone": null
  },
  "status": "queued",
  "statusDetail": null,
  "sentAt": null,
  "editedAt": null,
  "deletedAt": null,
  "attachments": [],
  "reactions": []
}

Изменить текст сообщения

PATCH/v1/messages/:id

API-ключ клиентаУспех: 202

Только свои отправленные текстовые сообщения. Мессенджер ограничивает время на правку (WhatsApp — около 15 минут).

WhatsAppдаTelegramдаMAXне проверено

Параметры пути

iduuidобязательно

id своего исходящего сообщения

Тело запроса

textstring ≤ 20000обязательно

новый текст

Ошибки

409	`message_not_sent`	сообщение ещё не ушло
409	`message_deleted`	сообщение удалено
422	`unsupported`	мессенджер номера не умеет эту операцию
404	`not_found`	сообщения нет или он принадлежит другому клиенту

Запрос

curl -X PATCH "https://msg.xaxu.am/v1/messages/{id}" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Здравствуйте! Исправленный текст."}'

Ответ 202

{
  "accepted": true
}

Удалить сообщение

DELETE/v1/messages/:id

API-ключ клиентаУспех: 202

WhatsAppдаTelegramдаMAXне проверено

Параметры пути

iduuidобязательно

id сообщения

Параметры запроса

forEveryoneboolean

true (по умолчанию) — удалить у всех, false — только у себя

Ошибки

409	`message_not_sent`	сообщение ещё не ушло
422	`unsupported`	мессенджер номера не умеет эту операцию
404	`not_found`	сообщения нет или он принадлежит другому клиенту

Запрос

curl -X DELETE "https://msg.xaxu.am/v1/messages/{id}?forEveryone=true" \
  -H "Authorization: Bearer $XM_API_KEY"

Ответ 202

{
  "accepted": true
}