Zapnoty — Helpdesk — тикеты поддержки

Документация API

REST API для уведомлений через Telegram и Max. Подписчики, OTP, рассылки, формы, helpdesk.

Helpdesk API

Система тикетов поддержки. Позволяет создавать тикеты от клиентов, отвечать на них и управлять статусами. При обращении в поддержку пользователь автоматически подписывается на уведомления. Включите Helpdesk в настройках проекта.

Управление тикетами через API

Полный CRUD тикетов доступен по REST API с API-ключом проекта (Bearer zn_live_…) — создание, список с фильтрами, переписка, смена статуса/приоритета, назначение и массовые операции. Те же действия можно выполнять в кабинете и через MCP-сервер для AI-агентов.

POST /v1/helpdesk/tickets — создание тикета

Создаёт тикет от имени клиента. Номер тикета генерируется автоматически.

text string обязательный

Текст первого сообщения

subject string

Тема обращения (необязательно)

channel string

Канал: telegram, max или virtual. По умолчанию virtual

chat_id number

Chat ID в мессенджере. Обязателен для telegram/max

first_name string

Имя клиента

username string

Username клиента

ticket_type_id string

UUID типа обращения (из GET /v1/helpdesk/ticket-types). Необязательный.

POST /v1/helpdesk/tickets
Authorization: Bearer zn_live_...
{
"channel": "virtual",
"text": "Не приходит код подтверждения",
"subject": "Проблема с входом",
"first_name": "Иван",
"username": "ivan_p",
"ticket_type_id": "uuid-or-omit"
}

Ответ

{
"id": "550e8400-...",
"ticket_number": 42,
"status": "new",
"priority": "normal",
"channel": "virtual",
"ticket_type_id": "uuid-or-null",
"ticket_type_name": "Баг",
"created_at": "2026-03-05T12:00:00Z"
}

GET /v1/helpdesk/tickets — список тикетов

Возвращает список тикетов проекта. Фильтрация по статусу: ?status=new|in_progress|waiting|closed.

GET /v1/helpdesk/tickets?status=new&limit=50&offset=0
Authorization: Bearer zn_live_...
// фильтры: status (new|in_progress|waiting|closed),
// assigned_to (UUID), limit (≤100), offset

GET /v1/helpdesk/tickets/{id} — детали тикета

Возвращает полную информацию о тикете по ID, включая все сообщения.

POST /v1/helpdesk/tickets/{id}/reply — ответ на тикет

Отправляет ответ агента на тикет. Клиент получит уведомление в мессенджер.

text string обязательный

Текст первого сообщения

internal bool

true — внутренняя заметка, не видна клиенту и не списывает кредит

POST /v1/helpdesk/tickets/{id}/reply
Authorization: Bearer zn_live_...
{
"text": "Проверьте папку «Спам» и повторите запрос кода",
"internal": false
}

POST /v1/helpdesk/tickets/{id}/customer-reply — ответ виртуального клиента

Отправляет ответ от имени виртуального клиента (channel=virtual). Только для тикетов с каналом virtual. Агенты получат уведомление, а webhook ticket.replied будет отправлен.

text string обязательный

Текст первого сообщения

PATCH /v1/helpdesk/tickets/{id}/status — смена статуса

Изменяет статус тикета. Допустимые значения: new, in_progress, waiting, closed.

status string обязательный

Новый статус: new, in_progress, waiting или closed

PATCH /v1/helpdesk/tickets/{id}/status
Authorization: Bearer zn_live_...
{
"status": "closed" // new | in_progress | waiting | closed
}

PATCH /v1/helpdesk/tickets/{id}/assign — назначить агента

Назначает тикет на агента поддержки.

assigned_to string | null

UUID агента; null или пропуск — снять назначение

PATCH /v1/helpdesk/tickets/{id}/priority — приоритет тикета

Изменяет приоритет тикета. Допустимые значения: low, normal, high, urgent.

priority string обязательный

Приоритет: low, normal, high, urgent

GET /v1/helpdesk/ticket-types — типы обращений

Возвращает список активных типов обращений проекта. Каждый тип содержит id, name, description. Используйте ticket_type_id при создании тикета для классификации обращений. Типы настраиваются в дашборде (Settings → Поддержка).

Webhook-события

