Events

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: `telegram`, `telegram_account`, `whatsapp`, `facebook`, `instagram`, `vk`, `max`, or `email`.
`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.
`attribution`	`object<string, string>`	No	Ticket acquisition metadata. Instagram tickets created from an Ads referral currently include `ad_id`.

{
  "id": "64f000000000000000000003",
  "chatId": "64f000000000000000000002",
  "status": "active",
  "channel": {
    "id": "64f000000000000000000010",
    "type": "instagram"
  },
  "assigneeId": "64f000000000000000000001",
  "startedAt": "2026-05-08T11:00:00.000Z",
  "endedAt": "2026-05-08T12:00:00.000Z",
  "attribution": {
    "ad_id": "120000000000000001"
  }
}

attribution is captured when a ticket is created. Integrations should treat it as an extensible string-to-string object and ignore keys they do not recognize.

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.
`email`	`string`	No	Client email address for an email-channel conversation.
`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",
  "email": "client@example.com",
  "parentUserId": "parent-user-id",
  "link": "https://example.com/client",
  "gender": "man"
}

Message object

Field	Type	Required	Description
`id`	`string`	Yes	Message identifier used by YoLead for the channel conversation. Email message ids are numeric-looking strings.
`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.
`subject`	`string`	No	Email subject, up to 998 characters. Omitted when the message has no subject or did not come from an email channel.
`attachments`	`Attachment object[]`	Yes	Message attachment descriptors. Empty array when there are none.

{
  "id": "wamid.HBg...",
  "sentAt": "2026-05-08T11:01:00.000Z",
  "fromId": "15551234567",
  "text": "Hello",
  "attachments": []
}

For email messages, fromId is the address in the message’s From header. The client email is taken from a single valid Reply-To address when one is present; otherwise it is taken from From.

{
  "id": "3604480123456789",
  "sentAt": "2026-08-11T11:01:00.000Z",
  "fromId": "sender@example.com",
  "text": "Hello, I need help with my order.",
  "subject": "Order question",
  "attachments": [
    {
      "id": "64b000000000000000000002",
      "kind": "document",
      "fileName": "order.pdf",
      "mimeType": "application/pdf",
      "size": 4096
    }
  ]
}

Attachment object

Telegram Bot, Telegram Account, MAX, VK, email, Facebook, and Instagram messages can contain attachment descriptors. Existing stored messages are not automatically backfilled.

Field	Type	Required	Description
`id`	`string`	Yes	YoLead attachment identifier.
`kind`	`string`	Yes	`image`, `animation`, `audio`, `voice`, `video`, `video_note`, `document`, `sticker`, or `unknown`.
`accessMode`	`external`	No	Indicates an attachment available through an external source in standard descriptors.
`fileName`	`string`	No	Original filename when available.
`mimeType`	`string`	No	MIME type when known.
`size`	`integer`	No	File size in bytes when known.
`width`	`integer`	No	Media width in pixels when known.
`height`	`integer`	No	Media height in pixels when known.
`duration`	`integer`	No	Media duration in seconds when known.

Only id and kind are guaranteed in standard descriptors. These descriptors do not contain provider URLs, provider identifiers, credentials, or YoLead storage details. VK descriptors identified by source: "vk" use an opaque string id and can include optional contentUrl, previewUrl, and externalUrl fields instead of accessMode. See Message attachments for the two formats and imported-history availability. The Public API does not provide an API-key-authenticated endpoint for downloading attachment bytes.

Employee object

Field	Type	Required	Description
`id`	`string`	Yes	YoLead employee id.
`firstName`	`string`	No	Employee first name.
`lastName`	`string`	No	Employee last name.
`kind`	`human \| ai`	Yes	Whether the employee is a human or an AI operator.
`position`	`string`	Yes	Employee position/title in YoLead.

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

`ticket.created`

Sent when a new ticket is created from an incoming message. When an AI operator automatically takes the request into work, the ticket can already have status: "active" and the AI employee’s assigneeId in this event. Do not assume that every ticket.created event has status new.

{
  "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"
      },
      "attribution": {
        "ad_id": "120000000000000001"
      },
      "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": []
    }
  }
}

Email example

An incoming email uses the same event envelope and adds the email-specific channel, client, and message fields:

{
  "id": "evt_64f000000000000000000104",
  "type": "message.incoming",
  "createdAt": "2026-08-11T11:05:00.000Z",
  "data": {
    "ticket": {
      "id": "64f000000000000000000003",
      "chatId": "64f000000000000000000002",
      "status": "active",
      "channel": {
        "id": "64f000000000000000000010",
        "type": "email"
      },
      "assigneeId": "64f000000000000000000001",
      "startedAt": "2026-08-11T11:00:00.000Z"
    },
    "client": {
      "firstName": "Customer",
      "email": "customer@example.com",
      "link": "mailto:customer@example.com"
    },
    "message": {
      "id": "3604480123456789",
      "sentAt": "2026-08-11T11:05:00.000Z",
      "fromId": "sender@example.com",
      "text": "Hello, I need help with my order.",
      "subject": "Order question",
      "attachments": [
        {
          "id": "64b000000000000000000002",
          "kind": "document",
          "fileName": "order.pdf",
          "mimeType": "application/pdf",
          "size": 4096
        }
      ]
    }
  }
}

`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, Embed, and AI actions 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, Embed, and AI actions 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",
      "kind": "human",
      "position": "Operator"
    },
    "actor": "Alex Smith",
    "changedAt": "2026-05-08T11:12:00.000Z"
  }
}

Start

Integration basics

REST API

Webhooks

Embed iframe

Resources

Objects used inside `data`

Ticket object

Client object

Message object

Attachment object

Employee object

`ticket.created`

`message.incoming`

Email example

`ticket.status_changed`

`ticket.assignee_changed`

​Objects used inside data

​Ticket object

​Client object

​Message object

​Attachment object

​Employee object

​ticket.created

​message.incoming

​Email example

​ticket.status_changed

​ticket.assignee_changed

Objects used inside `data`

Ticket object

Client object

Message object

Attachment object

Employee object

`ticket.created`

`message.incoming`

Email example

`ticket.status_changed`

`ticket.assignee_changed`