API и вебхуки для интеграций

Отправляйте сообщения из своей CRM, получайте входящие на свой сервер — всё через обычный REST API.

Если вам нужно отправлять сообщения программно — из 1С, amoCRM, Bitrix24, своего сайта или любого другого сервиса — API даёт прямой доступ к функциям chat-valet без ручной работы в личном кабинете. API и вебхуки доступны на всех тарифах, включая пробный.

Что можно сделать через API

Отправить сообщение с конкретного аккаунта — по номеру или в существующий диалог.
Отправить каскадом: сообщение уйдёт в первый по порядку мессенджер, где номер зарегистрирован.
Проверить, есть ли номера в мессенджере, до отправки.
Получить список подключённых аккаунтов с их статусами и остатком дневного лимита.
Читать журнал отправок и переписку.
Принимать входящие сообщения и статусы отправки, доставки и прочтения на свой сервер через вебхуки.

Аутентификация

Ключ создаётся в кабинете, раздел «API». Передавайте его в заголовке `X-Api-Key` или `Authorization: Bearer` — принимаются оба. У ключа есть права: `send` — отправка, `read` — чтение; выдавайте интеграции только то, что ей нужно.

X-Api-Key: cv_xxxxxxxxxxxxxxxxxxxxxxxx

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

POST на `/api/messages/send`. Поле `accountId` — идентификатор аккаунта из `GET /api/accounts`, `to` — номер телефона. Для ответа в существующий диалог передайте `chatId` вместо пары аккаунт-номер: адрес возьмётся из самого диалога, это надёжнее.

curl -X POST https://chat-valet.com/api/messages/send \
  -H "X-Api-Key: cv_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "9f8b1c2d-...",
    "to": "79161234567",
    "text": "Ваш заказ №4521 отправлен. Ожидайте в течение 2 дней."
  }'

В ответ придёт подтверждение движка и остаток дневного лимита: `messageId` — id строки в журнале, `externalId` — id сообщения в мессенджере, по нему же потом приходят статусы доставки и прочтения. Поле `sendAt` с датой в будущем откладывает отправку на это время.

{
  "ok": true,
  "messageId": 48213,
  "externalId": "3EB0C127D7BE9",
  "sentAt": "2026-08-21T10:24:00Z",
  "remainingToday": 42
}

Каскадная отправка

POST на `/api/messages/send-cascade` — главный метод, ради которого API и существует. Вы даёте номер и текст, сервис сам находит, где номер зарегистрирован, и шлёт в первый подходящий канал. Порядок каналов — поле `order`; без него берётся порядок, выбранный в кабинете, а если и он не задан — WhatsApp → Telegram → MAX.

curl -X POST https://chat-valet.com/api/messages/send-cascade \
  -H "X-Api-Key: cv_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "79161234567",
    "text": "Ваш заказ готов к выдаче.",
    "order": ["telegram", "whatsapp", "max"]
  }'

В ответе — каким каналом ушло и честный след по остальным: какие каналы пропущены и почему (номер не зарегистрирован, нет живого аккаунта, кончился дневной лимит).

{
  "ok": true,
  "channel": "whatsapp",
  "externalId": "3EB0C127D7BE9",
  "attempts": [
    { "channel": "telegram", "skipped": "not_registered" },
    { "channel": "whatsapp", "sent": true }
  ]
}

Аккаунты, проверка номеров, журнал

`GET /api/accounts` — подключённые аккаунты: канал, номер, статус, остаток лимита на сегодня.
`POST /api/messages/check-numbers` — есть ли номера в мессенджере: `{ "accountId": "…", "phones": ["7916…"] }`.
`GET /api/messages/log` — журнал всего, что сервис отправил: фильтры по каналу, аккаунту, источнику и статусу; у каждой строки — время отправки, доставки и прочтения.
`GET /api/chats` — диалоги; `POST /api/messages/send` с `chatId` — ответ в диалог.

Вебхуки: входящие и статусы

Добавьте свой https-адрес в кабинете, раздел «API». На каждое событие chat-valet отправит POST с JSON. События два: `message.in` — входящее сообщение, `message.status` — статус исходящего: отправлено, доставлено, прочитано или ошибка.