ticket.created — создан тикет, ticket.replied — ответ на тикет, ticket.status_changed — смена статуса, ticket.assigned — назначен агент, ticket.closed — тикет закрыт, ticket.csat_received — получена CSAT-оценка, ticket.unanswered_24h — тикет без ответа.

SLA-трекинг (6.4.3)

В ответе тикета — first_reply_at, closed_at и вычисляемые time_to_first_response_seconds, time_to_resolve_seconds. SLA-отчёт по проекту (средние времена, число нарушений, средний CSAT) — в кабинете на вкладке Helpdesk.

Массовые операции (6.4.8)

POST /v1/helpdesk/tickets/bulk — действие над списком тикетов (до 100). Поля: ticket_ids[], action (close / set_status / assign / set_priority / add_tag / remove_tag), value. Ответ: {affected}.

POST /v1/helpdesk/tickets/bulk
Authorization: Bearer zn_live_...
{
"ticket_ids": ["uuid-1", "uuid-2"],
"action": "set_status", // close|set_status|assign|set_priority|add_tag|remove_tag
"value": "closed"
}
// ответ: { "affected": 2 }

CSAT (6.4.5)

При включённом csat_enabled после закрытия тикета клиенту приходит сообщение с кнопками 1-5. Оценка сохраняется в csat_rating, шлётся webhook ticket.csat_received. Включается в кабинете на вкладке Helpdesk.

Автомаршрутизация (6.4.9)

Правила прогоняются при создании тикета, применяется первое подходящее. Условие (channel / subject_contains / text_contains / ticket_type_id) и действие (assign_to / set_priority / add_tag). Настраивается в кабинете.

Webhook ticket.unanswered_24h (6.4.10)

Воркер раз в час ищет тикеты в статусе new/in_progress, где последнее сообщение от клиента старше порога (12/24/48 ч), и шлёт webhook один раз. Порог настраивается в кабинете.

POST /v1/helpdesk/request — тикет для неподписанных

Если пользователь ещё не подписан на проект — используйте этот endpoint. Сервис создаёт deeplink в бот, где пользователь соглашается подписаться и сразу попадает в форму создания тикета.

  1. Клиент жмёт «Связаться с поддержкой» на вашем сайте → вы дёргаете /v1/helpdesk/request и получаете request_id + deeplinks.
  2. Открываете клиенту deeplink (Telegram или Max). Бот покажет название проекта, описание и попросит подписаться.
  3. После согласия подписка создаётся автоматически, сразу открывается меню helpdesk (создание тикета, ticket-types, активные тикеты).
  4. Polling-ом GET /v1/helpdesk/request/{request_id}/status ждёте status=accepted — вместе с ним приходит subscriber_id.

Создание запроса

channel string

Предпочитаемый канал (telegram или max). Если не указан — в ответе оба deeplink'а.

ticket_type_id string (UUID)

Опционально: id типа обращения для pre-selected на экране создания тикета.

POST /v1/helpdesk/request
 
{
"channel": "telegram" // optional
}

Ответ

{
"request_id": "Kq9xV3mN2pT7rL8s",
"telegram_link": "https://t.me/zapnotybot?start=hdreq_Kq9xV3mN2pT7rL8s",
"max_link": "https://max.ru/zapnotybot?start=hdreq_Kq9xV3mN2pT7rL8s",
"expires_in": 900
}

Проверка статуса

Polling каждые 1-2 секунды. Статусы: pending (ждём пользователя), accepted (подписался и открыл меню helpdesk), cancelled (нажал «Отмена»), expired (15 мин TTL).

GET /v1/helpdesk/request/{request_id}/status
 
{
"status": "accepted", // pending | accepted | cancelled | expired
"subscriber_id": "550e8400-...",
"channel": "telegram"
}

request_id живёт 15 минут. Если пользователь уже подписан — бот пропускает экран согласия и сразу открывает меню helpdesk. Требует helpdesk_enabled=true и helpdesk_allow_create=true в настройках проекта.

Конфигурация helpdesk через API

Настройки модуля, SLA, типы обращений, готовые ответы и правила маршрутизации можно менять не только в кабинете, но и через REST API по API-ключу проекта (Bearer zn_live_…). Те же операции доступны AI-агентам через MCP-сервер.

