Connect ChatGPT, Claude or another AI assistant to Spun
Spun can be connected to the AI assistant you already use, such as ChatGPT or Claude, through MCP (Model Context Protocol). Once connected, you can ask that assistant about your WhatsApp conversations, groups, contacts and digests in its own chat window, and it reads the answers straight from your Spun workspace.
This page covers what the connection gives you, which key and permissions to pick, how group messages tell you who wrote them, and how the Connected AI read allowance, the grace period and the add-on work.
At a glance
- Start read-only. The Read-only analyst key preset lets the assistant read but never send.
- Group sender identity needs two permissions: Read Contacts and Read Groups. The read-only preset has both.
- Every inbound group message names its sender: the phone number, your contact name for that number, and whether WhatsApp hid the number.
- Hidden-number members are marked hidden and carry a stable key instead of a number, so the assistant can still group their messages.
- Photos and voice-note transcripts are a separate choice. The consent screen asks for them with their own box, and an organization manager can turn them off for the whole organization.
- Digests are cheap to read: reading a prepared digest answer is one read, however many messages it covers.
- Starter includes 2,000 Connected AI reads per billing period; Pro and Max include Connected AI. Reads never use AI credit. When Starter reaches its allowance, a one-time 7-day grace period applies before reads pause, or you can add Connected AI for $25 a month.
What MCP gives you
MCP is an open standard that lets an AI assistant use tools from another product. With Spun connected, the assistant can, for example:
- read the messages in a chat or a group and summarize them,
- look up contacts and labels,
- read the prepared answers of your chat digests,
- check its own permissions and your usage for the month.
The list of supported assistants, the server address and the step-by-step setup for each one are on spun.com/mcp. This guide explains what you see once you are connected.
Step 1: Choose the key and its permissions
An organization manager creates the key in Settings → AI Assistant (MCP). Assistants that sign in with your Spun account (for example a custom connector in Claude) ask for the organization and access level on a consent screen instead; the same permissions apply.
Pick a preset. The three presets are Read-only analyst, Assistant, no sends and Assistant with sends.
For analysis, choose Read-only analyst. It lets the assistant read conversations, contacts, labels, campaigns, groups, tasks and team members, and it cannot send anything.
Two permissions decide whether the assistant sees who wrote a group message:
- Read Contacts
- Read Groups
A key needs both. Read-only analyst already has both. A key without them still reads group messages, but without the sender fields described below. The AI Assistant (MCP) settings tab offers the presets only; to pick permissions one by one, create the key on the Webhooks page under Manage API Keys instead.
You can delete a key at any time from Settings → AI Assistant (MCP). An assistant using it loses access immediately.
Photos and voice-note transcripts
Media is not part of any access level. When an assistant signs in with your Spun account, the consent screen shows a separate box under the three levels: Also photos and voice-note transcripts. Whatever the assistant reads this way goes to the AI provider you are connecting.
- The box is ticked by default for Assistant, no sends and Assistant with sends, and not ticked for Read-only analyst.
- With Assistant with sends, ticking it also lets the assistant send files. Every send still follows your organization's approval settings.
- If the box cannot be ticked, either an organization manager has turned media off for the organization (the screen says so), or media is not available yet.
The organization switch. At the top of Settings → AI Assistant (MCP) → Connected AI apps, an organization manager chooses whether connected AI may view photos and voice-note transcripts: Default, On or Off. Default means on for organizations created from October 22, 2026 and off for older ones. Off stops every connected app from reading media, whatever it was granted; Weave inside Spun is not affected. The media relay switch sits beside it. Both are saved with Save AI Assistant settings at the bottom of the page.
Daily limits. Each connection can read up to 200 photos or transcripts a day, 50 MB a day in total, and the same message at most 5 times a day. Past a limit, media reads are refused until the next day.
Apps connected before media existed. Their card reads "version 1 (without media)" next to the access level, with a Review and update access button. The review lists what would be added and removed in plain words, and says so when the update lets the app send files; ticking the box and pressing Update access is the confirmation, there is nothing to type. If the app's access was narrowed by hand after it connected, the review explains that it cannot be updated in one step; choose an access level for it in the list, or disconnect it and connect it again to approve photos and voice-note transcripts. Apps connected later show whether photos and voice-note transcripts are included.
Who wrote each group message
When the assistant reads messages from a group, every inbound message carries four sender fields:
| Field | What it holds |
|---|---|
sender_phone | The sender's phone number with the country code, for example +972501234567. Empty (null) when WhatsApp hides the number, or when your organization's AI privacy level is set to keep phone numbers away from AI. |
sender_contact_name | The name of the matching contact in your Spun contacts, or null when the sender is not a contact. Only a contact name counts here, never the profile name the member set in WhatsApp. |
sender_hidden | true when WhatsApp hides this member's number, otherwise false. |
sender_key | Present only when sender_hidden is true: a stable key for that member, such as hm_3f9a1c07b2e84d61. |
The profile name the member set in WhatsApp is in the separate sender field, as before. Like message text, names are passed to the assistant marked as untrusted content, so the assistant treats them as data and never as instructions.
Here is one inbound group message from a hidden-number member, shortened:
{
"message_id": "884213",
"direction": "inbound",
"type": "text",
"body": { "source": "whatsapp_message", "trust": "untrusted_external_content", "text": "Room 12 is ready" },
"timestamp": "2026-10-14T06:42:10.000Z",
"sender": { "source": "contact_field", "trust": "untrusted_external_content", "text": "Dana" },
"sender_phone": null,
"sender_contact_name": null,
"sender_hidden": true,
"sender_key": "hm_3f9a1c07b2e84d61"
}Telling staff from customers. Save your team as contacts with a label such as "Employee" (the group chats guide shows how). The assistant can then match sender_contact_name or sender_phone against that label and split your team's messages from everyone else's.
Messages your own number sent, and older history imported without a sender, do not carry these fields.
Hidden-number members
WhatsApp can hide a group member's number from everyone in the group, you included. Spun keeps working when WhatsApp hides the number.
- No fake numbers, ever.
sender_phonestays empty for a hidden-number member; no number is filled in. - A stable key instead.
sender_keystays the same for the same member across every group and every report in your organization, so the assistant can count and group that member's messages. It is not a WhatsApp id, it cannot be turned back into one, and a different organization never gets the same key for the same person. - Counted, not dropped. Hidden-number members are counted and labelled in every report, never silently dropped.
Link once, and the name follows. When you know who a hidden-number member is, link them to a contact in Spun. If they have written to you directly, open that chat, find the Not identified yet card in its contact panel, and choose Link to a contact or Add as new. From then on sender_contact_name carries the contact's name for that member, past messages included.
An organization manager can also tell Weave who a hidden member is in plain words, for example: "The member shown as ~Layla in the Reservations Review group is Layla Haddad." Name both the member and a contact you already have. Weave shows a confirmation card with the link it is about to make, and nothing changes until you confirm it. Weave never links a member on its own guess and never creates a contact from a link, and you can undo the link from the contact panel.
Spun does not look up a hidden member's number. Nothing is looked up in bulk; Spun only keeps what WhatsApp sends with normal message traffic. More on this in Analyze Your WhatsApp Group Chats.
Reading digests over MCP
A chat digest keeps a standing question answered as messages arrive, for example "What is still open in the partner groups?". The assistant reads a digest's prepared answer with the get_chat_summary tool.
- One read, however many messages. Reading the prepared answer counts as one read, whether it covers ten messages or ten thousand. For a daily report across hundreds of groups, this is the cheapest way to get it into ChatGPT or Claude.
- Nothing is recomputed.
get_chat_summaryreturns the stored answer with its evidence and how fresh it is. It never starts new AI work. - Listing and setting up.
list_chat_summarieslists your digests. With a key that may change data, the assistant can also create or edit one withdefine_chat_summaryandupdate_chat_summary.
Keeping digests up to date has its own monthly allowance of messages analyzed, shown on the pricing page. When it is used up, automatic refreshes pause until the next month, and a refresh you start yourself still runs.
Connected AI read allowance
Connected AI reads are included in each plan for the organization:
| Plan | Connected AI reads |
|---|---|
| Starter | 2,000 per billing period |
| Pro | Included, no cap |
| Max | Included, no cap |
| Trial | 300 for the whole trial |
The allowance follows your plan's billing period and starts again when the plan renews. Reads never use your AI credit, on any plan. The trial has one allowance for its whole window and no grace period: once its 300 reads are used, reads pause until the trial ends or you choose a plan.
What counts. A read is one tool use by the assistant that reads your data. These never count:
- checking the key's permissions, the usage summary, the business overview and delivery status (these keep working even while reads are paused),
- a call that failed,
- calls that change data, such as sending a message or creating a task. Those follow their own rules.
When Starter reaches its allowance. The first time your organization reaches the allowance, reads keep working for a 7-day grace period. The grace period is granted once per organization, not once per billing period. Once it has been used, a billing period that reaches the allowance pauses reads at once: the assistant gets a plan_limit_reached answer that names the Connected AI add-on at $25 a month and the date reads start again. Checking permissions and usage keeps working during a pause. To continue right away, add Connected AI for $25 a month, or move to Pro or Max, in Settings → Plan & Usage.
Emails. Organization managers are emailed when the organization reaches its allowance, with the grace period and the add-on explained, and again two days before the grace period ends. These emails follow the budget alerts setting.
Where to see your usage
- Settings → AI Assistant (MCP). Under Show tool usage, the Connected AI line shows how many reads you have used this period and how many your plan includes.
- Settings → Plan & Usage. The plan comparison table shows each plan's Connected AI allowance next to its AI credit, and that is where the Connected AI add-on is added.
- Ask the assistant. The usage summary tool reports reads used, the allowance, the current state (
allowance,grace,paused,includedoraddon), when a grace period ends, and the date the allowance starts again.
Privacy
The assistant sees only what the key's permissions allow, and a read-only key never sends anything. Photos and voice-note transcripts reach the assistant only when they were allowed on the consent screen and the organization switch permits it. If your organization's AI privacy level keeps phone numbers away from AI, sender_phone stays empty for everyone and the contact name is still shown. Tell your staff that their group messages are analyzed, in line with your local data-protection rules.