¿Ya eres cliente de Spur?

Entrar
Frame events

Talk to the frame

The frame posts events to its parent window and accepts three commands, all with window.postMessage.

Trusting messages

Before reading event.data, check that event.origin is https://embed.spurnow.com and that event.source is your iframe’s contentWindow. Send commands with that same origin as the target. Until its session starts, the frame only sends spur:ready, spur:authRequired and spur:error; after that it sends events to your page’s origin only. The frame takes commands, spur:verify included, only from its parent window.

Events (frame → page)

typePayloadWhen
spur:ready{ version }The frame loaded and is checking its session. version is 1. On a token link, answer with spur:verify.
spur:authenticated{ userId, sessionExpiresAt, masked }The session started. masked is true when the Spur user has Hide contact identity on.
spur:authRequired{ reason }The frame needs a new token: mint one and set src again. reason is expired, invalidToken, originMismatch or userInactive.
spur:conversationOpened{ conversationId, contactId, channelId, conversationStatus, assignedUserId, contact: { displayName, displayNumber } }The thread finished loading. contact holds the strings the header shows (see below).
spur:conversationNotFound{ conversationId }The conversation doesn’t exist, or the Spur user’s permissions don’t cover it. conversationId is null when you opened by contact and number.
spur:messageSent{ conversationId, messageId }Someone sent a message from the frame. Notes don’t count.
spur:conversationStatusChanged{ conversationId, conversationStatus }Someone clicked Close ticket, or reopened the conversation, in the frame. OPEN or CLOSED.
spur:error{ code }Something failed inside the frame. loadFailed: the frame couldn’t load its data. verifierMissing: no spur:verify answered spur:ready within 10 seconds; the frame shows Try again, which asks again.

contact.displayName and contact.displayNumber are what the frame’s header shows. For a user with Hide contact identity on, both are the masked number (for example +91 98•••• ••97): events never carry that contact’s phone number, WhatsApp username or name. For other users they’re the contact’s name and formatted number.

Commands (page → frame)

typePayloadEffect
spur:verify{ codeVerifier }Your answer to spur:ready: the code verifier whose SHA-256 you minted the token with, 43 to 128 characters. The frame sends it to Spur with the origin your browser stamps on this message, and the token is only spent when both match. Send it with Spur’s origin as the target, never “*”.
spur:openConversation{ conversationId } or { contactId, channelId }Switch conversations without reloading. The session carries over, and every request is checked against the Spur user’s permissions. With contactId and channelId the frame opens, or starts, that contact’s conversation on that number.
spur:prefill{ text }Put plain text in the reply box for the person to review and send. It never sends by itself. Up to 4,096 characters. It doesn’t pick a template; templates stay available in the frame’s template picker.
crm-page.js
const frame = document.getElementById('spur-conversation');

frame.contentWindow.postMessage(
  { type: 'spur:openConversation', conversationId: 49207711 },
  'https://embed.spurnow.com',
);

frame.contentWindow.postMessage(
  { type: 'spur:prefill', text: 'Hi Rahul, your consult is confirmed for 4 pm.' },
  'https://embed.spurnow.com',
);

Commands that arrive before the session starts are held and applied once it does. Unknown types and malformed payloads are ignored.

Handling expiry

Sessions last 8 hours and can’t be extended. When one ends, or a token is refused, the frame posts spur:authRequired. Mint a fresh token and set src again. If it keeps happening, stop after a few tries and show an error: a removed origin or a deactivated user won’t fix itself.

crm-page.js
window.addEventListener('message', async (e) => {
  if (e.origin !== 'https://embed.spurnow.com') return;
  if (e.source !== frame.contentWindow) return;

  if (e.data?.type === 'spur:ready') {
    frame.contentWindow.postMessage({ type: 'spur:verify', codeVerifier }, 'https://embed.spurnow.com');
  }
  if (e.data?.type === 'spur:authRequired') {
    // mountSpur from the quickstart: a new verifier, a new token, a new src.
    await mountSpur(current.recordId);
  }
});

Fixed behaviour

  • There are no configuration flags and no theming. The frame looks and behaves like a conversation in Spur, for that user.
  • There’s no number picker. Your CRM picks the WhatsApp number when it mints the token and switches with spur:openConversation.
  • The Spur user’s permissions apply: someone who can’t close conversations in Spur can’t close them in the frame.
  • Embed sessions are limited to conversation work whatever the role: even an owner’s session can’t reach settings, billing or conversation lists.
  • Improvements to Spur’s conversation view generally show up in the frame too.