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

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

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

Что можно сделать через 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 дней."
  }'

В ответ придёт подтверждение движка и остаток дневного лимита. Поле `sendAt` с датой в будущем откладывает отправку на это время.

{
  "ok": true,
  "externalId": "3EB0C127D7BE9",
  "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-...",
    "text": "Добрый день, хочу узнать о доставке",
    "senderId": "79161234567"
  }
}

Каждый запрос подписан: в заголовке `X-Chatvalet-Signature` — HMAC SHA-256 от тела запроса секретом, который вы получили при добавлении адреса. Ответьте кодом `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-ключей?

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