Skip to main content
YoLead uses chat for the client-channel relationship and ticket for each separate request inside that chat.

Chat vs ticket

One chat can have multiple tickets over time. For example, the same client can contact the company today, close the dialog, and contact the company again later. That later request may reopen the previous ticket or create a new ticket, depending on the channel restore period. For email, a chat is scoped to the connected company mailbox and the client’s normalized email address. A single valid Reply-To address identifies the client when present; otherwise YoLead uses the From address. The email subject does not create a separate chat. See Email channel for subject and content behavior.

Ticket attribution

A ticket can include optional acquisition attribution captured when it is created. Telegram Bot, MAX, VK, Instagram, Messenger, and WhatsApp can supply attribution. It appears in Public API ticket history and webhook Ticket objects. Later messages and reopening within the restore period preserve the original attribution. See Ticket attribution for keys and lifecycle rules.

Ticket statuses

Human and AI employees

Employees returned by GET /v1/employees include kind: "human" or kind: "ai". Both kinds can be ticket assignees. The Employee object in ticket.assignee_changed webhooks also includes kind. When an active AI operator handles a channel, a new incoming ticket can be taken into work automatically. In that case, the ticket.created webhook can already contain status: "active" and the AI employee’s assigneeId. AI actions can also close a ticket or hand it over to a human employee through the existing status and assignee events. In the YoLead UI, an AI agent can be configured to hand off to a specific employee or to the assignment queue. Existing agents keep their direct employee route unless their settings change. An optional client notification is generated and sent before a handoff when the client requests a person or the AI cannot answer. Technical errors, unsupported attachments, and inactivity handoffs do not send this notification. Retries resume the saved handoff without automatically resending the notice.

Chat status

A chat also has a status. It stays in sync with the status of chat.lastTicket.

Allowed status transitions

Direct new to inactive transitions are not allowed. A new request must be taken into work before it can be closed. Moving a chat back to new is not allowed. To transfer an active ticket to another employee, use PATCH /v1/tickets/{ticketId}/assignee. The same endpoint accepts newAssigneeId: null to move an active ticket to pending_assignment. Set newAssigneeId to an active human employee with channel access to take a queued ticket into work. Both actions keep the same ticket and its history. Repeating a removal on an already queued ticket is rejected. The status endpoint cannot move a ticket into or out of the queue, and a queued ticket cannot be closed directly. Taking a new ticket into work and entering or leaving the queue each emit one ticket.status_changed event. Its required assigneeId contains the employee assigned after the transition, or null when entering pending_assignment. The actor identifies who initiated the change and can differ from the assigned employee. These transitions do not also emit ticket.assignee_changed; that event is used for direct reassignment between employees while the ticket remains active. In Ticket objects, assigneeId is still omitted when there is no assignee. The status-change webhook always includes the field, using an explicit null for an unassigned ticket.

Scenarios

Restore period

The restore period controls what happens when a client sends a new message after a ticket was closed. The restore period is stored as restorePeriodMs and is configured in the YoLead UI in the company channel settings. If the client writes within the restore period, the message is treated as a continuation of the previous ticket and the ticket reopens. If the client writes after the restore period, the message is treated as a new request and a new ticket is created in the same chat.

Imported and disconnected-channel history

YoLead can link earlier source-channel messages to a separate inactive ticket through previousTicket. Imported history does not represent a new client request and does not trigger AI replies or auto-replies. History already stored in YoLead can still be read after its company channel is disconnected or removed, subject to the same company access and plan restrictions. VK tickets whose history is read from the provider still require an available channel and provider access. A new ticket’s history is unavailable; a pending_assignment ticket’s history is readable before it is assigned. Endpoint-specific request and response fields are documented in the REST API reference.