---
title: Справочные эндпоинты
description: Справочные эндпоинты OMNI API Multi API — каналы, отправители, баланс, шаблоны, Telegram Gateway
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://iba-platform.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.



> **Коротко:** кроме отправки сообщений, OMNI API предоставляет справочные методы — узнать доступные каналы, статус отправителей, баланс, шаблоны и работу Telegram Gateway.

## Кому подходит

- Роль: Разработчик, Интегратор
- Уровень: Опытный

## Что это

Справочные эндпоинты возвращают данные, которые нужны для настройки и проверки интеграции. Они не отправляют сообщения, а показывают текущее состояние вашего аккаунта.

| Метод | Эндпоинт | Для чего |
|---|---|---|
| GET | `/channels` | Список каналов, доступных компании |
| GET | `/senders` | Список имён отправителей |
| GET | `/balance` | Баланс договора |
| GET | `/templates` | Список шаблонов сообщений |
| GET | `/wa_templates` | Список шаблонов WhatsApp |
| POST | `/messages/revoke` | Отозвать верификационное сообщение Telegram Gateway |
| POST | `/messages/verification` | Проверить статус верификации Telegram Gateway |

## Каналы, доступные компании

**Эндпоинт:** `GET /channels`

Возвращает список каналов, которые подключены у вашей компании. Не все каналы из общей таблицы могут быть доступны — этот метод покажет фактические.

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/channels' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Успешный ответ `200 OK`:**

```json
{
  "error": false,
  "data": [
    {
      "id": 1,
      "type": "SMS",
      "description": "Sms channel type"
    },
    {
      "id": 2,
      "type": "RCS",
      "description": "Rcs channel type"
    },
    {
      "id": 3,
      "type": "VIBER",
      "description": "Viber channel type"
    },
    {
      "id": 4,
      "type": "WHATSAPP",
      "description": "Whatsapp channel type"
    },
    {
      "id": 6,
      "type": "WECHAT",
      "description": "Wechat channel type"
    },
    {
      "id": 7,
      "type": "EMAIL",
      "description": "Email channel type"
    },
    {
      "id": 8,
      "type": "TELEGRAM_GATEWAY",
      "description": "Telegram Gateway"
    },
    {
      "id": 10,
      "type": "PUSH",
      "description": "Push"
    },
    {
      "id": 11,
      "type": "TTS",
      "description": "Text To Speech (TTS)"
    },
    {
      "id": 14,
      "type": "FLASH_CALL",
      "description": "Flash call"
    }
  ]
}
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| id | Номер канала (совпадает с номером в общем списке) |
| type | Техническое имя канала (`SMS`, `WHATSAPP`, `TTS` и т. д.) |
| description | Описание канала |

<Note>
Если нужного канала нет в списке — его можно подключить. Обратитесь в поддержку Multi API: support@multiapi.ru.
</Note>

## Имена отправителей

**Эндпоинт:** `GET /senders`

Возвращает список имён отправителей компании с их статусами и каналами.

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/senders' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Успешный ответ `200 OK`:**

```json
{
  "data": [
    {
      "channel": 1,
      "displayName": "SMS Sender",
      "senderId": "1112223334",
      "status": 2,
      "vendorType": "transit_http_sms",
      "webhookGuid": "8ed6b786-9701-4984-9c50-bc2c66b2ffed",
      "webhookUrl": "https://test.site.com/webhook"
    }
  ],
  "error": false
}
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| channel | Номер канала, к которому привязано имя |
| displayName | Отображаемое имя |
| senderId | Технический идентификатор отправителя |
| status | Статус отправителя (см. таблицу ниже) |
| vendorType | Тип провайдера |
| webhookGuid | GUID вебхука |
| webhookUrl | URL вебхука для статусов |

**Статусы отправителя:**

| Код | Статус | Что означает |
|---|---|---|
| -1 | Blocked | Заблокировано |
| 0 | Draft | Черновик |
| 1 | In tests | На тестировании |
| 2 | Active | Активно |

**Когда использовать:**

- Проверить, что имя отправителя имеет статус `2` (Active) перед отправкой.
- Узнать, к какому каналу привязано имя.
- Проверить, что новое имя уже одобрено.

## Баланс договора

**Эндпоинт:** `GET /balance`

Возвращает баланс по всем договорам компании. У одной компании может быть несколько договоров — каждый со своим балансом.

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/balance' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Успешный ответ `200 OK`:**

