Номера

Номер — один аккаунт WhatsApp, Telegram или MAX. Здесь: список, заказ, настройки, срок оплаты и удаление.

Список номеров

GET/v1/accounts

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

Все номера клиента. Токены провайдера в ответе никогда не возвращаются.

Запрос

curl "https://msg.xaxu.am/v1/accounts" \
  -H "Authorization: Bearer $XM_API_KEY"

Ответ 200

{
  "accounts": [
    {
      "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
      "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "channel": "whatsapp",
      "label": "Отдел продаж",
      "idInstance": 7103123456,
      "wid": "79991234567@c.us",
      "state": "authorized",
      "stateChangedAt": "2026-10-01T08:12:40.000Z",
      "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
      "ingestMode": "webhook",
      "sendIntervalMs": 1500,
      "groupsEnabled": false,
      "billingStatus": "active",
      "paidUntil": "2026-11-09T23:59:59.999Z",
      "graceDays": 3,
      "provisionedVia": "partner",
      "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
      "createdAt": "2026-10-01T08:09:55.000Z",
      "capabilities": {
        "text": "yes",
        "file_upload": "yes",
        "poll": "yes",
        "forward": "yes",
        "stories": "yes",
        "…": "…"
      }
    }
  ]
}

Один номер

GET/v1/accounts/:id

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

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

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

id номера

Поля номера описаны в справочнике объектов.

Ошибки

404 not_found номера нет или он принадлежит другому клиенту

Запрос

curl "https://msg.xaxu.am/v1/accounts/{id}" \
  -H "Authorization: Bearer $XM_API_KEY"

Ответ 200

{
  "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "channel": "whatsapp",
  "label": "Отдел продаж",
  "idInstance": 7103123456,
  "wid": "79991234567@c.us",
  "state": "authorized",
  "stateChangedAt": "2026-10-01T08:12:40.000Z",
  "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
  "ingestMode": "webhook",
  "sendIntervalMs": 1500,
  "groupsEnabled": false,
  "billingStatus": "active",
  "paidUntil": "2026-11-09T23:59:59.999Z",
  "graceDays": 3,
  "provisionedVia": "partner",
  "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
  "createdAt": "2026-10-01T08:09:55.000Z",
  "capabilities": {
    "text": "yes",
    "file_upload": "yes",
    "poll": "yes",
    "forward": "yes",
    "stories": "yes",
    "…": "…"
  }
}

Заказать номер

POST/v1/accounts

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

Создаёт новый номер выбранного мессенджера. Номер появляется сразу в состоянии notAuthorized — дальше его нужно привязать к телефону.

Доступно, если оператор открыл вам самообслуживание (GET /v1/me → limits.remaining > 0). Новый номер работает trialDays дней без оплаты, потом продлевается оплатой.

Передавайте постоянный clientId (например, id вашей заявки): если ответ потерялся, повтор вернёт тот же номер (200), а не закажет второй.

Тело запроса

channel"whatsapp" | "telegram" | "max"обязательно

мессенджер

labelstring ≤ 200

название номера для себя

clientIdstring ≤ 100

ключ заказа против дублей

paidUntilдата

оплачено до — только если вы сами ведёте оплату (billingMode: tenant); вместо пробного периода

Ошибки

403	`quota_exceeded`	самообслуживание выключено или лимит номеров исчерпан (`details: {limit, used}`)
429	`rate_limited`	слишком много заказов за час
403	`billing_managed_by_platform`	передан `paidUntil`, а оплату ведёт платформа
400	`bad_request`	`paidUntil` в прошлом или дальше 10 лет
409	`order_in_progress`	заказ с этим `clientId` ещё выполняется — повторите через несколько секунд
409	`idempotency_mismatch`	`clientId` уже использован для другого мессенджера
409	`idempotency_key_used`	номер с этим `clientId` уже удалён — нужен новый `clientId`
422	`unsupported`	заказ номеров этого мессенджера сейчас недоступен

