Быстрый старт

Задача: получать сообщения из Amobit Chats в своей системе и отвечать в тот же диалог. Ниже — минимальный путь от кабинета до первого подписанного события и первого ответа через API. Настройку выполняет владелец или администратор компании.

Шаги

1. Подключите канал

   Кабинет → Профиль → Каналы. Добавьте канал, авторизуйте его и проверьте обмен: напишите с клиентского аккаунта и ответьте из Amobit. Пока канал не подключён, отправка через API вернёт 409.

2. Создайте интеграцию

   Кабинет → Профиль → Интеграции → API / Webhook. Укажите название, публичный HTTPS-адрес вашего эндпоинта и секрет подписи длиной не менее 16 символов. Секрет хранится на стороне Amobit и больше не показывается — сохраните его в хранилище секретов.

3. Включите доставку событий

   Отметьте чекбокс «Включить отправку событий message.created» и сохраните интеграцию. Включить её без webhook-URL и секрета нельзя — API вернёт 400, событие message.created единственное.

4. Выпустите токен

   Нажмите «Создать входящий токен». Токен вида amc_… показывается один раз и действует ограниченный срок — по умолчанию 365 дней; сохраните его в секреты вашей системы. Кнопка «Заменить входящий токен» отзывает предыдущий немедленно и возвращает новый expires_at.

5. Получите первое событие

   Отправьте сообщение с клиентского аккаунта. Amobit поставит событие в очередь и выполнит POST на ваш адрес. Проверьте заголовки X-Amobit-Chats-Signature, X-Amobit-Chats-Timestamp и X-Amobit-Chats-Idempotency-Key и подтвердите подпись кодом из раздела Webhooks. Ответьте 2xx в течение 10 секунд.

6. Ответьте через API

   Возьмите thread.id из payload события и отправьте текст обратно:

   curl -X POST https://chats.amobit.io/api/v1/external-integrations/inbound/messages/ \
     -H "Authorization: Bearer amc_ВАШ_ТОКЕН" \
     -H "Content-Type: application/json" \
     -d '{
       "thread_id": "9fd48a99-f5f3-4c3d-8ca1-1f0e047d5b25",
       "text": "Здравствуйте! Отвечаем из CRM.",
       "idempotency_key": "crm-outbox-1001"
     }'

   Успешная отправка — 201 с объектом сообщения. Повтор того же запроса с тем же ключом вернёт 200 и существующее сообщение, не создавая дубль.

7. Проверьте доставку

   Ваш сервер должен ответить 2xx. Состояние последних доставок возвращает GET /api/v1/external-integrations/workspaces/{workspace_slug}/deliveries/ — только с сессией Amobit ID владельца/администратора (последние 100 записей, без payload). В карточке интеграции журнал доставок пока не отображается; для диагностики используйте этот эндпоинт или поддержку.

Чек-лист перед продакшеном

• Webhook-URL — публичный HTTPS, без редиректов, отвечает 2xx быстрее 10 секунд.
• Подпись проверяется на сыром теле запроса, сравнение — за постоянное время.
• Повторные события отбрасываются по X-Amobit-Chats-Idempotency-Key.
• Слишком старые X-Amobit-Chats-Timestamp отклоняются (рекомендуем окно 5 минут).
• Токен и секрет лежат в секрет-хранилище и не попадают в Git, логи и переписку.
• Каждый исходящий вызов передаёт стабильный idempotency_key (ID записи в вашей очереди).
• На 202 и 502 повторяется тот же запрос с тем же ключом, а не создаётся новый.

Если что-то не работает

Дальше: справочник HTTP API · контракт webhooks · MCP для AI-клиентов.