Create a session

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`, unless `startOutboundChat` is also requested.
`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=..." />

When showChatPage and startOutboundChat are requested without showChatsList or chatId, the returned iframeUrl uses the /embed/chats/outbound path and opens the outbound message composer. 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. Use this value instead of assuming a fixed session lifetime.
`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.
startOutboundChat requires a read-write key. Requesting it with a read key returns 403.
At least one view capability is required: showChatsList or showChatPage.
If showChatPage is requested without showChatsList, chatId is required unless startOutboundChat is also requested.
If chatId is provided, the employee must have access to that chat.

Start

Integration basics

REST API

Webhooks

Embed iframe

Resources

Validation rules

​Validation rules

Validation rules