Helpdesk API
Ticket support system. Create tickets from customers, reply to them and manage statuses. Users are automatically subscribed to notifications when contacting support. Enable Helpdesk in project settings.
POST /v1/helpdesk/tickets — create ticket
Creates a ticket on behalf of a customer. Ticket number is auto-generated.
text string requiredFirst message text
subject string Ticket subject (optional)
channel string Channel: telegram, max or virtual. Defaults to virtual
chat_id number Messenger chat ID. Required for telegram/max
first_name string Customer first name
username string Customer username
ticket_type_id string Ticket type UUID (from GET /v1/helpdesk/ticket-types). Optional.
Response
GET /v1/helpdesk/tickets — list tickets
Returns project tickets. Filter by status: ?status=new|in_progress|waiting|closed.
GET /v1/helpdesk/tickets/{id} — ticket details
Returns full ticket information by ID, including all messages.
POST /v1/helpdesk/tickets/{id}/reply — reply to ticket
Sends an agent reply to the ticket. Customer will receive a notification in messenger.
POST /v1/helpdesk/tickets/{id}/customer-reply — virtual customer reply
Sends a reply on behalf of a virtual customer (channel=virtual). Only for tickets with virtual channel. Agents will be notified and a ticket.replied webhook will be dispatched.
text string requiredFirst message text
PATCH /v1/helpdesk/tickets/{id}/status — change status
Changes ticket status. Allowed values: open, in_progress, closed.
PATCH /v1/helpdesk/tickets/{id}/assign — assign agent
Assigns the ticket to a support agent.
user_id string requiredAgent user ID
PATCH /v1/helpdesk/tickets/{id}/priority — ticket priority
Changes ticket priority. Allowed values: low, normal, high, urgent.
priority string requiredPriority: low, normal, high, urgent
GET /v1/helpdesk/ticket-types — ticket types
Returns list of active ticket types for the project. Each type contains id, name, description. Use ticket_type_id when creating a ticket to classify requests. Types are configured in the dashboard (Settings → Support).
Webhook events
ticket.created — ticket created, ticket.replied — ticket replied, ticket.status_changed — status changed, ticket.assigned — agent assigned, ticket.closed — ticket closed.
POST /v1/helpdesk/request — ticket for non-subscribers
If the user isn't subscribed to the project yet, use this endpoint. The service creates a bot deeplink where the user consents to subscribe and lands directly in the ticket form.
- User clicks «Contact support» on your site → you call /v1/helpdesk/request and get request_id + deeplinks.
- Open the appropriate deeplink for the user (Telegram or Max). The bot shows project name + description and asks to subscribe.
- On consent the subscription is auto-created, helpdesk menu opens right away (create ticket, ticket-types, active tickets).
- Poll GET /v1/helpdesk/request/{request_id}/status until status=accepted — response contains subscriber_id.
Create request
channel string Preferred channel (telegram or max). If omitted, both deeplinks are returned.
ticket_type_id string (UUID) Optional: ticket type id for pre-selection on the ticket creation screen.
Response
Check status
Poll every 1-2s. Statuses: pending (waiting), accepted (subscribed and landed in helpdesk menu), cancelled (user tapped Cancel), expired (15 min TTL).
request_id lives for 15 min. If the user is already subscribed, the bot skips the consent screen and opens helpdesk menu directly. Requires helpdesk_enabled=true and helpdesk_allow_create=true in project settings.