У вас есть свой сервис: CRM, личный кабинет, интернет-магазин, биллинг. Там происходят события — закончился тариф, оплатился заказ, освободилось место в группе. API ЭТОЧАТБОТ нужен ровно для одного: чтобы ваша система в этот момент сама написала человеку в бот.

Без API вы бы шли в кабинет и отправляли сообщение руками. С API это делает код — одним HTTP-запросом.

Что этим обычно делают

Напомнить об окончании подписки. Крон в вашей системе раз в сутки находит тех, у кого осталось 3 дня, и отправляет каждому персональное сообщение.
Подтвердить оплату или заказ. Платёж прошёл — человек тут же получает в боте номер заказа и кнопку со ссылкой на статус доставки.
Сообщить об активации. Аккаунт создан, доступ выдан, заявка одобрена — бот пишет об этом первым, человеку не нужно ничего проверять.
Запустить целый сценарий. Не просто одно сообщение, а готовую цепочку из конструктора: с кнопками, ветвлениями, вопросами и ИИ-агентом. Это самое интересное, и об этом дальше отдельная статья.

Есть и обратное направление: получить список людей, писавших боту, и связать их с пользователями вашей базы по вашему же идентификатору.

Главное ограничение — прочитайте его до того, как начнёте

Написать через API можно только тому, кто раньше сам обратился к вашему боту. До первого обращения адреса доставки просто не существует — ни в одном канале. Это правила самих мессенджеров, а не наше решение и не настройка, которую можно включить.

Telegram разрешает боту писать только тем, кто хотя бы раз его запускал. ВКонтакте требует, чтобы человек разрешил сообщения от сообщества. Поэтому сценарий «выгрузим 50 000 клиентов из CRM и разошлём им всем напоминание в Telegram» работать не будет — сообщения уйдут только тем, кто уже общался с ботом.

Практический вывод: сначала приведите людей в бота (кнопка на сайте, ссылка в письме, QR в заказе, виджет чата на сайте), и только потом стройте на API рассылку событий. Обратный порядок — самая частая причина разочарования.

Какие каналы поддержаны

Канал	Поддержка
Чат на сайте	да
Telegram	да
ВКонтакте	да
МАКС	да
Instagram	нет

Instagram не поддержан намеренно. У Meta жёсткие правила на исходящие сообщения: писать первым нельзя, есть окно ответа и отдельные разрешённые поводы. Запихнуть это в общий эндпоинт «отправь текст» без вранья не получается. Если ключ выпущен для Instagram-бота, любой запрос вернёт 400 unsupported_channel. Для Instagram у нас есть отдельное партнёрское API — напишите в поддержку.

Шаг 1. Получите ключ

Ключ выпускается в кабинете: выберите бота → «Для разработчиков» → «Ключи API» → «Выпустить ключ».

Выглядит он так: etchtbt_bot_ и дальше 48 шестнадцатеричных символов.

Про ключ важно знать три вещи:

Он показывается один раз. В базе мы храним только хэш (sha256), восстановить исходный ключ невозможно. Потеряли — отзовите и выпустите новый.
Он привязан к одному боту. Ключ от бота А не открывает бота Б, даже если оба ваши. Это ограничение по замыслу: утёкший ключ не обнуляет весь аккаунт.
Ключей может быть до 5 живых на бота. Удобно, когда у вас разные среды или разные интеграции — отозвать можно каждый по отдельности.

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

Шаг 2. Проверьте ключ запросом GET /{channel}/me

Базовый адрес API — https://etochat.bot/api/v2/{channel}. Авторизация одна на все запросы: заголовок Authorization: Bearer <ключ>.

Самый безобидный запрос — GET /{channel}/me. Он ничего не меняет и показывает, к какому боту привязан ключ.

curl -s https://etochat.bot/api/v2/{channel}/me \
  -H "Authorization: Bearer etchtbt_bot_3f9a1c7d2e5b48a06c1f9d3e7b2a5c80d4f6e1b93a7c2d58"

Ответ:

{
  "bot": {
    "id": 83,
    "name": "Поддержка магазина",
    "channel": "webchat",
    "username": ""
  },
  "can_send": true
}

Смотрите на два поля. channel — убедитесь, что это тот бот, который вы имели в виду. can_send — если там false, значит подписка на боте неактивна и отправка будет отклоняться с ошибкой 402 subscription_inactive. Продлите тариф в кабинете.

Если вместо этого пришла ошибка:

401 unauthorized — заголовок Authorization вообще не долетел. Частая причина — прокси, который вырезает заголовки, или опечатка в названии.
401 invalid_key — ключ неверен, отозван или бот отключён.

Шаг 3. Найдите, кому писать

Чтобы отправить сообщение, нужен chat_id получателя. Взять его можно двумя способами.

Способ первый: список контактов. Эндпоинт GET /{channel}/chats возвращает всех, кто писал боту.

curl -s "https://etochat.bot/api/v2/{channel}/chats?limit=5" \
  -H "Authorization: Bearer etchtbt_bot_3f9a1c7d2e5b48a06c1f9d3e7b2a5c80d4f6e1b93a7c2d58"

{
  "total": 123,
  "limit": 5,
  "offset": 0,
  "contacts": [
    {
      "chat_id": "9995735656",
      "name": "Иван",
      "username": "ivan",
      "status": "open",
      "unread": 0,
      "blocked_bot": false,
      "external_ids": ["user-42"],
      "created_at": "2026-07-14 10:02:11",
      "updated_at": "2026-07-20 18:44:03"
    }
  ]
}

Поддерживаются limit (по умолчанию 50, максимум 100), offset (по умолчанию 0) и query — поиск подстрокой по имени, фамилии и username. Карточку одного человека можно запросить напрямую: GET /{channel}/chats/{chat_id}.

