For developers

Embedded components

Wavely's embedded components show Wavely screens inside your own app's pages through an iframe, using a short-lived session from your server.

How it works

Embedded components show Wavely screens inside your app's pages, through an iframe. The flow:

  1. Your backend asks the Platform API for a session. It needs the embed:sessions scope. The answer holds a single-use client_secret that is valid for 120 seconds.
  2. Your page loads wavely-embed.js from the Wavely address, at /embed/v1/wavely-embed.js.
  3. The SDK runs init with your publishable key wvpk_... and a function that fetches the client_secret from your backend.
  4. The frame trades that secret for a ten-minute token it keeps in memory only. The frame uses no browser storage.

Backend:

curl -X POST https://WAVELY-HOST/platform/v1/embed-sessions \
  -H "Authorization: Bearer wvsk_..." \
  -H "Wavely-Organization: BUSINESS-ID" \
  -H "Content-Type: application/json" \
  -d '{"agent_external_ref":"agent-42","components":["inbox","notifier"],"origin":"https://app.example.com"}'

Your page:

const wavely = WavelyEmbed.init({
  publishableKey: "wvpk_...",
  fetchClientSecret: async () => {
    const res = await fetch("/api/wavely-session", { method: "POST" })
    return (await res.json()).client_secret
  },
})
const inbox = wavely.create("inbox", {})
document.getElementById("inbox").append(inbox.element)

Pick the agent with agent_id or agent_external_ref. The origin must be on your app's allowed origins, otherwise Wavely answers origin_not_allowed. The frame only displays on those origins.

The nine components

One session asks for 1 to 8 components for one agent.

  • inbox: the inbox with its thread and composer.
  • traffic: the board of visitors on the site.
  • numbers: WhatsApp numbers.
  • canned: canned responses and their events.
  • fleet: the dashboard and table of WhatsApp servers. Operator sessions only.
  • notifier: shows nothing. It only reports new or unread chats, so you can badge your own app.
  • contact: a contact panel, either a conversations list or a summary.
  • channels: the Channels page, which can be filtered to web or whatsapp.
  • branches: the Branches page.

The agent's role decides what can be requested. numbers and channels need a role that may manage channels, and branches needs a role that may manage branches. The other components are open to every role. A fleet session is created through POST /platform/v1/embed-sessions/operator, with the scopes embed:sessions and fleet:operate.

Commands and events

Each component that create returns has commands such as openConversation, openContact, setLocale, setBranch and destroy. Listen for events with on, for example ready, conversation.selected, unread.changed and session.expired. The full list is in the SDK's type file.