```json
[
  {
    "agreementId": 0,
    "amount": 0,
    "balanceId": 0,
    "currency": "string",
    "name": "string"
  }
]
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| agreementId | ID договора |
| amount | Сумма баланса |
| balanceId | ID баланса |
| currency | Валюта баланса |
| name | Название договора |

<Note>
Этот эндпоинт возвращает **массив**, а не объект с `error` и `data`. Каждый элемент массива — баланс отдельного договора.
</Note>

**Когда использовать:**

- Перед массовой отправкой — убедиться, что баланса достаточно.
- В мониторинге — проверять баланс автоматически.
- При интеграции с биллингом — синхронизировать данные.

## Шаблоны сообщений

**Эндпоинт:** `GET /templates`

Возвращает список шаблонов сообщений компании.

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/templates' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Успешный ответ `200 OK`:**

```json
{
  "data": [
    {
      "channel": 4,
      "company_id": 1,
      "content": "{\"suggestionsInside\":[],\"cards\":[],\"selectedType\":\"whatsAppText\",\"preview_url\":true,\"text\":{\"body\":\"_test_\"}}",
      "created_at": "2025-01-23T18:31:35.587814Z",
      "created_by": "string",
      "id": 1,
      "message": "{text: {body: \"_test_\"}, type: \"text\", preview_url: true, recipient_type: \"individual\"}",
      "name": "wa_test",
      "updated_at": "2025-01-23T18:31:35.587823Z",
      "updated_by": "string"
    }
  ],
  "error": false,
  "size": 135
}
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| id | ID шаблона — используется в `template.id` при отправке |
| channel | Номер канала |
| company_id | ID компании |
| name | Название шаблона |
| content | Содержимое в виде JSON-строки |
| message | Содержимое в упрощённом виде |
| created_at, updated_at | Даты создания и обновления |
| created_by, updated_by | Кто создал и обновил |
| size | Общее количество шаблонов |

**Когда использовать:**

- Получить ID шаблона для отправки через `template.id`.
- Проверить, что шаблон создан.
- Синхронизировать шаблоны между своей системой и платформой.

## Шаблоны WhatsApp

**Эндпоинт:** `GET /wa_templates`

Возвращает список шаблонов WhatsApp со статусами одобрения.

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/wa_templates' \
  --header 'X-API-Key: <ваш-ключ>'
```

**Успешный ответ `200 OK`:**

```json
{
  "data": [
    {
      "category": "MARKETING",
      "content": "[{\"text\": \"1\", \"type\": \"BODY\"}]",
      "created_at": "2025-01-23T18:31:35.587823Z",
      "description": "my_favorite_template",
      "id": 1,
      "language": "en",
      "language_name_en": "English",
      "last_synced_at": "2025-01-23T18:31:35.587823Z",
      "rejection_reason": "custom_reason",
      "sender_display_name": "MySender",
      "sender_id": "test_sender",
      "status": "APPROVED",
      "status_updated_at": "2025-01-23T18:31:35.587814Z",
      "template_name": "test_template",
      "updated_at": "2025-01-23T18:31:35.587823Z"
    }
  ],
  "error": false,
  "size": 135
}
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| id | ID шаблона |
| template_name | Имя шаблона |
| category | Категория: `MARKETING`, `UTILITY`, `AUTHENTICATION` |
| language | Код языка |
| language_name_en | Название языка на английском |
| sender_id | ID отправителя |
| sender_display_name | Отображаемое имя отправителя |
| status | Статус одобрения |
| rejection_reason | Причина отклонения (если есть) |
| content | Содержимое в виде JSON-строки |
| description | Описание |
| last_synced_at | Когда последний раз синхронизировался с Meta |
| status_updated_at | Когда изменился статус |
| size | Общее количество шаблонов |

**Когда использовать:**

- Проверить статус одобрения шаблона в WhatsApp.
- Найти ID шаблона для отправки через `template.id`.
- Узнать причину отклонения.

## Telegram Gateway: отзыв сообщения

**Эндпоинт:** `POST /messages/revoke`

Отзывает ранее отправленное верификационное сообщение Telegram Gateway. Например, если пользователь запросил новый код — старый нужно отозвать, чтобы он не сработал.

**Тело запроса:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| messageId | string | Да | ID сообщения, которое нужно отозвать |

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/messages/revoke' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "messageId": "019372a1-d252-7908-9216-028bd36c7af1"
  }'
