Skip to main content
The embed flow has two sides:
  1. Your backend creates a short-lived embed session with POST /v1/embed/sessions.
  2. Your frontend renders the returned iframeUrl.
  3. The YoLead iframe uses the embed token to access runtime data.
Create embed sessions only from your backend. Do not expose the API secret in browser code.
The embed token identifies:
  • the YoLead company;
  • the employee acting inside the iframe;
  • the API key that created the session;
  • enabled UI capabilities;
  • optional chat restriction;
  • expiration time.
Capabilities control what the iframe may show in the UI. They do not replace backend access checks. YoLead still validates employee access, chat access, ticket state, and API key scope for each runtime action.

​
Integration patterns

Use a single-chat iframe when your CRM already has a specific conversation or ticket context. Pass chatId and request showChatPage. Use an inbox iframe when you want to show a list of available chats inside your product. Request showChatsList and showChatPage. Use an outbound-chat iframe when users should be able to start a new conversation. With a read-write API key, request showChatPage and startOutboundChat. You can omit chatId, and the iframe opens the outbound message composer. After a successful outbound message, the iframe sends a chat.created event to the parent window with the resulting chatId. Use write capabilities only when the user should be able to act from the embedded UI, such as sending messages, changing ticket status, or changing assignee.

​
Security model

  • Your backend signs the Public API request.
  • Your frontend only receives the returned iframeUrl.
  • The API secret must never be sent to the browser.
  • The embed token is placed in the URL hash, so it is not sent to the frontend server as part of the HTTP request URL.
  • Embed sessions are short-lived. Use the returned expiresAt value and create a new session when the previous one expires.