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:
- Your backend asks the Platform API for a session. It needs the
embed:sessionsscope. The answer holds a single-useclient_secretthat is valid for 120 seconds. - Your page loads
wavely-embed.jsfrom the Wavely address, at/embed/v1/wavely-embed.js. - The SDK runs
initwith your publishable keywvpk_...and a function that fetches theclient_secretfrom your backend. - 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 aconversationslist or asummary.channels: the Channels page, which can be filtered toweborwhatsapp.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.