{
  "event": "message.in",
  "at": "2026-08-21T10:23:00Z",
  "data": {
    "accountId": "9f8b1c2d-...",
    "chatId": "c3d4e5f6-...",
    "chatExternalId": "79161234567@s.whatsapp.net",
    "senderId": "79161234567",
    "text": "Добрый день, хочу узнать о доставке",
    "mediaType": null,
    "at": "2026-08-21T10:22:58Z"
  }
}

Поля `senderId`, `text` и `mediaType` могут быть `null` — например, у вложения без подписи. Второе событие, `message.status`, приходит дважды и больше: сначала результат отправки (`sent` или `failed`), затем квитанции мессенджера — `delivered`, `read` или `failed`:

{
  "event": "message.status",
  "at": "2026-08-21T10:24:05Z",
  "data": {
    "to": "79161234567",
    "channel": "whatsapp",
    "accountId": "9f8b1c2d-...",
    "chatId": "c3d4e5f6-...",
    "externalId": "3EB0C127D7BE9",
    "origin": "api",
    "status": "delivered",
    "at": "2026-08-21T10:24:04Z"
  }
}

Статус двигается только вперёд: `sent` → `delivered` → `read`, `failed` — конечный. У квитанции есть `chatId`, `origin` (откуда сообщение: `api`, `campaign`, `human`, `ai`…) и `error` при ошибке. Событие приходит для всего, что отправил сервис, включая рассылки; для отложенных — после фактической отправки. Сообщения, набранные вручную на телефоне, вебхуком не сопровождаются. Что умеет каждый канал:

Канал	Доставлено	Прочитано	Как считается
WhatsApp	да	да	по каждому сообщению; в группах — по первой квитанции любого участника
Telegram	нет — у личных аккаунтов нет квитанции доставки	да	«прочитано всё до сообщения X» в чате
MAX	нет	да	«прочитано всё до времени T» в чате

Каждый запрос подписан: в заголовке `X-Chatvalet-Signature` — HMAC SHA-256 от тела запроса секретом, который вы получили при добавлении адреса. Подпись — hex от сырого тела запроса, проверяйте её до разбора JSON. Ответьте кодом `200`; при ошибке будет ещё две попытки — через 5 и 30 секунд. Если адрес лежал дольше, пропущенное дочитывается через журнал.

Лимиты и ограничения

Параметр	Значение
Дневной лимит отправки	Лимит вашего тарифа — общий для API, рассылок и кабинета
Максимальный размер текста	10 000 символов
Формат номера	Цифрами с кодом страны: 79161234567
Ключей API	До 10 активных
Адресов вебхуков	До 5, только https

Зарегистрируйтесь и создайте API-ключ в разделе «API» кабинета.

Получить API-ключ

Частые вопросы

Есть ли SDK или библиотеки для популярных языков?

Пока официального SDK нет — API достаточно простой, чтобы работать напрямую через любой HTTP-клиент. Библиотека на Python и Node.js в планах.

Можно ли отправлять файлы и картинки через API?

Да. В поле media передайте объект с типом и адресом публично доступного файла: { "type": "image", "url": "https://…" }. Поддерживаются изображения, видео, аудио, голосовые и документы.

Как узнать, что вебхук не дошёл?

В разделе «API» кабинета у каждого адреса видно, когда он в последний раз отвечал успешно и какая ошибка была последней. Там же есть кнопка «Проверить» — пробное событие в один клик.

Работает ли API в бесплатный тестовый период?

Да. API и вебхуки доступны в полном объёме в течение бесплатного пробного периода 30 дней.

Можно ли использовать несколько API-ключей?

Да, до десяти. У каждого своё имя и права — например, один только для отправки, другой для чтения журнала. Скомпрометированный ключ отзывается в один клик, остальные продолжают работать.

Где полная документация по всем методам?

Полный справочник — все методы со всеми полями, коды ошибок и примеры проверки подписи — встроен в кабинет: раздел «API», вкладка «Документация».