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.
| Field | Required | Notes |
|---|---|---|
| user.email or user.id | Yes | The 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.number | One of these three | The 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.id | One of these three | A Spur contact ID, typically the contactId from an earlier response. |
| conversationId | One of these three | Open this conversation directly. It already identifies the WhatsApp number, so channelId isn’t needed. |
| channelId | With contact, if you have more than one WhatsApp number | Which of your numbers to open the contact on. Spur doesn’t guess: you can leave it out only when exactly one number is connected. |
| origin | Yes | The origin of the page that will show the frame, such as https://crm.acme.com. Must be on your allowed list. |
| codeChallenge | Yes | BASE64URL(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. |
| ttl | No | Token lifetime in seconds, 1 to 60. Default 60. This is the token’s life, not the session’s. |
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"
}'{
"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 field | Meaning |
|---|---|
| token | The single-use token. It’s already part of embedUrl. |
| embedUrl | Set this as the iframe src. Works once, within ttl, from origin, with the verifier. |
| expiresAt | When the token stops working (ISO 8601). |
| userId | The Spur user the frame acts as. Use it for assign. |
| contactId | The Spur contact. Store it on your record and mint with contact.id next time. |
| conversationId | The conversation the frame opens. |
| channelId | The WhatsApp number that conversation is on. |
| sessionTtl | Session 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.
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
}
]
}| Field | Meaning |
|---|---|
| conversationId | The conversation on this number, or null if the contact has none there yet (only with include=all). |
| channelId | Which of your WhatsApp numbers this is. |
| number | Your business number, never the contact’s. |
| name | The number’s display name. |
| conversationStatus | OPEN, CLOSED, or null when there’s no conversation yet. |
| lastMessageAt | Time of the last message, or null. |
| hasMessages | Whether 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.
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" }{
"conversationId": 49205067,
"assignedUserId": 318,
"aiAgentActive": false,
"conversationStatus": "OPEN"
}| Response field | Meaning |
|---|---|
| conversationId | The conversation (the ID the rest of the Spur API calls inboxId). |
| assignedUserId | The person assigned, or null. The rest of the API calls it assignedAgentId. |
| aiAgentActive | True when nobody is assigned and the number has an AI agent connected. |
| conversationStatus | OPEN 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. Someone opens a record: your backend calls assign with to: "user", then loads the frame.
- 2. They work the conversation in the frame.
- 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.