1-чат

Документация

API для внешних агентов

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

Лимит новых чатов на подключение за 24 часа

По умолчанию — 10; тариф и исключение для рабочего пространства могут менять предел. Текущий лимит возвращается в outreach подключений. Считается создание нового для 1-чат диалога через /conversations/start, даже без отправки сообщения. Предел считается по каждому подключённому аккаунту отдельно и скользящим окном в 24 часа, а не по календарным суткам. Он общий с людьми: то, что оператор начал вручную, тоже входит в счёт. При превышении приходит 429 с кодом new_contacts_daily_limit и временем, через которое освободится место. Предел защищает аккаунт от блокировки мессенджером — обходить его, заводя второй ключ, бессмысленно: счёт ведётся по аккаунту.

Секрет показывается один раз

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

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

Ответ приходит только после того, как мессенджер подтвердил приём, и на медленных каналах это занимает до полутора минут. Закладывайте это в таймауты клиента.

Повторяйте отправку только с тем же client_id

Передавайте client_id — свой UUID на каждое новое сообщение. Повтор с тем же client_id в том же диалоге не отправит второй раз, а вернёт уже созданное сообщение, так что ретрай после таймаута безопасен. Без client_id повтор отправит сообщение второй раз.

Вместо опроса — ожидание изменений

WebSocket ключам закрыт, но опрашивать список диалогов не нужно: GET /v1/changes принимает курсор и держит запрос до 30 секунд, возвращаясь в тот момент, когда событие действительно появилось. Один ждущий запрос заменяет десяток пустых проверок. Первый вызов — since=0 и wait=0, чтобы узнать текущий курсор; дальше передавайте cursor из ответа. Ответ status=gap означает, что курсор устарел и состояние надо перечитать целиком.

Из аккаунта, которому нужен вход, писать нельзя

Если сессию закрыли или мессенджер её завершил, чаты аккаунта остаются и читаются, но отправка, реакции, поиск собеседника и импорт отвечают 409 с кодом integration_needs_login и состоянием аккаунта. Так же, с кодом integration_not_running, отвечает аккаунт, который сейчас не удаётся подключить. Смотрите заранее state.can_send у аккаунта в list_accounts: он учитывает и то и другое. can_send у диалога говорит только о том, нужен ли аккаунту вход. Войти снова может только владелец пространства в интерфейсе.

Что API умеет

  • Читать список диалогов по всем подключённым мессенджерам сразу
  • Ждать новых сообщений, не опрашивая API вхолостую
  • Получать вебхук на свой адрес, когда держать соединение негде
  • Читать историю переписки и участников диалога
  • Скачивать вложения
  • Находить собеседника по телефону или имени пользователя
  • Начинать диалог с тем, с кем ещё не переписывались
  • Отправлять сообщения с текстом и файлами
  • Отмечать диалог прочитанным
  • Ставить и снимать реакции

Чего API не умеет

Это ограничения по замыслу, а не пробелы.

Подключать и отключать каналы
Каналы подключает человек через интерфейс — это решение, а не пробел
Работать с биллингом, оплатой и тарифами
Закрыто полностью
Входить, регистрироваться, управлять аккаунтом
Закрыто полностью
Создавать и отзывать API-ключи
Ключ не управляет ключами, в том числе собой
Подключаться к WebSocket
Поток реального времени доступен только интерфейсу; агент ждёт изменений через /v1/changes или получает вебхук
Видеть групповые чаты и каналы
Агенту доступна только личная переписка

Список разрешённого, а не запрещённого: существующий метод, которого здесь нет, отвечает 403 — в том числе метод, который появится в будущем. Несуществующий путь отвечает 404, так что опечатку в адресе легко отличить от нехватки прав.

Ключи

Два уровня доступа.

Чтение

sk_1chat_ro_…

Видит переписку, ничего не меняет

Запись

sk_1chat_rw_…

Видит переписку и может отправлять сообщения от имени владельца ключа

Ключи создаются в интерфейсе, на странице «API-ключи». До 20 активных ключей на воркспейс. Срока годности у ключа нет — он работает, пока его не отозвали.

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

Авторизация

HTTP-заголовок
Authorization: Bearer sk_1chat_rw_…

Базовый адрес: https://app.1-chat.ru/api

Методы

Все пути даны от базового адреса.

Чтение — доступно обоим ключам

GET/v1/attachments/{attachment_id}/raw
GET/v1/changes
GET/v1/conversations
GET/v1/conversations/{conversation_id}
GET/v1/conversations/{conversation_id}/assignment-events
GET/v1/conversations/{conversation_id}/messages
GET/v1/conversations/{conversation_id}/participants
GET/v1/integrations
GET/v1/team/handoff-categories
GET/v1/team/members
GET/v1/webhook-endpoints

Запись — только ключом на запись

POST/v1/conversations/recipients/search
POST/v1/conversations/start
DELETE/v1/conversations/{conversation_id}/assignment
POST/v1/conversations/{conversation_id}/assignment
DELETE/v1/conversations/{conversation_id}/help-call
PATCH/v1/conversations/{conversation_id}/help-call
POST/v1/conversations/{conversation_id}/help-call
POST/v1/conversations/{conversation_id}/help-call/accept
DELETE/v1/conversations/{conversation_id}/help-call/escalate
POST/v1/conversations/{conversation_id}/help-call/escalate
POST/v1/conversations/{conversation_id}/messages
POST/v1/conversations/{conversation_id}/messages/{message_id}/reactions
DELETE/v1/conversations/{conversation_id}/messages/{message_id}/reactions/{emoji}
POST/v1/conversations/{conversation_id}/read
POST/v1/conversations/{conversation_id}/typing
POST/v1/uploads
POST/v1/webhook-endpoints

