xaxumessageAPI
Методы API

Сторис (WhatsApp)

Статусы WhatsApp: публикация, входящие сторис контактов и просмотры.

Опубликовать сторис

POST/v1/accounts/:id/stories
API-ключ клиентаУспех: 202

Статус WhatsApp (сторис) с номера. Увидят его только контакты, у которых сохранён ваш номер и у вас — их. Провайдер помечает функцию как бета.

WhatsAppдаTelegramнетMAXнет

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

iduuidобязательно
id номера

Тело запроса

type"text" | "media" | "voice"обязательно
текст на фоне, фото/видео или голосовое
textstring ≤ 700
text: текст
backgroundColorstring
text, voice: цвет фона, например #228B22
fontstring
text: шрифт, например SERIF
attachmentId / urluuid / url
media, voice: файл
fileNamestring
media, voice: имя файла
captionstring ≤ 700
media: подпись
participantsstring[]
кому показывать (номера); не указано — всем контактам

Ошибки

409billing_suspendedномер приостановлен за неоплату
409attachment_not_readyфайл ещё не сохранён
422unsupportedмессенджер номера не умеет эту операцию
404not_foundномера нет или он принадлежит другому клиенту
Текст
curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/stories" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "text": "Скидки сегодня!",
    "backgroundColor": "#228B22",
    "font": "SERIF"
  }'
Фото
curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/stories" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "media",
    "attachmentId": "f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
    "caption": "Новинки"
  }'
Голосовое
curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/stories" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "url": "https://example.ru/hello.mp3",
    "fileName": "hello.mp3",
    "backgroundColor": "#112233"
  }'
Ответ 202
{
  "id": "7d6c5b4a-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "externalId": null,
  "direction": "out",
  "kind": "text",
  "text": "Скидки сегодня!",
  "caption": null,
  "backgroundColor": "#228B22",
  "font": "SERIF",
  "attachmentId": null,
  "sender": {
    "id": null,
    "name": null
  },
  "participants": null,
  "status": "queued",
  "statusDetail": null,
  "postedAt": null,
  "deletedAt": null,
  "views": []
}

Сторис номера

GET/v1/accounts/:id/stories
API-ключ клиентаУспех: 200

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

iduuidобязательно
id номера

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

direction"in" | "out"
входящие (от контактов) или свои
limitint 1…200
сколько вернуть

Ошибки

404not_foundномера нет или он принадлежит другому клиенту
Запрос
curl "https://msg.xaxu.am/v1/accounts/{id}/stories?direction=out&limit=20" \
  -H "Authorization: Bearer $XM_API_KEY"
Ответ 200
{
  "stories": [
    {
      "id": "7d6c5b4a-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
      "externalId": "BAE5C0FFEE",
      "direction": "out",
      "kind": "text",
      "text": "Скидки сегодня!",
      "caption": null,
      "backgroundColor": "#228B22",
      "font": "SERIF",
      "attachmentId": null,
      "sender": {
        "id": null,
        "name": null
      },
      "participants": null,
      "status": "sent",
      "statusDetail": null,
      "postedAt": "2026-10-10T10:00:03.000Z",
      "deletedAt": null,
      "views": []
    }
  ]
}

Подтянуть сторис

POST/v1/accounts/:id/stories/sync
API-ключ клиентаУспех: 200

Входящие сторис провайдер вебхуком не присылает — их забирают этим методом (или шлюз сам по расписанию, если оператор включил).

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

iduuidобязательно
id номера

Тело запроса

minutesint 1…1440
за сколько последних минут (по умолчанию сутки)

Ошибки

404not_foundномера нет или он принадлежит другому клиенту
502upstream_errorпровайдер мессенджера не ответил или ответил ошибкой — повторите позже
Запрос
curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/stories/sync" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minutes":1440}'
Ответ 200
{
  "created": 3
}

Одна сторис

GET/v1/stories/:id
API-ключ клиентаУспех: 200

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

iduuidобязательно
id сторис

Ошибки

404not_foundсторис нет или он принадлежит другому клиенту
Запрос
curl "https://msg.xaxu.am/v1/stories/{id}" \
  -H "Authorization: Bearer $XM_API_KEY"
Ответ 200
{
  "id": "7d6c5b4a-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "externalId": null,
  "direction": "out",
  "kind": "text",
  "text": "Скидки сегодня!",
  "caption": null,
  "backgroundColor": "#228B22",
  "font": "SERIF",
  "attachmentId": null,
  "sender": {
    "id": null,
    "name": null
  },
  "participants": null,
  "status": "queued",
  "statusDetail": null,
  "postedAt": null,
  "deletedAt": null,
  "views": []
}

Обновить просмотры

POST/v1/stories/:id/refresh-views
API-ключ клиентаУспех: 200

Запрашивает у провайдера, кто посмотрел свою отправленную сторис; результат — в views.

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

iduuidобязательно
id сторис

Ошибки

409story_not_sentсторис не своя или ещё не отправлена
404not_foundсторис нет или он принадлежит другому клиенту
Запрос
curl -X POST "https://msg.xaxu.am/v1/stories/{id}/refresh-views" \
  -H "Authorization: Bearer $XM_API_KEY"
Ответ 200
{
  "id": "7d6c5b4a-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "externalId": null,
  "direction": "out",
  "kind": "text",
  "text": "Скидки сегодня!",
  "caption": null,
  "backgroundColor": "#228B22",
  "font": "SERIF",
  "attachmentId": null,
  "sender": {
    "id": null,
    "name": null
  },
  "participants": null,
  "status": "sent",
  "statusDetail": null,
  "postedAt": null,
  "deletedAt": null,
  "views": [
    {
      "viewer": "79181234567@c.us",
      "status": "read",
      "viewedAt": "2026-10-10T11:02:00.000Z"
    }
  ]
}

Удалить сторис

DELETE/v1/stories/:id
API-ключ клиентаУспех: 202

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

iduuidобязательно
id сторис

Ошибки

404not_foundсторис нет или он принадлежит другому клиенту
Запрос
curl -X DELETE "https://msg.xaxu.am/v1/stories/{id}" \
  -H "Authorization: Bearer $XM_API_KEY"
Ответ 202
{
  "accepted": true
}