Перейти к содержимому
Разработчикам

Справочник Entagl API

Справочник API
v1
Endpoint: 98
Событий webhook: 58

Entagl API позволяет вашему программному обеспечению работать с workspace Entagl: контактами, диалогами, сообщениями, записями, напоминаниями, заказами, товарами, звонками ИИ и кампаниями. Webhooks сообщают вашим системам сразу, как что-то происходит. Это тот же API, который использует приложение Entagl для Make.

Базовый URL

HTTPS
https://api.entagl.com/api/v1

Запросы и ответы передаются в формате JSON по HTTPS. Названия полей записываются в формате snake_case. ID являются целыми числами, если endpoint не указывает иное. Время передаётся строками ISO 8601; в ответах используется UTC.

Аутентификация

Отправляйте токен с каждым запросом в заголовке Authorization: Authorization: Bearer <token>. Работают два вида токенов:

API-ключ

Для вашего собственного серверного кода. Создайте ключ в приложении Entagl в разделе Настройки → API Ключи. Ключи начинаются с ai_. Ключ работает в том workspace, где он создан, и даёт там права владельца, поэтому храните его в тайне и никогда не помещайте в браузер или мобильное приложение.

Открыть API Ключи

Токен доступа OAuth 2.0

Используется коннекторами, например приложением Entagl для Make. Человек входит в свой аккаунт Entagl, и коннектор действует от его имени с его ролью в workspace. Чтобы создать собственную интеграцию OAuth, напишите на support@entagl.com.

Запрос
curl "https://api.entagl.com/api/v1/contacts?limit=2" \
  -H "Authorization: Bearer ai_your_api_key"

Если заголовка нет, ответ будет 401 unauthenticated. Неверный или отозванный ключ даёт 401 invalid_api_key. Просроченный токен OAuth даёт 401 invalid_token: обновите его и повторите запрос.

Workspaces и разрешения

Каждый запрос работает ровно с одним workspace. API-ключ всегда использует свой workspace. Вход через OAuth может относиться к нескольким workspace (вашим или тем, куда вы вошли как участник команды): чтобы выбрать нужный, отправьте заголовок X-Entagl-Workspace с ID workspace. Если workspace один, заголовок необязателен. GET /me работает без заголовка и перечисляет все workspace, доступные этому логину.

Запрос
curl "https://api.entagl.com/api/v1/me" \
  -H "Authorization: Bearer <oauth_access_token>"

curl "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer <oauth_access_token>" \
  -H "X-Entagl-Workspace: <workspace_id from /me>"

Без заголовка при входе с несколькими workspace вы получите 400 workspace_required; workspace, к которому у логина нет доступа, даёт 403 workspace_forbidden. ID, принадлежащий другому workspace, всегда даёт 404 not_found, а не 403.

Для каждого endpoint ниже указано нужное разрешение. Владельцы, admins и API-ключи проходят все проверки. Участники команды проходят, если у их роли отмечено это разрешение в настройках команды: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns или integrations. Без него API отвечает 403 insufficient_permissions.

Запросы и ошибки

Отправляйте тела запросов в формате JSON с Content-Type: application/json. Большинство endpoint отклоняют неизвестные поля тела с 422, так что опечатка не пройдёт незамеченной. Все ошибки имеют одинаковую структуру: постоянный code, по которому можно ветвить логику, понятное message и, для ошибок валидации, список details, указывающий на каждое неверное поле.

422
{
  "error": {
    "code": "validation_failed",
    "message": "Invalid email address",
    "details": [
      { "path": "email", "message": "Invalid email address" }
    ]
  }
}
  • 400Некорректный запрос: неверный ID, неверный cursor, нет заголовка workspace.
  • 401Токен отсутствует, недействителен или просрочен.
  • 402Недостаточно кредитов для действия (например, при отправке кампании).
  • 403Вход выполнен, но доступ запрещён: нет разрешения или доступа к workspace.
  • 404Не найдено, в том числе для ID из другого workspace.
  • 409Конфликт: дублирующееся имя, неверное состояние или конфликт Idempotency-Key.
  • 422Проверка не пройдена, или бизнес-правило отклонило изменение.
  • 429Достигнут лимит запросов. См. Retry-After.
  • 500 / 502Сбой в Entagl или в канале сообщений. Проверьте результат, прежде чем повторять запись.

Маршруты с отметкой Старый формат ответа появились раньше этих правил: они возвращают обычные JSON-объекты или массивы и на большинство ошибок отвечают как { "message": "…" }.

Постраничная выдача

Endpoints с отметкой Постраничный возвращают сначала самые новые элементы, внутри объекта-списка. Запрашивайте до 100 элементов через limit (по умолчанию 25). Если has_more равно true, передайте next_cursor как starting_after, чтобы получить следующую страницу. Другие списки возвращают всё сразу, с has_more: false.

Ответ
{
  "object": "list",
  "data": [
    {
      "object": "contact",
      "id": 6789,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "tags": ["vip"]
    }
  ],
  "has_more": true,
  "next_cursor": "6789"
}
Следующая страница
curl "https://api.entagl.com/api/v1/contacts?limit=100&starting_after=6789" \
  -H "Authorization: Bearer ai_your_api_key"

Идемпотентность

Каждый POST endpoint в стандартном формате принимает заголовок Idempotency-Key (до 200 символов). Используйте уникальное значение для каждой операции, например UUID. Entagl хранит первый ответ 24 часа: повтор с тем же ключом и тем же телом возвращает этот ответ с Idempotent-Replayed: true, и ничего не выполняется дважды. Маршруты с пометкой Старый формат ответа работают иначе, см. ниже.

Запрос
curl -X POST "https://api.entagl.com/api/v1/contacts" \
  -H "Authorization: Bearer ai_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c1d2e-order-7781" \
  -d '{ "first_name": "Jane", "phone": "+15551234567", "tags": ["vip"] }'
  • Тот же ключ с другим телом даёт 409 idempotency_key_reused.
  • Пока первый запрос ещё выполняется или если он так и не завершился, повтор даёт 409 request_in_progress. Проверьте результат, затем повторите с новым ключом.
  • Сохраняется любой результат, включая ошибки. Чтобы повторить неудавшийся запрос, используйте новый ключ.
  • Ключи привязаны к workspace и к учётным данным.

Старые маршруты. POST /messages тоже принимает Idempotency-Key (или message_id в теле): повтор уже принятого сообщения отвечает 202 с тем же conversationId и не обрабатывается дважды, а тот же ключ с другим телом отвечает 409. У POST /chat нет защиты от повторов: повтор снова запускает ИИ, поэтому проверьте результат, прежде чем повторять запрос.

Лимиты запросов

Каждый workspace может делать 120 запросов в минуту, этот лимит общий для всех его API-ключей и подключений. В ответах есть RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset (секунды до сброса окна). При превышении лимита вы получите 429 rate_limited с заголовком Retry-After: подождите столько секунд и повторите запрос. Старые маршруты API-канала в этот лимит не входят.