Для разработчиков

Contacts

Контакт — клиент, который обращается в поддержку. Через API контакт находится по telegram_id или email. Свои данные (ID в CRM, тариф и т. п.) кладите в extra_data — произвольный JSON-объект, оператор видит его в карточке контакта.

Объект контакта

{
  "id": "44e1...",
  "workspace_id": "1c2b...",
  "channel_id": null,
  "external_id": null,
  "internal_id": null,
  "telegram_id": 123456789,
  "email": "ivan@example.com",
  "full_name": "Иван Петров",
  "username": "ivanp",
  "extra_data": { "plan": "pro", "crm_id": "user-42" },
  "created_at": "2026-04-01T08:00:00",
  "updated_at": "2026-04-06T10:12:33"
}

Другие идентификаторы контакта (VK, WhatsApp) в ответах API не возвращаются; телефон из виджета лежит в extra_data.phone.

GET/api/v1/contacts

Список контактов

Новые сверху.

Query-параметры:

search — подстрока в имени, username, внешнем и внутреннем ID, Telegram ID и VK ID. Email ищется только целиком: адреса хранятся зашифрованными, поиска по части адреса нет
page (по умолчанию 1), page_size (по умолчанию 50, максимум 100)

Ответ: {"items": [...], "total": 42, "page": 1, "page_size": 50}

GET/api/v1/contacts/{contact_id}

Контакт по ID

Возвращает объект контакта. Нет такого — 404 CONTACT_NOT_FOUND.

POST/api/v1/contacts

Найти или создать контакт

Нужен хотя бы один из telegram_id и email, иначе 400. Контакт ищется по telegram_id, затем по email:

Найден — обновляется только full_name (и username, если контакт найден по telegram_id). Email, Telegram ID и extra_data существующего контакта не меняются.
Не найден — создаётся со всеми переданными полями.

В обоих случаях ответ — 201 и объект контакта.

body

{
  "email": "ivan@example.com",
  "telegram_id": 123456789,
  "full_name": "Иван Петров",
  "username": "ivanp",
  "extra_data": { "plan": "pro", "country": "RU", "crm_id": "user-42" }
}

Изменить или удалить контакт через API нельзя. Контакты, созданные через API, не вызывают webhook contact.created: он приходит, только когда виджет впервые идентифицирует посетителя.

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