Страницы и пагинация

Список диалогов

По умолчанию 50, максимум 200 за запрос. Листается смещением.

История переписки

По умолчанию 50, максимум 200 за запрос. Пагинация курсорная: она не теряет и не дублирует сообщения, даже если во время листания приходят новые.

Мессенджеры

Значения параметра channel.

whatsappWhatsApp
telegramTelegram (бот) — Подключение через бота. Сообщения уходят от имени бота.
telegram_clientTelegram (личный аккаунт) — Подключение личного аккаунта. Сообщения уходят от имени человека.
maxMAX

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

queuedПринято к отправке
sentМессенджер принял сообщение
failedОтправить не удалось

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

Два свойства отправки, которые ломают наивного клиента, — повторяем их здесь, рядом с методом, а не только во вступлении.

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

Ответ приходит только после того, как мессенджер подтвердил приём, и на медленных каналах это занимает до полутора минут. Закладывайте это в таймауты клиента.

Частота запросов

300 запросов в минуту с одного IP-адреса — несколько агентов за одним адресом делят лимит между собой.

Окно фиксированное, а не скользящее: счётчик обнуляется на границе календарной минуты. Поэтому пауза до следующей попытки — это остаток текущей минуты, и она то короткая, то почти целая минута. Точное значение приходит в поле retry_after_seconds и заголовке Retry-After.

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

Предел общий с людьми: диалоги, начатые оператором вручную, тоже входят в счёт. При превышении приходит 429 с кодом new_contacts_daily_limit. Считается по аккаунту, поэтому второй ключ предела не обходит.

Особенности

Агенту без постоянного процесса — вебхук

Ожидание через /v1/changes подходит процессу, который живёт всегда. Агенту, который просыпается и завершается, ждать негде — для него зарегистрируйте вебхук в интерфейсе, и мы постучимся сами. Каждая доставка подписана: заголовок X-1chat-Signature содержит HMAC-SHA256 от метки времени и тела через точку, ключ выдаётся при создании. Доставка не реже одного раза, поэтому дедуплицируйте по seq события.

Новому собеседнику пишут в два шага

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

Файл отправляется в два шага

Сначала POST /v1/uploads — multipart с полем file, а также conversation_id и, если нужно, kind (file, image, video, audio, voice; без него — по MIME-типу, PDF уходит документом). В ответ придёт id. Затем отправьте сообщение с этим id в attachment_ids; text тогда — подпись, его можно не передавать. Файл — до 50 МБ, каждый id уходит один раз. В MCP то же самое делают upload_file (по ссылке или base64) и send_message.

Диалог принадлежит аккаунту, а не типу мессенджера

integration_account_id — это конкретное подключение, channel — его тип. Считать их одним и тем же нельзя, даже если сейчас на каждый мессенджер приходится одно подключение.

Счётчик непрочитанных общий на диалог

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

Статусы «доставлено» и «прочитано» не приходят

Узнать, прочитал ли собеседник сообщение, нельзя — этого не отдают сами мессенджеры.

Вложения скачиваются через API

Прямых ссылок в хранилище нет: запрос за содержимым вложения требует того же заголовка авторизации.

Ошибки

401
Ключ не существует, отозван или перевыпущен
invalid_api_key
403
Метод недоступен ключам
api_key_scope_forbidden
403
Ключом на чтение вызван метод записи
api_key_read_only
403
Диалог в мессенджере, закрытом для ключей
api_key_channel_forbidden
404
Объект не найден или принадлежит другому воркспейсу
409
Аккаунту нужен вход: писать из него нельзя, пока владелец не войдёт снова
integration_needs_login
409
Аккаунт сейчас не работает: писать из него нельзя
integration_not_running
422
Некорректное тело запроса
429
Превышена частота запросов
global_rate_limited
429
Исчерпан дневной предел новых собеседников для этого аккаунта
new_contacts_daily_limit

Ответ с ошибкой содержит поле detail с машиночитаемым кодом.

Безопасность

Если ключ утёк — перевыпустите его на странице «API-ключи».

Секрет не хранится
В базе лежит только хеш ключа. Утечка дампа базы не даёт рабочих ключей, но и восстановить потерянный ключ нельзя.
Отзыв и перевыпуск действуют немедленно
Старый секрет перестаёт работать сразу: агенты, которые им пользуются, получат 401 со следующего запроса. Ждать истечения чего-либо не нужно.
Видно, когда ключом пользовались в последний раз
У каждого ключа отображается дата последнего обращения — по ней видно, работает ли выданный ключ и не пользуется ли им кто-то, кто не должен.
Отдельный ключ на каждого агента
Так скомпрометированный ключ отзывается по одному, не задев остальных, и по дате последнего использования видно, чей именно перестал работать.
Ключ на запись пишет вашим клиентам от вашего имени
Обращайтесь с ним как с паролем: держите в переменных окружения или менеджере секретов, не кладите в репозиторий, не пересылайте в переписке. Если задача только читать — выдавайте ключ на чтение.
Ключ работает в пределах одного воркспейса
Того, где он создан. Чужие диалоги по нему недоступны.
Создать API-ключСтраница «API-ключи» в приложенииОстальные разделыВернуться в базу знаний

Описание собрано автоматически из работающего кода API, редакция 677c44fa1f87f048.

Попробуйте 7 дней бесплатно

Подключите мессенджеры и соберите переписку с клиентами в одном окне. Без карты — просто войдите.

Попробовать бесплатноСмотреть цены

Есть вопросы? Напишите нам в Telegram →