PUT /v1/helpdesk/settings — настройки модуля: включение, приветствие, SLA, CSAT, allow_create/allow_view, порог «без ответа»
GET /v1/helpdesk/sla — отчёт по соблюдению SLA и текущие пороги
GET /v1/helpdesk/ticket-types/config — все типы обращений, включая выключенные (рантайм-список включённых — GET /v1/helpdesk/ticket-types)
POST /v1/helpdesk/ticket-types, PUT/DELETE /v1/helpdesk/ticket-types/{type_id} — CRUD типов обращений
GET/POST /v1/helpdesk/canned-responses, PUT/DELETE /v1/helpdesk/canned-responses/{canned_id} — CRUD готовых ответов
GET/POST /v1/helpdesk/routing-rules, PUT/DELETE /v1/helpdesk/routing-rules/{rule_id} — CRUD правил маршрутизации тикетов

Настройки модуля — PUT /v1/helpdesk/settings

Все поля опциональны — передаются только изменяемые. Поля helpdesk_welcome_message и helpdesk_close_message — объекты вида { ru, en }, а не строки.

helpdesk_enabled bool

Включить/выключить модуль helpdesk

helpdesk_welcome_message object {ru,en}

Приветственное сообщение, мультиязычный объект

helpdesk_close_message object {ru,en}

Сообщение при закрытии тикета, мультиязычный объект

sla_first_reply_hours int | null

SLA на первый ответ в часах, null — выключить

sla_resolve_hours int | null

SLA на решение в часах, null — выключить

helpdesk_ticket_types_enabled bool

Включить выбор типа обращения

helpdesk_allow_create bool

Разрешить подписчикам создавать тикеты

helpdesk_allow_view bool

Разрешить подписчикам просматривать свои тикеты

csat_enabled bool

Включить опрос удовлетворённости (CSAT)

csat_message_template string ≤1024

Текст CSAT-сообщения

helpdesk_unanswered_hours 12 | 24 | 48 | null

Порог алерта «без ответа», null — выключить

PUT /v1/helpdesk/settings
Authorization: Bearer zn_live_...
{
"helpdesk_enabled": true,
"helpdesk_welcome_message": { "ru": "Здравствуйте! Опишите проблему", "en": "Hello! Describe your issue" },
"helpdesk_close_message": { "ru": "Тикет закрыт. Спасибо", "en": "Ticket closed. Thanks" },
"sla_first_reply_hours": 4,
"sla_resolve_hours": 24,
"helpdesk_ticket_types_enabled": true,
"helpdesk_allow_create": true,
"helpdesk_allow_view": true,
"csat_enabled": true,
"csat_message_template": "Оцените поддержку",
"helpdesk_unanswered_hours": 24
}

Тип обращения — POST/PUT /v1/helpdesk/ticket-types

name string обязательный

Название типа обращения

description string

Описание типа

sort_order int

Порядок сортировки в списке

enabled bool

Только для PUT — включён ли тип

POST /v1/helpdesk/ticket-types
Authorization: Bearer zn_live_...
{
"name": "Баг",
"description": "Сообщения об ошибках",
"sort_order": 1
}

Готовый ответ — POST /v1/helpdesk/canned-responses

title string обязательный

Заголовок готового ответа

text string обязательный

Текст ответа

shortcut string

Короткая команда для быстрой вставки

POST /v1/helpdesk/canned-responses
Authorization: Bearer zn_live_...
{
"title": "Приветствие",
"text": "Здравствуйте! Чем можем помочь?",
"shortcut": "/hi"
}

Правило маршрутизации — POST /v1/helpdesk/routing-rules

name string обязательный

Название правила

condition object обязательный

Условие срабатывания, непустой объект

action object обязательный

Действие при срабатывании

order_index int

Приоритет применения правила

POST /v1/helpdesk/routing-rules
Authorization: Bearer zn_live_...
{
"name": "Срочные баги — менеджеру",
"condition": { "ticket_type": "bug" },
"action": { "set_priority": "high" },
"order_index": 1
}

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

Быстрый старт
Первое сообщение за 2 минуты: получение ключа, deep link для подписки, отправка через curl.
Аутентификация
Как авторизовать запросы к API через Authorization: Bearer zn_… ключ проекта.
POST /v1/send — отправка
Отправка персональных уведомлений: текст, HTML/Markdown, медиа, кнопки, шаблоны.