Каналы и интеграции

Канал API

Подключите Entagl к своему приложению или к Make: отправляйте сообщения, получайте ответы и управляйте своим workspace.

Обзор

Канал API позволяет использовать того же AI agent, который отвечает в ваших DM, на сайте, в мобильном приложении или на backend. Вы отправляете сообщение, agent обрабатывает его (с той же буферизацией и многосообщными ответами в человеческом стиле, как в реальных DM), а ответ приходит чуть позже — через webhook callback или polling. Настройте это в Каналы → API: сгенерируйте API key, включите канал, затем выберите callback или polling. Этот же API позволяет вашему разработчику или Make работать с contacts, conversations, bookings, orders и многим другим. Смотрите вкладку Workspace API.

Для разработчиков: справочник API

Каждый endpoint, поле и событие webhook, с примерами кода.

Вкладки на этой странице

API нужен не только для чата. Ваш разработчик или инструмент вроде Make может использовать его, чтобы читать и обновлять большую часть вашего workspace.

Что с ним можно делать

Помимо отправки сообщений, API поддерживает:

Contacts: создавать, обновлять, искать, объединять, добавлять заметки, помечать как do-not-contact
Tags и lifecycle stages: добавлять и удалять теги, переводить contact на другой stage
Conversations: назначать teammate, закрывать с closing note, ставить AI на паузу или возобновлять, добавлять team comments, отправлять сообщение от имени вашего business
Bookings и reminders: проверять свободное время, бронировать, переносить, отменять, создавать и закрывать reminders
Orders и products: создавать и обновлять orders и их items, управлять каталогом
Calls: запускать AI phone call или ставить его в очередь, читать результат
Campaigns: просматривать campaigns и отправлять их

Когда что-то меняется, Entagl может сразу сообщить вашим инструментам через webhooks.

Два способа входа

Make. Когда вы подключаете Make, вы входите в систему под своим аккаунтом Entagl. Затем Make действует от вашего имени с ровно теми же правами: owner или admin могут всё, а team member — только то, что разрешают его права. Если в вашем логине несколько workspace, вы выбираете, какой использовать.

API key. Для своего сервера создайте key в Каналы → API или Настройки → API keys и передавайте его как Authorization: Bearer <your key>. Key принадлежит одному workspace и даёт ему полный доступ owner, поэтому относитесь к нему как к паролю.

Безопасно повторять: заголовок Idempotency-Key

Иногда запрос проходит, но ответ теряется по пути обратно. Если система не уверена, что запрос сработал, она может отправить его снова с тем же заголовком Idempotency-Key. В течение 24 часов Entagl распознаёт key, пропускает выполнение и возвращает первый ответ, так что у вас не появятся два заказа или два contacts. Использование того же key для другого запроса будет отклонено с ошибкой.

Сколько запросов можно отправлять

До 120 запросов в минуту на каждый workspace. Если превысить лимит, Entagl ответит ошибкой 429 (rate_limited). Подождите немного и попробуйте снова. Большинство автоматизаций до этого даже не доходят.

Полная API reference

Все endpoint, поля и коды ошибок перечислены в API reference Entagl. Если у вашего разработчика его ещё нет, напишите на support@entagl.com и попросите API reference.

API key даёт полный доступ owner к своему workspace. Храните его на сервере, никогда не размещайте в веб-сайте или приложении, которое могут открыть клиенты, и отзовите его сразу, как только заподозрите утечку.

Изменения, внесённые через API, в событиях webhook помечаются как сделанные через API, поэтому сценарий Make может игнорировать свои собственные изменения вместо того, чтобы зациклиться.

Функции

Настройка и аутентификация

Создайте API-ключ в Channels → API, включите переключатель канала, затем обращайтесь к API по адресу https://api.entagl.com с заголовком Authorization: Bearer <ваш ключ>. Ключи привязаны к рабочему пространству.

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

POST /api/v1/messages с { message, externalUserId }. Сразу получите 202 и conversationId. Используйте этот conversationId повторно, чтобы продолжить conversation. Ответ agent придёт позже, не в этом ответе.

Webhook (callback) (рекомендуется)

Добавьте публичный HTTPS-адрес callback, и Entagl будет отправлять каждый ответ агента туда методом POST, подписывая заголовком X-Entagl-Signature (HMAC-SHA256). Проверяйте подпись и отвечайте 2xx примерно за 5 секунд. Автоповтора нет.

Опрос (Polling)

Если вы не можете разместить адрес callback, вызывайте GET /api/v1/conversations/:id/messages?since=<cursor>, чтобы получать новые ответы. Передавайте cursor из каждого ответа как ?since=, чтобы получать только новые сообщения.

Безопасность и изоляция

API keys хранятся в виде хэша, а signing secret зашифрован (оба показываются только один раз). Каждый поиск привязан к workspace: conversation ID из другого workspace вернёт 404, и передать user ID нельзя (он выводится из вашего key).

Распространённые задачи

Настройка канала API

Около 3 мин

Перейдите в Channels → API и нажмите Generate API Key. Скопируйте его сразу, потому что он показывается только один раз.
Включите переключатель канала в заголовке карточки API.
Рекомендуется: разверните карточку, вставьте публичный HTTPS-адрес callback, сохраните и скопируйте секрет подписи.
Из своего приложения отправляйте сообщения методом POST на https://api.entagl.com/api/v1/messages и получайте ответы через callback или опрос.

Советы

Ответы приходят асинхронно. POST возвращает 202, а ответ agent приходит через callback или polling, а не в самом ответе.

Одно сообщение может дать несколько ответов после небольшой задержки буферизации (около 8 секунд, настраивается до ~5 минут). Показывайте их все по порядку.

202 не гарантирует ответ. Agent может промолчать, если automation приостановлена, guardrail блокирует сообщение или в workspace закончились credits.

У callback нет автоповтора. Держите опрос как резерв и всегда проверяйте заголовок X-Entagl-Signature, прежде чем доверять доставке.

Повторно используйте conversationId, чтобы продолжить разговор; externalUserId — это просто ваша собственная метка для конечного пользователя.

Пока только текст. Храните API key и signing secret в безопасности: оба показываются только один раз.

Часто задаваемые вопросы

Эта страница была полезной?