Запрос

curl -X POST "https://msg.xaxu.am/v1/accounts" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "label": "Отдел продаж",
    "clientId": "org-42-wa-1"
  }'

Ответ 201

{
  "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "channel": "whatsapp",
  "label": "Отдел продаж",
  "idInstance": 7103123456,
  "wid": null,
  "state": "notAuthorized",
  "stateChangedAt": "2026-10-01T08:12:40.000Z",
  "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
  "ingestMode": "webhook",
  "sendIntervalMs": 1500,
  "groupsEnabled": false,
  "billingStatus": "active",
  "paidUntil": "2026-11-09T23:59:59.999Z",
  "graceDays": 3,
  "provisionedVia": "partner",
  "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
  "createdAt": "2026-10-01T08:09:55.000Z",
  "capabilities": {
    "text": "yes",
    "file_upload": "yes",
    "poll": "yes",
    "forward": "yes",
    "stories": "yes",
    "…": "…"
  }
}

Изменить настройки номера

PATCH/v1/accounts/:id

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

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

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

id номера

Тело запроса

labelstring ≤ 200

название

sendIntervalMsint 0…600000

пауза между исходящими сообщениями номера, мс. Слишком маленькая пауза повышает риск блокировки

ingestMode"webhook" | "poll"

как шлюз забирает входящие у провайдера: вебхуком (по умолчанию) или опросом

groupsEnabledboolean

принимать и отправлять в группы и каналы (подробнее)

Ошибки

404 not_found номера нет или он принадлежит другому клиенту

Запрос

curl -X PATCH "https://msg.xaxu.am/v1/accounts/{id}" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"Ресепшен","groupsEnabled":false}'

Ответ 200

{
  "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "channel": "whatsapp",
  "label": "Ресепшен",
  "idInstance": 7103123456,
  "wid": "79991234567@c.us",
  "state": "authorized",
  "stateChangedAt": "2026-10-01T08:12:40.000Z",
  "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
  "ingestMode": "webhook",
  "sendIntervalMs": 1500,
  "groupsEnabled": false,
  "billingStatus": "active",
  "paidUntil": "2026-11-09T23:59:59.999Z",
  "graceDays": 3,
  "provisionedVia": "partner",
  "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
  "createdAt": "2026-10-01T08:09:55.000Z",
  "capabilities": {
    "text": "yes",
    "file_upload": "yes",
    "poll": "yes",
    "forward": "yes",
    "stories": "yes",
    "…": "…"
  }
}

Удалить номер

DELETE/v1/accounts/:id

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

Удаляет номер, который вы заказали сами: номер отключается у провайдера и перестаёт стоить денег; сам номер и его переписка через API больше недоступны (404). Номер, подключённый оператором, удаляет только оператор. Событие — account.deleted.

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

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

id номера

Ошибки

403	`forbidden`	номер подключён оператором — удалить может только он
404	`not_found`	номера нет или он принадлежит другому клиенту

Запрос

curl -X DELETE "https://msg.xaxu.am/v1/accounts/{id}" \
  -H "Authorization: Bearer $XM_API_KEY"

Ответ 200

{
  "deleted": true,
  "instanceDeleted": true
}

Обновить состояние номера

POST/v1/accounts/:id/refresh

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

Спрашивает у провайдера текущее состояние номера прямо сейчас (обычно шлюз проверяет его сам по расписанию).

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

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

id номера

Ошибки

404	`not_found`	номера нет или он принадлежит другому клиенту
502	`upstream_error`	провайдер мессенджера не ответил или ответил ошибкой — повторите позже

Запрос

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/refresh" \
  -H "Authorization: Bearer $XM_API_KEY"

Ответ 200

