Já é cliente da Spur?

Entrar
Quickstart

Embed a conversation in five steps

You need a small backend route that talks to Spur, an iframe on your page, and a message listener. Plan on an afternoon.

Before you start

An API key just for the embed

Create one in Settings → Developers → API. It stays on your server. A dedicated key means you can replace it without touching your other integrations.

The Spur user the frame acts as

Either each person’s own Spur seat, or one shared user for your whole team. Its role needs Inbox access with sending; to open conversations assigned to someone else, the role must also see other people’s conversations.

Masking, if your team shouldn’t see numbers

Settings → Team → the user → Hide contact identity. That user then never sees customers’ numbers, WhatsApp usernames or names, and can’t sign in to the Spur dashboard.

Your WhatsApp numbers’ channel IDs

Settings → Developers → Embeds lists every number with its channelId. A token request must name one when you have more than one number.

1. Allow your domain

The frame refuses to load inside any site you haven’t listed. Add every page origin that will show it in Settings → Developers → Embeds → Allowed origins.

  • Full origins only: https://crm.acme.com. No wildcards, paths or trailing slash. Up to 50.
  • HTTPS, except for local development on http://localhost:3000 or http://127.0.0.1:3000.
  • Changes take effect within a minute.
  • If your own page sets a Content-Security-Policy, also allow frame-src https://embed.spurnow.com.

A page on an origin that isn’t listed gets a blank frame and a “Refused to frame” error in the browser console.

2. Mint a token on your server

Never call this from the browser: the request carries your workspace API key, which can read and send on every conversation in your workspace.

Request
POST https://api.spurnow.com/embed/tokens
Authorization: Bearer <workspace API key>
Content-Type: application/json

{
  "user": { "email": "crm@acme.com" },
  "contact": { "number": "+919876543210", "firstName": "Rahul" },
  "channelId": 1042,
  "origin": "https://crm.acme.com",
  "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
}
Response
201 Created

{
  "token": "emb_…",
  "embedUrl": "https://embed.spurnow.com/auth?token=emb_…",
  "expiresAt": "2026-10-20T10:31:04Z",
  "userId": 318,
  "contactId": 9812,
  "conversationId": 49205067,
  "channelId": 1042,
  "sessionTtl": 28800
}

contactId, conversationId and channelId tell you exactly what the frame opened. Store them on your record and mint with contact.id or conversationId next time. All fields are in the API reference.

server.js
// Your backend (Node / Express). The API key never leaves this server.
app.get('/api/spur/embed-url', requireCrmLogin, async (req, res) => {
  const record = await crm.records.get(req.query.recordId);

  const r = await fetch('https://api.spurnow.com/embed/tokens', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPUR_EMBED_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user: { email: 'crm@acme.com' },      // the Spur user the frame acts as
      contact: record.spurContactId
        ? { id: record.spurContactId }      // known contact: send the Spur id
        : { number: record.phone, firstName: record.firstName },
      channelId: record.spurChannelId ?? 1042, // which of your numbers
      origin: 'https://crm.acme.com',       // the page that shows the frame
      codeChallenge: req.query.codeChallenge, // from the page; see step 3
    }),
  });
  const body = await r.json();
  if (!r.ok) return res.status(r.status).json(body);

  // Store Spur's ids so the next mint (and the browser) never needs the number.
  await crm.records.update(record.id, {
    spurContactId: body.contactId,
    spurChannelId: body.channelId,
    spurConversationId: body.conversationId,
  });
  res.json({ embedUrl: body.embedUrl, conversationId: body.conversationId });
});

3. Embed the frame

crm-page.html
<iframe id="spur-conversation"
  src=""
  allow="clipboard-write; microphone"
  style="width: 100%; height: 100%; border: 0"></iframe>

