Публичный API и вебхуки

REST API даёт вашей CRM, бэкенду сайта или собственному боту работать с лидами и диалогами meni.ge так же, как это делает панель: читать карточки, менять свойства, отправлять события, отвечать в диалогах. Вебхуки, наоборот, сами сообщают вашему серверу о новых лидах, событиях и сообщениях.

Что нужно для запуска#

Шаг 1. Ключ и права#

1. Откройте Интеграции и нажмите API и вебхуки в шапке страницы.
2. На вкладке Ключи нажмите Создать ключ, введите название («CRM», «Бэкенд сайта», «Telegram-бот»).
3. Выберите набор прав или отметьте права по одному, при нескольких точках — к каким точкам ключ допущен, и срок.
4. Скопируйте секрет cnk_…. Он показывается один раз: у нас хранится только его отпечаток (SHA-256).

Наборы: CRM / бэкенд (лиды, свойства, события, чтение диалогов и сегментов), Свой бот (читает лидов, отвечает в диалогах, пишет лидам), Только чтение, Всё.

• Права меняют права и точки ключа на лету — интеграция продолжает работать.
• Перевыпустить выдаёт новый секрет; старый перестаёт работать сразу, права и журнал остаются.
• Отозвать — сразу и навсегда, следующий запрос получит 401.

Ключ передаётся заголовком Authorization: Bearer cnk_… (или X-Api-Key: cnk_…). Храните его только на сервере — не в браузере и не в мобильном приложении.

Шаг 2. Первые запросы#

KEY=cnk_ваш_ключ
API=https://api.meni.ge/public-api/v1

# что умеет ключ: права, точки, лимит
curl -H "Authorization: Bearer $KEY" "$API/me"

# лиды, свежие сверху (20 на страницу)
curl -H "Authorization: Bearer $KEY" "$API/contacts?limit=20"

# поиск по имени, почте или телефону
curl -H "Authorization: Bearer $KEY" "$API/contacts?q=anna"

Ответ — всегда конверт:

{
  "meta": { "status": 200, "requestId": "…", "nextCursor": "WyIyMDI2LTEwLTA0…" },
  "data": { "total": 128, "contacts": [ { "id": "…", "status": "lead", "name": "Анна", "updatedAt": "2026-10-04T09:12:00Z" } ] }
}

Следующая страница — тот же запрос с cursor=<meta.nextCursor>; нет nextCursor — страниц больше нет. Ошибка — {"meta": {...}, "error": {"code": "…"}}.

Точка. Если ключу доступна одна точка, её указывать не нужно. Если несколько — добавьте location=<id точки> (список — GET /v1/locations), иначе ответ 400 location_required.

Свойства и события по вашему user_id. Не обязательно хранить наш id лида: добавьте ?by=user_id, и адресом станет ваш идентификатор пользователя. Лида с таким user_id ещё нет — мы его заведём.

# свойства: операции update_or_create, set_once, add, delete, append, union, exclude
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ops":[{"op":"update_or_create","key":"$email","value":"anna@example.com"},
              {"op":"add","key":"orders","value":1},
              {"op":"union","key":"interests","value":"yoga"}]}' \
  "$API/contacts/u-1001/props?by=user_id"

# события пачкой (до 100), повтор с тем же id засчитывается один раз
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"events":[{"id":"ord-5531","userId":"u-1001","name":"order_paid","props":{"sum":45,"currency":"GEL"}}]}' \
  "$API/events"

# ответ в диалоге и смена статуса
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text":"Здравствуйте! Заказ передан курьеру."}' "$API/conversations/<id>/reply"
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"resolved"}' "$API/conversations/<id>/status"

Запись идёт через ту же очередь, что правки из панели: изменения применяются за секунды, а ответ на запись по user_id — 202 с pending. В карточке лида автор правки виден как «API: <название ключа>».

Методы#

Поля, примеры и коды ошибок каждого метода — в справочнике.

Шаг 3. Вебхуки#

Вебхуки настраиваются у точки: Чат → Настройки → Вебхуки — адрес https, события и секрет подписи. К событиям диалога (новый диалог, новое сообщение, статус, оценка, метки) добавились события лида:

{
  "event": "lead.event_tracked",
  "deliveryId": "WD…",
  "at": "2026-10-04T09:12:03Z",
  "webhookId": "…",
  "locationId": "…",
  "contact": { "id": "…", "status": "user", "userId": "u-1001", "props": { "orders": 3 }, "tags": ["vip"] },
  "leadEvent": { "name": "order_paid", "at": "2026-10-04T09:12:00Z", "props": { "sum": 45 } }
}

Имя, почта и телефон лида попадают в тело, только если у вебхука включена галка «Передавать контакты гостя». Проверка подписи — HMAC-SHA256 тела секретом вебхука:

# заголовок X-Meni-Signature: sha256=<hex>
echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET"

Ответьте 2xx за 5 секунд — иначе доставка повторится; после длинной серии неудач вебхук отключается, и это видно в настройках. Дубли отсекайте по deliveryId.

Ограничения#

• 60 запросов в минуту на ключ; сверх — 429 с заголовком Retry-After. Остаток — в X-RateLimit-*.
• До 200 записей на страницу (по умолчанию 50), до 100 событий в пачке, до 250 операций со свойствами за запрос, до 30 тегов за раз.
• До 20 живых ключей на аккаунт.
• Журнал вызовов ключа хранится 30 дней: время, метод, шаблон пути (без id и тела), код ответа, длительность.
• События, отправленные через API, ложатся в карточку лида (лента, сводка, сегменты), но не в сырой журнал аналитики посещений.
• Написать лиду можно только в существующий диалог: нет диалога — ответ 409 no_conversation.

Устранение неполадок#

Каждый запрос виден на вкладке Журнал вызовов — с кодом ответа и названием ключа.

Частые вопросы#

Можно ли вызывать API из браузера? Нет: ключ даёт доступ ко всем лидам точки. Вызывайте API со своего сервера.

Чем user_id отличается от id лида? id лида — наш идентификатор карточки. user_id — ваш идентификатор пользователя (номер в CRM, id аккаунта на сайте); с ?by=user_id карточку можно адресовать им.

Что будет при повторной отправке события? Событие с тем же id засчитывается один раз — можно смело повторять запрос при сетевой ошибке.

Нужен ли отдельный ключ на каждую точку? Нет: один ключ может работать с несколькими точками, точка выбирается параметром location.

Связанные разделы#

• Чат с гостями — диалоги, лиды и настройки вебхуков
• Заявки — единый входящий поток
• API и MCP своей АТС — отдельный API телефонии
• Интеграции