> ## Documentation Index > Fetch the complete documentation index at: https://docs.yo-lead.com/llms.txt > Use this file to discover all available pages before exploring further. # Events > YoLead webhook event reference. Webhook payloads use this envelope: ```json theme={null} { "id": "event_id", "type": "message.incoming", "createdAt": "2026-05-08T12:00:00.000Z", "data": {} } ``` Current event types: * `ticket.created` * `ticket.status_changed` * `message.incoming` * `ticket.assignee_changed` ## Objects used inside `data` These reusable object shapes are nested under the event `data` field. Optional fields are omitted when the underlying value is not available. ### Ticket object | Field | Type | Required | Description | | -------------- | --------------------------- | -------- | -------------------------------------------------------------------------------------- | | `id` | `string` | Yes | YoLead ticket id. | | `chatId` | `string` | Yes | YoLead chat id associated with the ticket. | | `status` | `new \| active \| inactive` | Yes | Current ticket status. | | `channel.id` | `string` | Yes | YoLead company channel id. | | `channel.type` | `string` | Yes | Source channel type, such as `telegram`, `whatsapp`, `facebook`, `instagram`, or `vk`. | | `assigneeId` | `string` | No | Current employee assigned to the ticket. | | `startedAt` | `string` | Yes | Ticket start time as an ISO 8601 date-time string. | | `endedAt` | `string` | No | Ticket close time as an ISO 8601 date-time string. | ```json theme={null} { "id": "64f000000000000000000003", "chatId": "64f000000000000000000002", "status": "active", "channel": { "id": "64f000000000000000000010", "type": "telegram" }, "assigneeId": "64f000000000000000000001", "startedAt": "2026-05-08T11:00:00.000Z", "endedAt": "2026-05-08T12:00:00.000Z" } ``` ### Client object | Field | Type | Required | Description | | -------------- | -------------- | -------- | --------------------------------------------------------------------------- | | `firstName` | `string` | Yes | Client display first name or fallback display name from the source channel. | | `lastName` | `string` | No | Client last name when provided by the source channel. | | `photo` | `string` | No | URL of the client profile photo. | | `username` | `string` | No | Username or profile name from the source channel. | | `phone` | `string` | No | Client phone number when available, usually from WhatsApp. | | `parentUserId` | `string` | No | Parent/source user id when provided by the channel payload. | | `link` | `string` | No | Link to the client's profile or contact page in the source channel. | | `gender` | `man \| woman` | No | Client gender when provided by the source channel. | ```json theme={null} { "firstName": "Client", "lastName": "Name", "photo": "https://example.com/photo.jpg", "username": "client_username", "phone": "+15551234567", "parentUserId": "parent-user-id", "link": "https://example.com/client", "gender": "man" } ``` ### Message object | Field | Type | Required | Description | | ------------- | -------- | -------- | ----------------------------------------------------------------------------- | | `id` | `string` | Yes | Source-channel message id. | | `sentAt` | `string` | No | Message send time as an ISO 8601 date-time string. | | `fromId` | `string` | Yes | Sender id from the source channel. | | `text` | `string` | Yes | Message text. Empty string when there is no text. | | `attachments` | `array` | Yes | Message attachments from the source channel. Empty array when there are none. | ```json theme={null} { "id": "wamid.HBg...", "sentAt": "2026-05-08T11:01:00.000Z", "fromId": "15551234567", "text": "Hello", "attachments": [] } ``` ### Employee object | Field | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------- | | `id` | `string` | Yes | YoLead employee id. | | `firstName` | `string` | No | Employee first name. | | `lastName` | `string` | No | Employee last name. | | `position` | `string` | Yes | Employee position/title in YoLead. | ```json theme={null} { "id": "64f000000000000000000001", "firstName": "Alex", "lastName": "Smith", "position": "Operator" } ``` ## `ticket.created` Sent when a new ticket is created from an incoming message. ```json theme={null} { "id": "evt_64f000000000000000000100", "type": "ticket.created", "createdAt": "2026-05-08T11:01:00.000Z", "data": { "ticket": { "id": "64f000000000000000000003", "chatId": "64f000000000000000000002", "status": "new", "channel": { "id": "64f000000000000000000010", "type": "telegram" }, "startedAt": "2026-05-08T11:00:00.000Z" }, "client": { "firstName": "Client", "lastName": "Name", "photo": "https://example.com/photo.jpg", "username": "client_username", "phone": "+15551234567", "parentUserId": "parent-user-id", "link": "https://example.com/client", "gender": "man" }, "message": { "id": "wamid.HBg...", "sentAt": "2026-05-08T11:01:00.000Z", "fromId": "15551234567", "text": "Hello", "attachments": [] } } } ``` ## `message.incoming` Sent when a new incoming message is received for a ticket. ```json theme={null} { "id": "evt_64f000000000000000000101", "type": "message.incoming", "createdAt": "2026-05-08T11:05:00.000Z", "data": { "ticket": { "id": "64f000000000000000000003", "chatId": "64f000000000000000000002", "status": "active", "channel": { "id": "64f000000000000000000010", "type": "telegram" }, "assigneeId": "64f000000000000000000001", "startedAt": "2026-05-08T11:00:00.000Z" }, "client": { "firstName": "Client", "lastName": "Name", "photo": "https://example.com/photo.jpg", "username": "client_username", "phone": "+15551234567", "parentUserId": "parent-user-id", "link": "https://example.com/client", "gender": "man" }, "message": { "id": "wamid.HBg...", "sentAt": "2026-05-08T11:05:00.000Z", "fromId": "15551234567", "text": "I need help", "attachments": [] } } } ``` ## `ticket.status_changed` Sent when a ticket status changes. Payload fields: | Field | Type | Required | Description | | ----------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `ticketId` | `string` | Yes | YoLead ticket id whose status changed. | | `chatId` | `string` | Yes | YoLead chat id associated with the ticket. | | `oldStatus` | `new \| active \| inactive` | Yes | Previous ticket status. | | `newStatus` | `new \| active \| inactive` | Yes | New ticket status. | | `actor` | `string` | Yes | Actor that triggered the status change. Public API changes use `api`; employee and embed UI changes use the employee display name; automatic reactivation by an incoming client message uses `client`. | | `changedAt` | `string` | Yes | Status change time as an ISO 8601 date-time string. | ```json theme={null} { "id": "evt_64f000000000000000000102", "type": "ticket.status_changed", "createdAt": "2026-05-08T11:10:00.000Z", "data": { "ticketId": "64f000000000000000000003", "chatId": "64f000000000000000000002", "oldStatus": "new", "newStatus": "active", "actor": "api", "changedAt": "2026-05-08T11:10:00.000Z" } } ``` `oldStatus` and `newStatus` can be `new`, `active`, or `inactive`. ## `ticket.assignee_changed` Sent when a ticket assignee changes. Payload fields: | Field | Type | Required | Description | | -------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `ticket` | `Ticket object` | Yes | Ticket after the assignee change. | | `previousAssigneeId` | `string` | No | Previous employee assignee id, omitted when there was no previous assignee. | | `assignee` | `Employee object` | Yes | New employee assigned to the ticket. | | `actor` | `string` | Yes | Actor that triggered the assignee change. Public API changes use `api`; employee and embed UI changes use the employee display name. | | `changedAt` | `string` | Yes | Assignee change time as an ISO 8601 date-time string. | ```json theme={null} { "id": "evt_64f000000000000000000103", "type": "ticket.assignee_changed", "createdAt": "2026-05-08T11:12:00.000Z", "data": { "ticket": { "id": "64f000000000000000000003", "chatId": "64f000000000000000000002", "status": "active", "channel": { "id": "64f000000000000000000010", "type": "telegram" }, "assigneeId": "64f000000000000000000001", "startedAt": "2026-05-08T11:00:00.000Z" }, "previousAssigneeId": "64f000000000000000000004", "assignee": { "id": "64f000000000000000000001", "firstName": "Alex", "lastName": "Smith", "position": "Operator" }, "actor": "Alex Smith", "changedAt": "2026-05-08T11:12:00.000Z" } } ```