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

Helpdesk API

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

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). Необязательный.

Ответ

{

"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/{id} — детали тикета

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

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

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

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

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

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

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

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

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

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

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

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

ID пользователя-агента

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 — тикет закрыт.

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

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

Клиент жмёт «Связаться с поддержкой» на вашем сайте → вы дёргаете /v1/helpdesk/request и получаете request_id + deeplinks.
Открываете клиенту deeplink (Telegram или Max). Бот покажет название проекта, описание и попросит подписаться.
После согласия подписка создаётся автоматически, сразу открывается меню helpdesk (создание тикета, ticket-types, активные тикеты).
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 в настройках проекта.