Developer Portal
At a glance
| Location | Sidebar → Developer Portal (Code2 icon) |
| Plan | All plans, including the free tier |
| Related features | 2 |
Build and publish your own extensions for the Spun marketplace. Access API documentation and developer tools.
The contacts API accepts the same contact details as the contact card (company, job title, department, address, website, notes, extra phone numbers and emails, and custom fields); a value you send wins and one you omit is left alone.
Connected AI apps and access levels
API keys and Connected AI apps (claude.ai, ChatGPT or Gemini app connections signed in with Spun) are managed under Settings (the MCP server address is https://api.spun.com/api/mcp for every organization in every region (US, EU and any other): paste that one address into claude.ai, ChatGPT, Gemini or any MCP client, with keyless sign-in or an API key, and Spun routes each request to the organization's own region; never quote a regional address. An API key created before this routing existed shows a note in the API keys list (works at the regional address only after a region move; re-create to use api.spun.com)): connections can be disconnected at any time, and an org manager can enable or disable autonomous sending per connected app (typed confirmation; re-connecting from the AI app resets it).
The access level of an already-connected app can also be changed in place from the same panel, between Read-only analyst, Assistant (no sends) and Assistant with sends, without disconnecting and reconnecting: the change takes effect immediately for the app.
Raising an app to a send-capable level requires a typed confirmation because it grants more than was approved when the app was connected, the panel keeps showing which level was originally consented to, changing the level always turns autonomous sending back off, and lowering the level cancels any AI sends from that app that are still waiting for approval.
Consent page and media access
When an AI app connects by signing in with Spun, a consent page lets an organization manager pick the organization and access level; someone signed in with an account that manages no organization sees which email they are signed in with, so they can sign out and sign in with the address their Spun account uses.
If the sign-in returns to an app on the same computer (localhost, for example Claude Code), the page warns to allow it only when that app was just started from a source you trust, and if approving fails on the Spun side, nothing is connected and the page asks you to start connecting again from the AI app.
Someone who clicks Connect in an AI app without a Spun account is taken to the Spun sign-up page with a Connect heading: they create the account there (the free trial applies, no card needed), and after sign-up, including an email verification that opens in another tab, Spun brings them back to the consent page to finish; someone whose business already uses Spun should sign in with that account instead of creating a new one.
That sign-up page says that Spun links the business WhatsApp to the AI app, lists the three steps (create the account, link WhatsApp by scanning a code with the phone, then choose what the app may do), and says that after the trial the account can continue on Free MCP by saving a card, with nothing charged, Free MCP being only for a business using its own WhatsApp number.
If the chosen organization has no WhatsApp number linked yet, the consent page says so and offers Link WhatsApp first, which opens Spun in a new tab on that organization so the number can be linked; back on the consent page the line changes to WhatsApp linked without a reload.
Access can also be allowed without linking first, but the AI app cannot read chats until a number is linked. A connection request stays valid for 30 minutes; after that the page says the request has expired, and the fix is to go back to the AI app and click Connect again, which is one click when already signed in to Spun.
The consent page also offers photos and voice-note transcripts as a separate box under the access levels (ticked by default for the two Assistant levels, unticked for Read-only analyst; whatever the app reads goes to that AI provider), shown disabled with a hint when media access is off for the organization; apps connected before that box existed show version 1 (without media) and can be moved to the current version with Review and update access in Connected AI apps.
When photos and voice-note transcripts are off for the organization, Review and update access does not offer them: it says they are off, the update goes ahead without them, and an administrator can turn them on in Settings, Connected AI apps.
The three access levels also cover calendar events and alarms, reading at every level and creating and changing at the two Assistant levels; an app connected before they did keeps what it was approved for until a manager uses the same Review and update access.
Since 10 November 2026 the levels also cover the pipeline, Contact Circles, Keep In Touch, quick replies and contacts: reading at every level, and at the two Assistant levels moving pipeline stages, managing circles and Keep In Touch and creating and editing contacts, with the same review for apps connected earlier.
When a connected app is behind its access level and a review would turn on something that app can use, administrators see one line at the top of the inbox, for example "Claude can do more after an access review: read calendar, read alarms." (several apps are counted instead of named); Review access opens Connected AI apps with that app's review open, or scrolls to the first app waiting, and nothing changes until Update access is confirmed.
The X hides the line in that browser until a newer access level exists; it never shows above a WhatsApp connection problem or another warning, or while presenting, and a ChatGPT connection is counted only when the update opens a tool ChatGPT can use.
When Spun opens more tools for an organization's ChatGPT connection, administrators see a different line at the top of the inbox, for example "New in ChatGPT: Spun tools for photos, voice notes and more. Refresh the Spun connector in your ChatGPT settings to load them." ChatGPT keeps the tool list it loaded when it connected, so the new tools appear there only after the connector is refreshed in ChatGPT (or a new session is started); nothing needs to change in Spun, and the X hides the line in that browser until more tools open.
The AI app says the same: asked what it can do, or refused for a missing permission, it names what is available on its level but not turned on yet and that an administrator turns it on under Settings, AI Assistant (MCP), Connected AI apps, Review and update access.
ChatGPT connections with the box ticked get voice-note transcripts and the text of PDF and Word documents, as text only:
- ChatGPT gets the picture itself only for an organization Spun approved, when its administrator switches on Send the actual image to ChatGPT on the Media reading page (otherwise a photo answers that it was not read), and the file-sending tools are not available in ChatGPT
- A connection made before the box was ticked gets them after an administrator updates its access and the connector is refreshed in ChatGPT
- Claude connections have the picture and the sending tools too
While Spun has this switched off for ChatGPT, the consent page says so under the photos box ("ChatGPT cannot use photos, documents or voice-note transcripts through Spun yet. You can allow it now, and it starts working as soon as it becomes available."), the box stays available with its usual default, and Connected AI apps shows "Photos and voice notes: allowed, not available in ChatGPT yet".
For ChatGPT and other OpenAI apps (Codex, any OpenAI client), Spun can withhold ID, card and password numbers (passport, ID card, driving licence, residence permit, visa and tax numbers, card numbers, the machine-readable line of a passport, and passwords), because that is OpenAI's rule for apps in ChatGPT, not a law; Claude and other apps are not affected.
A marker such as [passport number withheld] takes the number's place, and ChatGPT can get an Open in Spun link to a Withheld from ChatGPT page that shows the item in full after signing in, valid for 24 hours, with Open in chat, Ask Weave about this chat and Report a wrong removal; the link never contains the number and opens only for someone with access to that chat.
An administrator can also open that page without the link: in Connected AI apps, each ChatGPT or other OpenAI connection has a Withheld in the last 24 hours button with the number of items, and the page it opens lists only items from chats that administrator can open, with Report a wrong removal and Back to settings.
The same items are also listed, for anyone signed in and only from chats they can open, in the Withheld from ChatGPT tab of AI Sends, which opens from the AI Sends button in the sidebar and as the AI Sends tab of the Spun Concierge, where the person who connected ChatGPT and administrators also see what ChatGPT asked when an item was withheld (see Media Reading).
The AI Sends icon in the sidebar also appears when there are such items and nothing waits for approval (it then opens on the Withheld from ChatGPT tab), with a small dot until the new items have been looked at.
On ChatGPT, photos from the chats an administrator chooses on the Media reading page (Settings, Media reading (MCP)) are read by another AI provider (listed at spun.com/privacy/subprocessors) and ChatGPT gets a description, not the image; numbers are withheld from descriptions too, and identity and medical documents are named, not described.
The row Send the actual image to ChatGPT (under Rules for ChatGPT on the Media reading page) is off and locked for every organization; Spun can open it for an organization after looking at its history, and Tell us you need this records a request.
Once Spun opened it, an administrator can switch it on after confirming a sentence that says every photo ChatGPT asks for in the chats of the organization is sent to ChatGPT as it is, identity documents and cards included, with no check by Spun, that any person whose ChatGPT is connected to the organization can ask for a photo, not only administrators, and that text is still filtered and chats excluded on the page are not sent.
Who switched it on, when, and the confirmed sentence are recorded; switching it off needs no confirmation, and the reading choices on the page stay as they are. If Spun withdraws the approval, no photo is sent and the row is locked again; if Spun opens it again, an administrator has to switch it on and confirm again.
For 90 days Spun keeps a note of which message had something withheld from ChatGPT and what kind of item it was, never the value; only Spun's staff can read it. This is turned on in steps: the consent page and the Connected AI apps card list only the parts in effect for that connection, and say nothing about them while they are off.
A stage move or a Keep In Touch label that would start an automated message to the contact also needs the Propose Sends permission, so Assistant, no sends is refused it (missing_scope) and nothing changes. The API keys list labels the two media permissions Send Media and Read Media & Transcripts.
Ask Claude or ChatGPT card
Before and right after WhatsApp is linked, an "Ask Claude or ChatGPT about your customers" card shows the same connection steps outside Settings: on the welcome page it comes first for someone who signed up from the MCP page or already has an API key or connected AI app, and otherwise sits under More; once the first chats have synced it appears as the fourth card under Here is what just arrived for org managers.
The card shows the server address with a Copy button, one line per sign-in client (claude.ai: Settings, Connectors, Add custom connector; ChatGPT: Settings, Connectors, Create; Gemini app: Settings & help, Connected Apps, Add a custom app), that signing in with Spun is for org managers only, that the trial includes 100 calls a month, and spun.com/mcp for every other client; a team member who is not an org manager sees the card without the address and is asked to have their org manager connect it.
There is one key panel, reached from two places: Settings, AI Assistant, Manage API keys (the AI Assistant tab itself only lists keys read-only with their status) and Tools, API & MCP Keys.
The panel puts Connect your AI first: that button opens the same guided setup as Settings, AI Assistant, and is the right path for Claude, ChatGPT or Cursor; New Key is the manual form for other tools.
The permission list in that form comes from the server and covers every permission a key can hold, including the newer ones (calendar, pipeline boards, contact circles, alarms, keep in touch, quick replies, status updates, WhatsApp channels, presence, catalog and orders, business profile, groups, forwarding, feedback to Spun), so a permission added to the MCP server appears in the editor automatically with the right warning level.
Each key card also carries its toolset selector (All tools, a Support, Sales or Reporting toolset, or custom bundles) for AI keys.
Photos and voice-note transcripts are offered in the manual form the same way as on the consent page: a Photos and voice-note transcripts box under the access cards, ticked by default for Assistant no sends and Assistant with sends (with sends it also lets the key send files), unticked for Read-only analyst, and greyed out with a note when media access is switched off for the organization in Settings, AI Assistant; the key the Connect your AI wizard creates follows the same default.
The manual form asks what the key is for with four cards (Read-only analyst, Assistant no sends, Assistant with sends, Legacy REST for Zapier), starts on Assistant no sends (a hand-built key never starts able to send or create bots), and keeps the individual permissions under Customize scopes, grouped into collapsible sections (AI read, AI manage, AI sends, scopes that need typed confirmation, Shared, Legacy REST) with Select all and Clear per section; Select all never ticks the two typed-confirmation scopes (Create & change bots, Autonomous send), each of which is confirmed by typing a word.
One key cannot hold the legacy Send Messages (REST) scope together with AI Assistant (MCP) scopes: ticking an MCP scope unticks legacy send with a notice, and legacy send is greyed out while MCP scopes are ticked, so anyone who needs both creates two keys, and if the two are still sent together the screen names the permissions that clash and what to change.
Only an administrator of the organization can connect an AI tool or create, change or delete keys: anyone else who opens the key list sees the keys without those controls and a line saying so.
An existing key's name and permissions can be edited in place from the pencil on its card, with the same cards and sections; the key value itself is shown once at creation and can never be shown again, but a lost key does not mean starting over: the circular-arrows button on the card (New key value) generates a fresh value for the same key, shown once, while the name, permissions, allowed IPs, toolset and any sends waiting for approval all stay; the previous value stops working immediately, so it must be replaced in the AI tool, and the card goes back to Waiting for the first call until the new value is used.
Deleting a key that was never called first asks whether the person only lost the value and points to New key value and Edit instead. Narrowing a key so it loses Propose Sends, Schedule Sends or Send Media cancels the sends it still had waiting for approval, and the form says so before saving.
Connected AI apps (sign-in connections) are edited in Connected AI apps, not from a key card.
A key card answers "is it working?" by itself: a live key nobody has called yet shows "Waiting for the first call from your AI" and the list refreshes quietly every few seconds while that panel is open (for up to 15 minutes), so the moment the AI makes its first call the card turns green with Connected: first call from ChatGPT (or Claude, Claude Code, Codex, Cursor, or a script or REST client for plain HTTP tools) and the time; afterwards it shows Last call: ChatGPT with the time, and a deactivated unused key shows Not used yet.
A Connected AI app card likewise says "waiting for the first call from the app" until its first call, then last used with the date.
IP allowlist for REST keys
REST API keys can be locked to an IP allowlist (single IPs or CIDR ranges, IPv4 and IPv6, set per key in Settings): requests from any other IP are rejected, and an empty list means the key works from anywhere. The allowlist applies only to REST keys - it does not apply to AI/MCP connections, whose traffic comes from shared AI-provider IPs.
A wrongly configured list never locks you out of managing keys, since Settings uses your Spun login rather than the key.
REST Actions API and OpenAPI document
The REST Actions API (/api/integrations, Bearer wap_ keys) covers text sends, media sends (image, video, audio, voice note, or document, from a URL or a base64 upload, with captions - POST /send-media with the send_message scope), contact and label management (apply-label refuses the Undelivered label, which only Spun adds, with 422 system_applied_label; remove-label can still take it off), phone checks, webhook subscriptions, and polling lists: GET /messages (read_messages scope) and GET /contacts (read_contacts scope) return cursor-paginated pages (since + limit, max 100 per page) so automation tools like n8n can poll for new activity.
Each listed message includes the other party's phone (peer_phone_e164), the group flag (is_group) and, for media messages, a signed download link (media_url) valid for 24 hours and fetchable without a Spun login, together with media_mime, media_filename, media_size and the caption; the link is null when Spun holds no copy of the file, and requesting the message again returns a fresh link.
Chats whose number WhatsApp hides behind a privacy ID work too: GET /messages lists them with peer_lid (the privacy ID digits, not a phone number) and identity_state (phone, lid_linked or lid_unlinked), and send-message accepts their @lid chat_id as to, so a helpdesk reply reaches the customer even when no phone number is known.
If the WhatsApp channel is offline, text sends are queued for delivery on reconnect, but media sends are not queued - the API returns a clear channel-offline error and the caller retries later.
If WhatsApp gives no answer in time, send-message and send-media answer send_outcome_unknown and nothing is queued or sent again, because the message may already have reached the recipient: check the conversation before sending it again.
Both send-message and send-media accept an optional idempotency_key: repeating a key whose first send succeeded (or, for send-message, was queued) returns the original answer with idempotent: true instead of sending again, and while the first attempt is still running or its outcome is unknown a repeat answers 409 send_outcome_unknown and sends nothing; a key whose first attempt was refused can send again.
While WhatsApp is paused because the free trial ended without a plan, send-message and send-media answer 402 with the code trial_ended_whatsapp and nothing is queued (a text already waiting in the offline queue is marked failed rather than sent later), and GET /messages returns every message dated after the trial ended as a locked stub (its id, chat, time, direction and type with locked: true, never its text or media) plus a notice field saying how many messages are locked; once a plan is picked, sending works again and the messages unlock.
The whole REST Actions API is also described by a public OpenAPI 3.1 document at https://api.spun.com/api/integrations/openapi.json, which needs no API key to read: it lists every endpoint, the scope each one requires, request and response shapes, the error codes, and the webhook delivery envelope with its HMAC-SHA256 signature scheme, so automation tools and developers can generate a client or import the API directly.
MCP toolsets, tools and read allowances
AI/MCP connections (API keys and Connected AI apps) can be limited to toolset bundles: an org manager picks All tools, a Support, Sales or Reporting toolset, or individual bundles (messaging reads, outbound sends, chat management, contact reads, contact writes, workspace, groups, status and newsletters, presence and profile, commerce, AI compute, analytics, digests) per key or per connected app in Settings, and the AI then only sees and can call the tools in those bundles; existing keys keep every tool until narrowed.
MCP tools can also create contacts and update contact details (a dedicated Create and Update Contacts scope; a duplicate phone number is reported instead of creating a second contact, and contact notes are append-only so the AI can never delete what a person wrote), create labels, read per-day message volume and response-rate statistics for a date range, and check their own remaining AI budget, rate-limit usage, toolset and Connected AI read allowance (get_usage_summary reports reads used this period, the plan's allowance, the state - allowance, grace, paused, included or addon - the grace end and the reset date).
Connected AI reads never use AI credit.
Starter includes 2,000 counted calls per billing period, Pro and Max include Connected AI with no cap, the trial includes 300, and Free MCP includes 100 a month (one counted call is one successful tool call, a read or a change; a message-list call returns up to 50 messages) with no grace period and no add-on: at its allowance a Free MCP organization gets plan_limit_reached naming Starter's 2,000 reads until the period resets; after a one-time 7-day grace period a Starter organization that reaches its allowance gets plan_limit_reached (naming the $25 a month Connected AI add-on and the reset date) on every counted read until the period resets or the add-on is added, while permissions, usage, business overview and delivery-status calls keep working.
Org managers can see which MCP tools each key calls and how often they fail (per-tool usage, last 7, 30 or 90 days) in Settings and in the admin MCP control page.
Closing and reopening conversations
Helpdesk and CRM tools can close and reopen conversations through the REST API: an API key holding the Close & Reopen Conversations scope (manage_conversations, ticked in the API key panel) can call POST /api/integrations/conversations/close and POST /api/integrations/conversations/reopen with the contact's phone (E.164) or the chat_id, an optional reason (up to 200 characters, stored on the webhook event) and an optional idempotency_key.
The response returns the chat_id and the new state; an unknown number answers 404, a conversation already in that state answers 409 with its current state (so a retry is safe), and the call answers 503 without changing anything if WhatsApp refuses the change. Closing fires conversation.closed and reopening fires conversation.reopened.
REST limits and group message fields
Limits and cost of the REST API: 60 requests per minute per API key across all endpoints (never quote another number), list endpoints return up to 100 rows per page with cursor pagination (GET /api/integrations/messages returns every stored message, direct and group, oldest first, within the plan's message history), and REST calls draw 1 AI token per 10 calls with no other fee; each outbound webhook delivery draws 1 AI token.
Group messages on the REST messages endpoint carry the group's id and subject, and when the API key also holds the read_contacts scope each inbound group message carries the member who wrote it, the same fields the MCP list_messages tool returns: sender_phone (E.164, null when WhatsApp hides the number or when the account AI privacy level is Full), sender_contact_name (the matching Spun contact's name, never the WhatsApp profile name; it is customer-authored text), sender_hidden (true when WhatsApp hides the number) and, for hidden senders, sender_key (a stable per-account id for grouping one member's messages, not a phone number).
A key without read_contacts gets none of these fields, there is no read_groups scope on the REST API, and outbound and direct-chat messages never carry them, nor does a group message whose sender Spun never recorded, such as imported history. A poller can therefore read up to 100 messages per page at up to 60 requests per minute per key.
Plan requirements for credentials
Plan requirement for credentials: REST API credentials (wap_ keys with integration scopes such as send_message, read_messages, read_contacts or manage_conversations) require the Pro or Max plan; on Starter the API key panel answers a plan-limit notice with an Upgrade path, and an existing REST key on a Starter plan answers 402 plan_limit_reached on every call.
Connected AI apps and MCP keys (claude.ai, ChatGPT, Gemini connections) are on every paid plan including Starter. Customers on a legacy plan from before the current lineup keep their REST API credentials working.
Any connected AI app can be limited by a manager to chosen labels and chats (the optional Limit to step on the consent screen, or Limit / Edit limit in the Connected AI apps list); chats outside the limit are invisible to that app and cannot be messaged, narrowing saves at once and widening needs a reconnect.
How to use
- Open Developer Portal from the sidebar.
- Create a new extension project.
- Follow the SDK documentation.
- Submit for review.
Related features
FAQ
- How do I build an extension?
- Where is the developer portal?
- Is there an API?
- Why does the API answer 402 trial_ended_whatsapp?
- Can I connect Claude or ChatGPT to Spun without having an account yet?
- The consent page says no WhatsApp number is linked, what do I do?
- Where do I see what was withheld from ChatGPT without the link?