chat_id всегда приходит строкой — и обрабатывать его надо как строку. У чата на сайте идентификатор длиннее 16 цифр, а число такой длины в JavaScript теряет точность: JSON.parse молча испортит последние разряды, и вы будете писать несуществующему человеку. Не приводите chat_id к числу нигде: ни в коде, ни в схеме базы, ни в таблице Excel.

Способ второй: зеркалирование входящих. На странице «Для разработчиков» можно указать до 3 адресов, куда мы будем присылать копии входящих сообщений. В момент, когда человек написал боту, вы получаете уведомление — и в нём chat_id. Это удобнее для живых интеграций: не надо периодически вычитывать список, вы сразу знаете нового собеседника и можете записать его в свою базу.

Шаг 4. Отправьте первое сообщение

curl -s -X POST https://etochat.bot/api/v2/{channel}/messages \
  -H "Authorization: Bearer etchtbt_bot_3f9a1c7d2e5b48a06c1f9d3e7b2a5c80d4f6e1b93a7c2d58" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "9995735656",
    "text": "Ваш заказ <b>№1043</b> оплачен. Курьер приедет завтра с 10 до 14."
  }'

{
  "sent": true,
  "message_id": 16641,
  "chat_id": "9995735656"
}

Поле text обязательно, до 4000 символов, поддерживает HTML-разметку. При желании можно добавить кнопки — но только кнопки-ссылки: пара text и url, адрес обязан быть http или https, максимум 8 штук.

curl -s -X POST https://etochat.bot/api/v2/{channel}/messages \
  -H "Authorization: Bearer etchtbt_bot_3f9a1c7d2e5b48a06c1f9d3e7b2a5c80d4f6e1b93a7c2d58" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "9995735656",
    "text": "Подписка заканчивается через 3 дня.",
    "buttons": [
      {"text": "Продлить", "url": "https://example.com/billing"}
    ]
  }'

Это всё. Три запроса — и ваша система умеет писать людям в бот.

Что дальше: свои идентификаторы вместо chat_id

Хранить чужие chat_id в своей базе неудобно. Проще один раз сказать нам, что человек с chat_id 9995735656 — это ваш пользователь user-42:

curl -s -X POST https://etochat.bot/api/v2/{channel}/contacts/link \
  -H "Authorization: Bearer etchtbt_bot_3f9a1c7d2e5b48a06c1f9d3e7b2a5c80d4f6e1b93a7c2d58" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "9995735656", "external_id": "user-42"}'

После этого в POST /{channel}/messages и POST /{channel}/trigger можно передавать external_id вместо chat_id — и ваш код больше не знает ничего про внутренние идентификаторы мессенджеров. external_id — до 190 символов, регистр сохраняется; повторная привязка того же значения просто перевешивает его на новый chat_id.

Что дальше: запуск сценариев

Самый мощный эндпоинт — POST /{channel}/trigger. Он не отправляет одно сообщение, а запускает для человека сценарий из конструктора: с кнопками, ожиданием ответа, ветвлениями, ИИ-агентом — всем, что вы там собрали. Плюс вы передаёте в сценарий свои переменные:

curl -s -X POST https://etochat.bot/api/v2/{channel}/trigger \
  -H "Authorization: Bearer etchtbt_bot_3f9a1c7d2e5b48a06c1f9d3e7b2a5c80d4f6e1b93a7c2d58" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-42",
    "vars": {"plan": "Премиум", "days_left": "3"}
  }'

В текстах сценария они доступны как {{var.plan}} и {{var.days_left}}. Сценарий должен быть создан в конструкторе с триггером «Из другой автоматизации» и включён — иначе придёт 404 no_flow.

Как выглядят ошибки

Любая ошибка — это JSON одного и того же вида плюс осмысленный HTTP-статус:

{
  "error": {
    "code": "recipient_blocked_bot",
    "message": "Человек остановил бота"
  }
}

Ориентируйтесь на code, а не на текст message — текст может меняться.

Статус	code	Что произошло
401	`unauthorized`	Заголовок `Authorization` не передан
401	`invalid_key`	Ключ неверен, отозван или бот отключён
400	`unsupported_channel`	Канал бота не поддерживается (Instagram)
400	`recipient_required`	Не указан ни `chat_id`, ни `external_id`
400	`text_required` / `text_too_long`	Пустой текст или длиннее 4000 символов
400	`chat_id_invalid`	`chat_id` некорректен
400	`external_id_required` / `external_id_too_long`	Проблема с внешним идентификатором
404	`contact_not_found`	Такого контакта у этого бота нет
404	`external_id_not_linked`	Сначала вызовите `POST /{channel}/contacts/link`
404	`no_flow`	Нет включённого сценария с нужным триггером
402	`subscription_inactive`	Подписка неактивна, отправка невозможна
409	`recipient_blocked_bot`	Человек остановил бота
502	`send_failed`	Мессенджер не принял сообщение

Два статуса стоит обработать в коде осознанно. 409 recipient_blocked_bot — это не сбой, а нормальный конец жизни контакта: пометьте его у себя и перестаньте пытаться. 502 send_failed — временная проблема на стороне мессенджера, здесь уместен повтор с задержкой.

Остальные статьи раздела

Выпуск, хранение и отзыв ключей API
Работа с контактами: поиск, пагинация, карточка человека
Привязка своих идентификаторов пользователей (external_id)
Отправка сообщений: HTML-разметка, кнопки-ссылки, лимиты
Запуск сценариев через POST /{channel}/trigger и передача переменных
Зеркалирование входящих сообщений на ваш адрес
Справочник ошибок и рекомендации по повторам
Готовые рецепты: напоминание об окончании тарифа, подтверждение заказа, приветствие после регистрации

API ЭТОЧАТБОТ: с чего начать