Charon держит подключения к WhatsApp, Telegram, WeChat, Matrix и Max и открывает их вашей системе по HTTP. Входящие приходят подписанным вебхуком на ваш адрес, ответы уходят вызовом REST API. Что делать с сообщением дальше, решаете вы.
Два направления, и в каждом Charon отвечает за мессенджер, а ваша система — за то, что происходит в CRM.
Клиент отправляет сообщение на подключённый номер или аккаунт.
Принимает сообщение, сохраняет в историю и подписывает событие.
Получает POST на свой адрес, проверяет подпись, отвечает 2xx.
Заводит контакт или сделку по своим правилам и показывает переписку менеджеру.
Менеджер пишет ответ в привычном для него окне.
Ваша система вызывает POST /api/v1/messages с ключом и текстом.
Отправляет сообщение через нужное подключение и записывает его в историю.
Клиент получает ответ в том же диалоге, где написал.
Вебхук — не единственный путь: историю и статусы можно читать запросами к API по расписанию. Но опрос коротким интервалом даёт задержку и лишние запросы, поэтому для входящих лучше поднять обработчик.
Граница проходит по CRM: до неё работает Charon, внутри неё — ваш разработчик.
2xx.401, 403, 409, 429 и 5xx.С Битрикс24 этой работы нет: там сообщения попадают в Открытые линии без программирования. Внешний API нужен там, где готовой интеграции нет — своя CRM, 1С, сайт, система отчётности. Для amoCRM тот же путь описан на отдельной странице.
Методы, из которых обычно собирается интеграция. Полное описание отдаёт сама установка — про это ниже.
| Задача | Метод |
|---|---|
| Проверить, что ключ работает | GET /api/v1 |
| Получить подключения и их статусы | GET /api/v1/connections |
| Отправить сообщение в мессенджер | POST /api/v1/messages |
| Прочитать историю переписки | GET /api/v1/messages, GET /api/v1/connections/{id}/messages |
| Получать входящие без опроса | POST /api/v1/webhooks |
| Посмотреть, дошло ли событие | GET /api/v1/webhooks/{id}/deliveries |
| Забрать отчёты в свою систему | GET /api/v1/analytics/… |
| Выдать отдельный ключ интеграции | POST /api/v1/api-keys |
Отправка сообщения выглядит так — один запрос с ключом в заголовке:
curl -X POST https://charon.example.com/api/v1/messages \
-H "X-API-Key: ваш_ключ" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"connectionId": "…", "conversationId": "79001234567@c.us", "text": "Здравствуйте! Пишу по вашей заявке."}'
Idempotency-Key защищает от двойной отправки: если
запрос повторится из-за обрыва связи, Charon вернёт результат
первого вызова, а клиент не получит сообщение дважды. Ставьте его на
все запросы, которые нельзя выполнить второй раз.
message.received — пришло входящее, message.sent — ушло исходящее, connection.status — подключение сменило статус.universal — для новой интеграции. Формат bitrix_open_lines нужен только там, где код уже ждёт структуру Открытых линий.X-Signature, метка времени — в X-Signature-Timestamp; подписывается строка «метка времени, точка, тело». Проверяйте по сырому телу, иначе подпись не сойдётся.GET /api/v1/webhooks/{id}/deliveries — по нему разбираются пропавшие сообщения.У ключа ровно те права, которые вы ему дали. Заводите отдельный ключ на каждую внешнюю систему — тогда его можно отозвать, не трогая остальные.
| Право | Что открывает |
|---|---|
messages:read |
Читать сообщения, чаты и контакты |
messages:send |
Отправлять сообщения |
connections:manage |
Читать и настраивать подключения |
media:read |
Скачивать вложения |
analytics:read |
Читать отчёты аналитики |
webhooks:manage |
Заводить адреса вебхуков и смотреть журнал доставок |
api_keys:manage |
Управлять ключами. Давайте только доверенной админ-интеграции |
Ключ создаётся в панели Charon и показывается один раз — сохраните
его сразу в хранилище секретов. Для административных сценариев,
где ваша система входит под учётной записью Charon, подойдёт вход по
токену: Authorization: Bearer.
Порядок, при котором связка проверяется по частям, а не целиком в последний день.
В панели Charon, в разделе API-ключей. Для типовой связки
хватает messages:read, messages:send
и webhooks:manage. Проверьте ключ запросом
GET /api/v1 — так сразу видно, что домен, права и
заголовок в порядке.
Возьмите идентификатор подключения из
GET /api/v1/connections и отправьте себе тестовое
сообщение. Это отделяет проблемы доступа от проблем вашего
кода: если ручной запрос прошёл, дальше дело в интеграции.
Адрес должен быть доступен по HTTPS снаружи и отвечать
2xx после того, как событие принято. Проверку
подписи считайте по сырому телу запроса. Пока подпись не
сходится, не переходите к логике CRM.
Теперь пишется то, ради чего всё затевалось: поиск клиента,
создание сделки, показ переписки менеджеру. Ошибки
401, 403, 409,
429 и 5xx обработайте по отдельности —
они означают разное.
Описание методов отдаёт сама установка Charon:
/api/openapi.yaml и /api/openapi.json на
вашем домене. Это спецификация той версии, которая у вас стоит,
поэтому она не расходится с работающими методами.
Charon держит подключения к WhatsApp, Telegram, WeChat, Matrix и Max и открывает их вашей системе по HTTP. Входящие сообщения он отправляет подписанным вебхуком на ваш адрес, а ответы вы отправляете вызовом REST API. Тем же API читается история переписки, список подключений и их статусы, скачиваются вложения и забираются отчёты. Что делать с сообщением дальше — создавать сделку, контакт или задачу — решает ваша система.
Нужен обработчик по адресу HTTPS, который принимает вебхуки
Charon, проверяет подпись HMAC-SHA256 по сырому телу запроса и
отвечает кодом 2xx. Дальше он вызывает методы вашей
CRM, а обратные сообщения отправляет вызовом
POST /api/v1/messages. Объём работ зависит от того,
какие сущности и сценарии вы используете: связку с воронками,
дедупликацию контактов и правила автосоздания сделок пишет ваш
разработчик.
Charon подписывает тело вебхука HMAC-SHA256 на секрете, который
выдаётся при регистрации адреса. Подпись приходит в заголовке
X-Signature, метка времени — в
X-Signature-Timestamp; подписывается строка из
метки времени, точки и тела запроса. Проверять подпись нужно по
сырому телу, а не по повторно собранному JSON, иначе она не
сойдётся.
Charon повторит доставку — до пяти попыток с нарастающей паузой.
Результат каждой попытки виден в журнале доставок:
GET /api/v1/webhooks/{id}/deliveries. После
пятидесяти неудач подряд адрес отключается, и включить его снова
нужно вручную — так сломанный обработчик не копит бесконечную
очередь.
Описание отдаёт сама установка Charon:
/api/openapi.yaml и /api/openapi.json
на вашем домене. Это спецификация OpenAPI той версии, которая у
вас стоит, поэтому она не расходится с работающими методами.
Ключи создаются в панели в разделе API-ключей; полный ключ
показывается один раз при создании.
Полный доступ к внешнему API входит в платный тариф Charon. Если API и CRM вам не нужны и достаточно встроенного мессенджера, в калькуляторе на главной странице есть режим «Без CRM и API» — он вдвое дешевле. Внешний API работает одинаково и в облаке, и при установке на свой сервер.
Расскажите, какая у вас система, какие сущности заводятся по обращению и сколько каналов нужно. Подскажем, какие методы и события закроют сценарий, и что придётся написать на вашей стороне.
Оставить заявку