{
  "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "channel": "whatsapp",
  "label": "Отдел продаж",
  "idInstance": 7103123456,
  "wid": "79991234567@c.us",
  "state": "authorized",
  "stateChangedAt": "2026-10-01T08:12:40.000Z",
  "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
  "ingestMode": "webhook",
  "sendIntervalMs": 1500,
  "groupsEnabled": false,
  "billingStatus": "active",
  "paidUntil": "2026-11-09T23:59:59.999Z",
  "graceDays": 3,
  "provisionedVia": "partner",
  "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
  "createdAt": "2026-10-01T08:09:55.000Z",
  "capabilities": {
    "text": "yes",
    "file_upload": "yes",
    "poll": "yes",
    "forward": "yes",
    "stories": "yes",
    "…": "…"
  }
}

Задать срок оплаты номера

PUT/v1/accounts/:id/billing

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

Только для клиента, который сам берёт оплату со своих пользователей (billingMode: tenant, включает оператор). Дата в прошлом сразу выключает отправку (402), история сохраняется. Бессрочно (null) поставить нельзя.

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

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

id номера

Тело запроса

paidUntilдатаобязательно

оплачено до (ISO или YYYY-MM-DD — до конца дня UTC), не дальше 10 лет

graceDaysint 0…60

дней отсрочки после окончания срока

Ошибки

403	`billing_managed_by_platform`	оплату ваших номеров ведёт платформа
404	`not_found`	номера нет или он принадлежит другому клиенту

Запрос

curl -X PUT "https://msg.xaxu.am/v1/accounts/{id}/billing" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paidUntil":"2026-11-30","graceDays":3}'

Ответ 200

{
  "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "channel": "whatsapp",
  "label": "Отдел продаж",
  "idInstance": 7103123456,
  "wid": "79991234567@c.us",
  "state": "authorized",
  "stateChangedAt": "2026-10-01T08:12:40.000Z",
  "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
  "ingestMode": "webhook",
  "sendIntervalMs": 1500,
  "groupsEnabled": false,
  "billingStatus": "active",
  "paidUntil": "2026-11-30T23:59:59.999Z",
  "graceDays": 3,
  "provisionedVia": "partner",
  "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
  "createdAt": "2026-10-01T08:09:55.000Z",
  "capabilities": {
    "text": "yes",
    "file_upload": "yes",
    "poll": "yes",
    "forward": "yes",
    "stories": "yes",
    "…": "…"
  }
}

Продлить номер на N дней

POST/v1/accounts/:id/extend

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

Только billingMode: tenant. Продлевает от текущего срока (или от сегодня, если срок уже истёк) и сразу снова включает номер.

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

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

id номера

Тело запроса

daysint 1…3650обязательно

на сколько дней продлить

Ошибки

403	`billing_managed_by_platform`	оплату ваших номеров ведёт платформа
404	`not_found`	номера нет или он принадлежит другому клиенту

Запрос

curl -X POST "https://msg.xaxu.am/v1/accounts/{id}/extend" \
  -H "Authorization: Bearer $XM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"days":30}'

Ответ 200

{
  "id": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "channel": "whatsapp",
  "label": "Отдел продаж",
  "idInstance": 7103123456,
  "wid": "79991234567@c.us",
  "state": "authorized",
  "stateChangedAt": "2026-10-01T08:12:40.000Z",
  "lastStateCheckAt": "2026-10-10T09:30:00.000Z",
  "ingestMode": "webhook",
  "sendIntervalMs": 1500,
  "groupsEnabled": false,
  "billingStatus": "active",
  "paidUntil": "2026-11-09T23:59:59.999Z",
  "graceDays": 3,
  "provisionedVia": "partner",
  "settingsSyncedAt": "2026-10-01T08:10:02.000Z",
  "createdAt": "2026-10-01T08:09:55.000Z",
  "capabilities": {
    "text": "yes",
    "file_upload": "yes",
    "poll": "yes",
    "forward": "yes",
    "stories": "yes",
    "…": "…"
  }
}