Справочник объектов

Поля объектов, которые возвращает API и которые приходят в событиях.

Номер (Account)

Поле	Тип	Описание
`id`	uuid	id номера
`tenantId`	uuid	id клиента
`channel`	"whatsapp" \| "telegram" \| "max"	мессенджер
`label`	string	название для себя
`idInstance`	number	номер инстанса у провайдера (для обращений в поддержку)
`wid`	string \| null	адрес самого аккаунта в мессенджере после привязки
`state`	string	состояние: `authorized`, `notAuthorized`, `pendingPassword`…
`stateChangedAt, lastStateCheckAt`	дата	когда сменилось состояние и когда последний раз проверялось
`ingestMode`	"webhook" \| "poll"	как шлюз забирает входящие у провайдера
`sendIntervalMs`	int	пауза между исходящими, мс
`groupsEnabled`	boolean	приём и отправка в группы и каналы
`billingStatus`	"active" \| "grace" \| "suspended"	статус оплаты
`paidUntil`	дата \| null	оплачено до; `null` — без ограничения (только номера оператора)
`graceDays`	int	дней отсрочки после `paidUntil`
`provisionedVia`	"partner" \| "manual"	заказан через API / подключён оператором вручную
`settingsSyncedAt`	дата \| null	когда настройки последний раз переданы провайдеру
`createdAt`	дата	когда создан
`capabilities`	object	что умеет мессенджер: `{feature: "yes" \| "unverified" \| "no"}` (таблица)

Пример

{
  "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",
    "…": "…"
  }
}

Чат (Chat)

Поле	Тип	Описание
`id`	uuid	id чата
`accountId`	uuid	номер, к которому относится чат
`externalId`	string	адрес чата в мессенджере — его передают в `to.chatId`
`kind`	"direct" \| "group" \| "channel" \| "unknown"	личный чат, группа или канал
`title`	string \| null	название (имя собеседника или группы)
`contactName`	string \| null	имя контакта из адресной книги
`phone`	string \| null	телефон собеседника в личном чате (цифры без `+`); `null`, если неизвестен или скрыт
`avatarUrl`	string \| null	аватар
`lastMessageAt`	дата \| null	время последнего сообщения
`unreadCount`	int	непрочитанных входящих
`archived`	boolean	в архиве

Пример

{
  "id": "9e2f7a1c-3b4d-4e5f-8a6b-7c8d9e0f1a2b",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "externalId": "79181234567@c.us",
  "kind": "direct",
  "title": "Анна",
  "contactName": "Анна",
  "phone": "79181234567",
  "avatarUrl": null,
  "lastMessageAt": "2026-10-10T09:28:11.000Z",
  "unreadCount": 2,
  "archived": false
}

Сообщение (Message)

