Já é cliente da Spur?

Entrar
API reference

Spur Embed API

Three endpoints: one mints the frame’s token, one lists a contact’s conversations across your WhatsApp numbers, and one hands a conversation between Spur’s AI agent and a person. The same endpoints are in the REST API reference.

Authentication

Send your workspace API key as a bearer token: Authorization: Bearer <key>. Create keys in Settings → Developers → API. Call these endpoints from your server only.

POST /embed/tokens

Mints a single-use token and returns the URL to load in your iframe. Returns 201.

FieldRequiredNotes
user.email or user.idYesThe Spur user the frame acts as. Must be an active member who has accepted their invite. The session gets that user’s role, permissions and masking setting.
contact.numberOne of these threeThe contact’s WhatsApp number in international format: + and the country code, e.g. +919876543210. Numbers without + are refused. If no contact has it, Spur creates one; contact.firstName, contact.lastName and contact.email are used only then.
contact.idOne of these threeA Spur contact ID, typically the contactId from an earlier response.
conversationIdOne of these threeOpen this conversation directly. It already identifies the WhatsApp number, so channelId isn’t needed.
channelIdWith contact, if you have more than one WhatsApp numberWhich of your numbers to open the contact on. Spur doesn’t guess: you can leave it out only when exactly one number is connected.
originYesThe origin of the page that will show the frame, such as https://crm.acme.com. Must be on your allowed list.
codeChallengeYesBASE64URL(SHA-256(codeVerifier)), 43 characters (PKCE, S256 only). Your page makes a random codeVerifier for each token and posts it to the frame with spur:verify; only this hash goes through your server. Without the verifier the link opens nothing.
ttlNoToken lifetime in seconds, 1 to 60. Default 60. This is the token’s life, not the session’s.
Request
curl -X POST https://api.spurnow.com/embed/tokens \
  -H "Authorization: Bearer $SPUR_EMBED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": { "email": "crm@acme.com" },
    "contact": { "id": 9812 },
    "channelId": 1042,
    "origin": "https://crm.acme.com",
    "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
  }'
Response 201
{
  "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
}
Response fieldMeaning
tokenThe single-use token. It’s already part of embedUrl.
embedUrlSet this as the iframe src. Works once, within ttl, from origin, with the verifier.
expiresAtWhen the token stops working (ISO 8601).
userIdThe Spur user the frame acts as. Use it for assign.
contactIdThe Spur contact. Store it on your record and mint with contact.id next time.
conversationIdThe conversation the frame opens.
channelIdThe WhatsApp number that conversation is on.
sessionTtlSession length in seconds once the frame loads (28800, 8 hours).

What a token is, and isn’t

Single use

The first load of embedUrl spends it, and the frame immediately moves to a clean URL. Mint one per frame load; don’t cache it.

Bound to your site

It only works when the frame is loaded from the origin you declared, and that origin must still be on your allowed list.

Bound to your page

It only works with the code verifier your page made for it, delivered by spur:verify from that origin. A copied or logged embedUrl opens nothing.

Not a session

It buys an 8-hour session. Sessions don’t extend; when one ends, the frame posts spur:authRequired and your page mints a new token.

No sign-in, no one-time codes

The frame never shows a sign-in form or asks for a login OTP. Your server’s API key is the proof of identity.

For your team, not your customers

Tokens act as a Spur user in your workspace. For chat on your storefront, use the Spur website widget.

GET /contacts/{contactId}/conversations

A contact can have a conversation on each of your WhatsApp numbers. This lists them so your CRM can choose which one to show; the frame itself has no number picker. Read-only: it mints no token and starts no session.

Request and response
GET https://api.spurnow.com/contacts/9812/conversations
Authorization: Bearer <workspace API key>

{
  "contactId": 9812,
  "conversations": [
    {
      "conversationId": 49205067,
      "channelId": 1042,
      "type": "wa",
      "number": "+911234567890",
      "name": "Acme Support",
      "conversationStatus": "OPEN",
      "lastMessageAt": "2026-10-19T17:02:11Z",
      "hasMessages": true
    }
  ]
}
FieldMeaning
conversationIdThe conversation on this number, or null if the contact has none there yet (only with include=all).
channelIdWhich of your WhatsApp numbers this is.
numberYour business number, never the contact’s.
nameThe number’s display name.
conversationStatusOPEN, CLOSED, or null when there’s no conversation yet.
lastMessageAtTime of the last message, or null.
hasMessagesWhether the contact has ever exchanged messages on this number.
  • By default only numbers the contact has messages on are listed, newest first. Add ?include=all to list every WhatsApp number in your workspace, with the unused ones last. That’s also the quickest way to see all your channel IDs.
  • Typical flow: call this, let your CRM pick the number, then mint with that conversationId (or switch an open frame with spur:openConversation). If your CRM already knows the number, skip this and mint with the contact and channelId.
  • WhatsApp only. A person’s Instagram or Facebook conversation is a separate contact in Spur and isn’t listed.
  • A contact that isn’t in your workspace, or isn’t a WhatsApp contact, returns 404.

POST /conversations/{conversationId}/assign

Spur’s AI agent keeps replying on a conversation until a person is assigned to it. This one endpoint handles both directions.

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

// Hand to a person (the AI agent stops on this conversation)
{ "to": "user", "userId": 318 }

// Hand back to the AI agent (clears the person)
{ "to": "ai" }
Response 200
{
  "conversationId": 49205067,
  "assignedUserId": 318,
  "aiAgentActive": false,
  "conversationStatus": "OPEN"
}
Response fieldMeaning
conversationIdThe conversation (the ID the rest of the Spur API calls inboxId).
assignedUserIdThe person assigned, or null. The rest of the API calls it assignedAgentId.
aiAgentActiveTrue when nobody is assigned and the number has an AI agent connected.
conversationStatusOPEN or CLOSED after the call.
  • userId is required with to: "user" and must be an active member of your workspace. With one shared Spur user, it’s always that user’s ID (the userId from the token response).
  • Calling it again with the same assignee is fine: you get 200 and the current state.
  • Assigning a CLOSED conversation to a person reopens it. Handing a closed conversation to the AI leaves it closed. Otherwise the status doesn’t change: use Close ticket in the frame for that.
  • The conversation’s history shows the handover, attributed to your API key, and an open frame or Spur dashboard updates straight away.
  • It hands over to whichever AI agent is connected to that number. Teams, bulk assignment and choosing a specific AI agent aren’t supported.

Handoff sequence

  1. 1. Someone opens a record: your backend calls assign with to: "user", then loads the frame.
  2. 2. They work the conversation in the frame.
  3. 3. They’re done (for example, they close the ticket in the frame and your page gets spur:conversationStatusChanged): your backend calls assign with to: "ai". The AI agent answers the next customer message.

Skip step 1 and the AI agent and your team may both reply. Skip step 3 and the AI agent stays off on that conversation. When a closed conversation gets a new message from the customer, it reopens unassigned, so the AI agent picks it up again.

Rate limits

Up to 600 tokens a minute per workspace. Over that, POST /embed/tokens returns 429 with code: "EMBED_RATE_LIMITED" and retryAfter in seconds. Switching conversations with spur:openConversation costs no token, so a normal integration stays far below the limit. See Errors for every status code.