Events - YoLead Developers

Webhook payloads use this envelope:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "id": "64f000000000000000000001",
  "firstName": "Alex",
  "lastName": "Smith",
  "position": "Operator"
}

`ticket.created`

Sent when a new ticket is created from an incoming message.

{
  "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.

{
  "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.

{
  "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.

{
  "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"
  }
}

​Objects used inside data

​Ticket object

​Client object

​Message object

​Employee object

​ticket.created

​message.incoming

​ticket.status_changed

​ticket.assignee_changed