Messenger SDK
Embed the ChaosDesk messenger on your website or in your app, control it with zE(), and sign visitors in with a JWT.
The ChaosDesk messenger is a chat window for your website and apps. Bot flows answer first, then hand the conversation to an agent, where it becomes a messaging ticket.
Embed it
Each brand has its own key under Admin Center, Channels, Messenger. Add the snippet before </body>:
<script id="ze-snippet" src="https://app.chaosdesk.io/messenger.js?key=YOUR_KEY"></script>The id="ze-snippet" and the zE() API match the Zendesk Web Widget (messaging), so a site moving from Zendesk only changes the script URL and the key. Add https://app.chaosdesk.io to script-src, frame-src and connect-src if your site has a Content Security Policy. Your ChaosDesk help centre adds the snippet by itself when the brand’s messenger is on.
The zE() API
| Call | What it does |
|---|---|
zE('messenger', 'open') / 'close' | Opens or closes the conversation window |
zE('messenger', 'show') / 'hide' | Shows or hides the launcher |
zE('messenger', 'loginUser', cb => cb(jwt)) | Signs the visitor in (see below) |
zE('messenger', 'logoutUser') | Ends the signed-in session |
zE('messenger:on', 'open' | 'close', fn) | Runs fn when the window opens or closes |
zE('messenger:on', 'unreadMessages', fn) | fn(count) on every change of the unread count |
zE('messenger:set', 'locale', 'fr') | Sets the interface language |
zE('messenger:set', 'zIndex', 99999) | Sets the stacking order |
zE('messenger:set', 'cookies', false) | Hides the messenger and deletes its stored data (consent off) |
zE('messenger:set', 'conversationFields', [{ id, value }]) | Sets ticket fields applied at hand-off (ChaosDesk field id or key) |
zE('messenger:set', 'conversationTags', ['vip']) | Sets tags; each call replaces the previous ones |
Sign visitors in
Signed-in visitors see their conversation history on every device, and agents see who they are. The JWT has the same shape as Zendesk’s messaging JWT, so an existing token service only needs the new secret:
- Header:
{"alg": "HS256", "typ": "JWT", "kid": "<key id>"}, signed with the shared secret from Admin Center, Channels, Messenger (create a new secret, do not reuse an old one). RS256 with a JWKS URL is supported too. - Claims:
scope: "user",external_id(required), and optionallyname,email,email_verifiedandexp. - ChaosDesk links the visitor to the user with that
external_id, otherwise to the user with that verified email, otherwise to a new end user.
zE('messenger', 'loginUser', function (callback) {
fetch('/chat-token').then(r => r.text()).then(callback);
});Allowed domains, business hours and the bot flows are set per brand in the Admin Center.
Mobile apps
Embed the messenger in a WebView in iOS and Android apps today. Native SDKs are on the roadmap.