<script>
  const base64url = (bytes) =>
    btoa(String.fromCharCode(...new Uint8Array(bytes)))
      .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

  // The verifier for the frame that is loading. It never leaves this page.
  let codeVerifier;

  async function mountSpur(recordId) {
    codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
    const codeChallenge = base64url(
      await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier)),
    );
    const r = await fetch(
      `/api/spur/embed-url?recordId=${recordId}&codeChallenge=${codeChallenge}`,
    );
    const { embedUrl } = await r.json();
    document.getElementById('spur-conversation').src = embedUrl;
  }
</script>
  • microphone is needed for voice notes and WhatsApp calls; clipboard-write makes the copy buttons work.
  • Make a new code verifier for every token. Only its SHA-256 goes to your server, as codeChallenge; the verifier itself goes straight to the frame in step 4. A link copied from a log, a screenshot or the network tab opens nothing without it.
  • crypto.subtle needs HTTPS, or http://localhost while you develop.
  • Using React or Svelte? Copy a ready-made component from React & Svelte.
  • The token in embedUrl works once. Mint a new one for every load and never cache it. Right after loading, the frame moves to a clean URL so the token doesn’t stay in the browser history.

4. Listen to the frame

The frame tells your page what happens inside it, and takes commands to switch conversations or put text in the reply box. Every integration handles two events. Answer spur:ready with spur:verify and the verifier, or the token link opens nothing. And handle spur:authRequired: sessions last 8 hours and don’t extend.

crm-page.js
const SPUR = 'https://embed.spurnow.com';
const frame = document.getElementById('spur-conversation');

window.addEventListener('message', async (e) => {
  // Trust only the Spur frame.
  if (e.origin !== SPUR || e.source !== frame.contentWindow) return;

  switch (e.data?.type) {
    case 'spur:ready':
      // The frame asks for the verifier of the link it was given. Spur's origin only.
      frame.contentWindow.postMessage({ type: 'spur:verify', codeVerifier }, SPUR);
      break;
    case 'spur:authRequired':
      // The session ended or the token was refused: mint a new one.
      await mountSpur(current.recordId);
      break;
    case 'spur:conversationStatusChanged':
      if (e.data.conversationStatus === 'CLOSED') {
        await fetch(`/api/spur/hand-back?recordId=${current.recordId}`, { method: 'POST' });
      }
      break;
  }
});

// Another record: switch the open frame. No new token.
function showRecord(record) {
  frame.contentWindow.postMessage(
    { type: 'spur:openConversation', conversationId: record.spurConversationId },
    SPUR,
  );
}

Every event and command is in Frame events.

5. Hand off the AI agent

If Spur’s AI agent answers on the number you embed, it keeps replying until a person is assigned. Opening a frame doesn’t assign anyone. Do it from your backend:

server.js
// When someone picks up the record: the AI agent stops on this conversation.
await spur.post(`/conversations/${conversationId}/assign`, { to: 'user', userId: 318 });

// When they're done: the AI agent answers the next customer message.
await spur.post(`/conversations/${conversationId}/assign`, { to: 'ai' });

Skip the first call and the AI agent and your team may both reply. Skip the second and the AI stays off on that conversation. See the handoff sequence.

Go-live checklist

  • ✓ Every origin that shows the frame, including staging, is on the allowed list.
  • ✓ The API key exists only on your server, in a secret store. It is a key used for nothing but the embed.
  • ✓ Your browser code never sees a phone number: it asks your backend, and works with record and Spur IDs.
  • ✓ Your page mints a fresh token on every frame load and on every spur:authRequired, and never caches embedUrl.
  • ✓ Every mint gets a new code verifier. Only its SHA-256 leaves the page, and the verifier goes to the frame in spur:verify, with Spur’s origin as the target.
  • ✓ Your message listener checks event.origin and event.source before reading event.data.
  • ✓ If Spur’s AI agent works on these numbers, your backend assigns the conversation to the user when work starts and back to the AI when it ends.
  • ✓ If your team shares one Spur user, your CRM keeps its own record of who sent what.