Create a session - YoLead Developers

Use POST /v1/embed/sessions to create an iframe session. The request must be signed with the same HMAC headers as other Public API requests.

Create embed sessions on your backend. Do not call this endpoint from browser code because it requires the API secret.

{
  "employeeId": "64f000000000000000000001",
  "chatId": "64f000000000000000000002",
  "capabilities": ["showChatPage"]
}

Request fields:

Field	Type	Required	Description
`employeeId`	`string`	Yes	Active YoLead employee id that will act inside the iframe.
`chatId`	`string`	No	Chat to open or restrict the iframe session to. Required when `showChatPage` is requested without `showChatsList`.
`capabilities`	`array`	Yes	List of requested iframe capabilities. At least one view capability must remain after scope filtering.

The response contains iframeUrl. Render that URL in an iframe on your frontend.

{
  "data": {
    "iframeUrl": "https://app.yo-lead.com/embed/chats/64f000000000000000000002#token=eyJ...",
    "embedToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2026-05-08T12:15:00.000Z",
    "capabilities": ["showChatPage"],
    "allowedChatId": "64f000000000000000000002"
  }
}

<iframe src="https://app.yo-lead.com/embed/chats/64f000000000000000000002#token=..." />

Response fields:

Field	Type	Description
`iframeUrl`	`string`	URL to render in the customer frontend.
`embedToken`	`string`	Short-lived token consumed by the YoLead iframe runtime.
`expiresAt`	`string`	Token expiration time as an ISO 8601 date-time string. Embed sessions expire after 60 minutes.
`capabilities`	`array`	Effective capabilities granted to this session after API key scope filtering.
`allowedChatId`	`string`	Present when the session is restricted to a single chat.

Validation rules

employeeId must belong to an active employee in the API key company.
Requested capabilities are filtered by API key scope.
read keys can only grant showChatsList and showChatPage.
read-write keys can grant all supported capabilities.
At least one view capability is required: showChatsList or showChatPage.
If showChatPage is requested without showChatsList, chatId is required.
If chatId is provided, the employee must have access to that chat.

​Validation rules

Validation rules