```

**Успешный ответ `200 OK`:**

```json
{
  "error": "string",
  "message_id": "019372a1-d252-7908-9216-028bd36c7af1",
  "success": true
}
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| success | `true` — сообщение отозвано |
| message_id | ID отозванного сообщения |
| error | Описание ошибки, если есть |

**Когда использовать:**

- Пользователь запросил повторную отправку кода.
- Отправка устарела или была ошибочной.

## Telegram Gateway: проверка статуса

**Эндпоинт:** `POST /messages/verification`

Проверяет статус доставки и верификации в Telegram Gateway.

**Тело запроса:**

| Поле | Тип | Обязательно | Что указать |
|---|---|---|---|
| messageId | string | Да | ID сообщения |
| code | string | Да | Код, который нужно проверить |

**Пример запроса:**

```bash
curl --location 'https://web.multiapi.ru/api/v1/messages/verification' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "messageId": "019372a1-d252-7908-9216-028bd36c7af1",
    "code": "1234"
  }'
```

**Успешный ответ `200 OK`:**

```json
{
  "delivery_status": "read",
  "error": "string",
  "message_id": "019372a1-d252-7908-9216-028bd36c7af1",
  "success": true,
  "verification_status": "code_valid"
}
```

**Поля ответа:**

| Поле | Что означает |
|---|---|
| success | `true` — запрос обработан |
| message_id | ID сообщения |
| delivery_status | Статус доставки (например, `read`) |
| verification_status | Статус проверки кода (например, `code_valid`) |
| error | Описание ошибки, если есть |

**Когда использовать:**

- Узнать, верифицирован ли пользователь.
- Проверить, что код дошёл до получателя.
- Диагностировать проблему, если код не пришёл.

## Коды ответов

| Код | Когда возвращается |
|---|---|
| 200 OK | Запрос обработан успешно |
| 400 Bad Request | Неверный запрос |
| 401 Unauthorized | Неверный или отсутствующий API-ключ |
| 404 Not Found | Ресурс не найден |
| 500 Internal Server Error | Внутренняя ошибка на стороне платформы |

<Note>
Все ошибки возвращают единый формат: `{"error": true, "data": {"message": "...", "requestId": "..."}}`. Подробнее: [Обработка ошибок API](https://iba-platform.jamdesk.app/06-reference/01-api/api-errors).
</Note>

<Note>
**Исключение — `GET /balance`:** для него документирован только код `500 Internal Server Error`. Если баланс не получен — обратитесь в поддержку сервиса.
</Note>

## Лимиты

На один канал действует ограничение — **не более 5 одновременных запросов на отправку**.

Сообщения становятся в очередь и отправляются асинхронно. Отправка и получение статуса не зависят друг от друга.

Если нужно больше — лимит увеличивается до фактического потребления по запросу в поддержку сервиса.

При превышении лимита API возвращает код **`429 Too Many Requests`**.

## Частые проблемы

<Accordion title="401 Unauthorized">
**Причина:** заголовок `X-API-Key` не передан или ключ неверный.

**Решение:** проверьте заголовок. Подробнее: [Ошибка 401](https://iba-platform.jamdesk.app/06-reference/03-troubleshooting/ts-mapi-401).
</Accordion>

<Accordion title="403 Forbidden">
**Причина:** у ключа нет нужного scope.

**Решение:** откройте ключ в разделе **API Подключения** и добавьте нужный scope.
</Accordion>

<Accordion title="429 Too Many Requests">
**Причина:** превышен лимит одновременных запросов на канал.

**Решение:** дождитесь обработки очереди. Если лимит критично низкий — обратитесь в поддержку сервиса.
</Accordion>

## См. также

<Columns cols={2}>
  <Card title="OMNI API — отправка сообщений" icon="paper-plane" href="/03-multiapi/02-api/mapi-103-omni-api">
    Эндпоинты `/messages`, `/omnimessages`
  </Card>
  <Card title="Broadcasts API" icon="bullhorn" href="/03-multiapi/02-api/mapi-105-broadcasts-api">
    Запуск рассылок, шаблоны
  </Card>
  <Card title="Статусы сообщений" icon="signal" href="/03-multiapi/02-api/mapi-106-api-statuses">
    Push и pull
  </Card>
  <Card title="Обработка ошибок API" icon="triangle-exclamation" href="/06-reference/01-api/api-errors">
    HTTP-коды и форматы ответов
  </Card>
</Columns>

## Нужна помощь?

- Multi API: support@multiapi.ru