Поле	Тип	Описание
`id`	uuid	id сообщения
`accountId, chatId`	uuid	номер и чат
`externalId`	string \| null	id в мессенджере; у исходящего появляется после отправки
`clientId`	string \| null	ваш ключ операции, если передавали
`direction`	"in" \| "out"	входящее / исходящее
`origin`	"contact" \| "api" \| "phone"	кто создал: собеседник, ваш API или владелец номера с телефона
`kind`	string	`text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `contacts`, `poll`, `poll_vote`, `reaction`, `buttons`, `list`, `template`, `group_invite`, `unknown`
`text`	string \| null	текст или подпись
`data`	object	данные своего типа: координаты, контакт, варианты и итоги опроса…
`quotedExternalId`	string \| null	на какое сообщение это ответ (id мессенджера)
`sender`	{id, name, phone}	отправитель; `phone` — только у входящих личных чатов, никогда не номер вашего аккаунта и не номер участника группы
`status`	string	статус (ниже)
`statusDetail`	string \| null	пояснение, например причина `failed`
`sentAt`	дата \| null	время отправки
`editedAt, deletedAt`	дата \| null	когда отредактировано / удалено
`attachments`	Attachment[]	файлы сообщения
`reactions`	{actor, emoji}[]	реакции

Пример

{
  "id": "0b8e4d2a-6c1f-4a3e-9b7d-5e2f1c0a9d8b",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "chatId": "9e2f7a1c-3b4d-4e5f-8a6b-7c8d9e0f1a2b",
  "externalId": "BAE5F4C1D2A3B4C5",
  "clientId": null,
  "direction": "in",
  "origin": "contact",
  "kind": "text",
  "text": "Здравствуйте! Есть свободные номера на выходные?",
  "data": {},
  "quotedExternalId": null,
  "sender": {
    "id": "79181234567@c.us",
    "name": "Анна",
    "phone": "79181234567"
  },
  "status": "received",
  "statusDetail": null,
  "sentAt": "2026-10-10T09:28:11.000Z",
  "editedAt": null,
  "deletedAt": null,
  "attachments": [],
  "reactions": []
}

Статусы сообщения

`status`	Что значит
`queued`	в очереди номера в шлюзе
`sending`	передано провайдеру
`sent`	ушло в мессенджер (одна галочка)
`delivered`	доставлено на телефон получателя (две галочки)
`read`	прочитано
`failed`	не отправлено; причина — в `statusDetail`
`received`	входящее сообщение (становится `read` после «прочитано»)

Статус только растёт: queued → sending → sent → delivered → read. Опоздавшая отметка «доставлено» после «прочитано» статус назад не вернёт; failed может заменить только queued, sending или sent.

Файл (Attachment)

Поле	Тип	Описание
`id`	uuid	id файла
`messageId`	uuid \| null	сообщение (у загруженного, но ещё не отправленного — `null`)
`direction`	"in" \| "out"	входящий / загруженный вами
`kind`	string	`image`, `video`, `audio`, `document`, `sticker`
`fileName, mimeType`	string	имя и тип
`sizeBytes`	int \| null	размер
`sha256`	string \| null	контрольная сумма
`caption`	string \| null	подпись
`status`	"pending" \| "stored" \| "failed" \| "expired"	скачивается / готов / ошибка / ссылка у провайдера истекла
`error`	string \| null	причина ошибки
`createdAt, storedAt`	дата	когда создан и сохранён
`contentUrl`	string \| null	адрес байтов: `GET` с вашим ключом (когда `stored`)

Пример

{
  "id": "f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b",
  "messageId": "0b8e4d2a-6c1f-4a3e-9b7d-5e2f1c0a9d8b",
  "direction": "in",
  "kind": "image",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "sizeBytes": 184213,
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "caption": "Вот так выглядит номер",
  "status": "stored",
  "error": null,
  "createdAt": "2026-10-10T09:28:11.000Z",
  "storedAt": "2026-10-10T09:28:12.000Z",
  "contentUrl": "/v1/attachments/f1a2b3c4-d5e6-4f70-8a9b-0c1d2e3f4a5b/content"
}

Сторис (Story)

Поле	Тип	Описание
`id`	uuid	id сторис
`accountId`	uuid	номер
`externalId`	string \| null	id у провайдера
`direction`	"in" \| "out"	чужая / своя
`kind`	"text" \| "media" \| "voice"	вид
`text, caption, backgroundColor, font`	string \| null	содержимое и оформление
`attachmentId`	uuid \| null	файл
`sender`	{id, name}	автор входящей сторис
`participants`	string[] \| null	кому показывается
`status, statusDetail`	string	статус отправки
`postedAt, deletedAt`	дата \| null	когда опубликована / удалена
`views`	{viewer, status, viewedAt}[]	кто посмотрел (после `refresh-views`)

Пример

{
  "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": []
}

Счёт (Payment)

Поле	Тип	Описание
`id`	uuid	id счёта
`invoiceNumber`	int	номер счёта (для поддержки и листания)
`tenantId, accountId`	uuid	клиент и номер
`status`	"pending" \| "paid"	ждёт оплаты / оплачен
`amountMinor, currency`	int, string	сумма в копейках и валюта
`periods, days`	int	сколько периодов и дней продления
`isTest`	boolean	тестовый счёт — номер не продлевает
`email`	string \| null	адрес для чека
`description`	string	назначение платежа
`createdAt, paidAt`	дата	создан / оплачен
`credited`	boolean	номер продлён по этому счёту
`payUrl`	string \| null	ссылка на оплату (пока счёт не оплачен)

Пример

{
  "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
  "invoiceNumber": 1042,
  "tenantId": "c3d4e5f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "accountId": "5b1e9c3a-8f2d-4c71-9a0e-2d6f1b7c4e10",
  "status": "pending",
  "amountMinor": 299000,
  "currency": "RUB",
  "periods": 1,
  "days": 30,
  "isTest": false,
  "email": "buh@example.ru",
  "description": "Номер WhatsApp «Отдел продаж», 30 дней",
  "createdAt": "2026-10-10T09:40:00.000Z",
  "paidAt": null,
  "credited": false,
  "note": null,
  "payUrl": "https://auth.robokassa.ru/Merchant/Index.aspx?…"
}

Событие (Event)

Поле	Тип	Описание
`id`	int	номер события, растёт монотонно
`type`	string	тип события
`createdAt`	дата	когда произошло
`tenantId`	uuid	клиент (в вебхуке)
`accountId`	uuid \| null	номер
`data`	object	содержимое своего типа