Hidden-number chat tools for your AI assistant
WhatsApp sometimes hides a person's phone number from Spun, so their chat arrives without one and sits in the Not identified yet group in Contacts. A connected AI assistant (ChatGPT, Claude or another MCP client) can help work out who these people are, and with the right permission it can link a chat to a contact, undo its own links, name a contact, and keep two records apart.
This page lists all ten tools, the permission each one needs, what the Free plan includes, the limits, and what each refusal means in plain words. Everything the assistant does shows up in the Links tab of Contacts, where your team can check it and undo it.
New to connecting an assistant? Start with Connect ChatGPT, Claude or another AI assistant to Spun.
At a glance
- Reading needs Read Contacts. Six tools only read. Two of them also need Read Conversations, because they look at messages.
- Changing needs its own permission. The four tools that change anything need Link Hidden-Number Chats to Contacts. It is never switched on by itself: you tick it on the key.
- A person always wins. A link a person made or confirmed, and a name a person typed, stay locked. The assistant cannot change them.
- When records hold data, a person decides. If linking would combine two records that both hold data, the assistant only suggests the link. A person decides it in the Links tab.
- Everything can be checked and undone. Every change lands in the Links tab with the key's name and the reason the assistant gave.
- Nothing is sent to anyone. These tools never message a customer and never ask WhatsApp for a number.
- All ten tools are on the Free plan.
The permission in Settings
An organization manager sets permissions on a key in Settings → AI Assistant (MCP), or approves them when an assistant signs in with a Spun account.
| Permission | Scope | What it lets the assistant do |
|---|---|---|
| Read Contacts | read_contacts | See a chat's identity, the likely matches, the list of changes and the decisions waiting for a person |
| Read Conversations & Messages | read_conversations | Together with Read Contacts: search messages to find a chat, and list the chats Spun could not identify |
| Link Hidden-Number Chats to Contacts | manage_identity | Link a chat to a contact, undo a link it made, name a contact that has no name yet, and keep two records apart |
Link Hidden-Number Chats to Contacts appears in the manage section of the key editor as "Link Hidden-Number Chats to Contacts (name, link, unlink, keep apart; links a person set stay locked)". In Hebrew it reads "קישור שיחות עם מספר מוסתר לאנשי קשר (שם, קישור, ביטול, הפרדה; קישורים שאדם קבע נשארים נעולים)".
What ticking it means:
- the assistant can link a hidden-number chat to a contact you already have, when the chat's own record is still empty,
- it can undo a link that an assistant or Spun made automatically, but never one a person made or confirmed,
- it can name a contact that still has a system label for a name, but never replace a name a person typed,
- it can keep a chat and a contact apart for 30 days, so nobody suggests that pair again for a while.
A key that was created with every permission (an older "all permissions" key) does not get this one. You add it on purpose, per key.
Free plan
All ten tools work on the Free plan once the key has the permissions.
- The six read tools count toward your monthly Connected AI calls like any other read.
- The four change tools do not count toward the monthly calls. They have their own hourly limits instead, see Limits.
Reading tools
| Tool | What it does | Permission |
|---|---|---|
get_chat_identity | Shows who a hidden-number chat belongs to: the linked contact if there is one, how sure Spun is, whether a person locked it, anything paused or waiting for a decision. A likely match here is a hint, not an answer | Read Contacts |
list_identity_candidates | Lists the contacts this chat could be. Likely matches come first, each with the evidence behind it (an entry in a lead game, the same person in a group, a phone number they wrote, their WhatsApp profile name), then recent contacts. With a search word it is a plain contact search | Read Contacts |
find_chat_by_message | Finds chats that contain an exact phrase (3 characters or more) from the last 6 months, grouped by contact, so a hidden chat can be matched to a known one | Read Contacts and Read Conversations |
list_unidentified_chats | Lists the chats Spun could not identify yet, and on request linked chats whose contact still has no name | Read Contacts and Read Conversations |
list_identity_changes | Lists recent links, undos, names and other identity changes, the same history the Links tab shows | Read Contacts |
list_identity_decisions | Lists the suggestions and conflicts waiting for a person. The assistant can read conflicts but cannot settle them | Read Contacts |
Changing tools
Each change asks for a short reason, 10 to 200 characters of plain text, which your team sees next to the change in the Links tab. The assistant should say what the evidence was. It must never put a password, key or other secret in the reason.
| Tool | What it does | Permission |
|---|---|---|
link_chat_to_contact | Links a hidden-number chat to a contact you already have, by contact or by phone number. The link is marked as made by this key, as probable, and can be undone. If the chat's own record already holds data, nothing is linked: a suggestion is recorded for a person to decide in the Links tab | Link Hidden-Number Chats to Contacts |
unlink_chat | Undoes a link that an assistant or Spun made automatically. A link a person made or confirmed cannot be undone this way. Undoing a link also stops suggestions for that pair for 30 days | Link Hidden-Number Chats to Contacts |
name_hidden_contact | Gives a name to the contact behind a hidden-number chat, when that contact still has only a system label. A WhatsApp profile name on its own is not a reason to name someone. The name shows a "named by" marker with the key's name until a person edits it | Link Hidden-Number Chats to Contacts |
keep_contacts_separate | Keeps a chat and a contact apart for 30 days, so no one suggests that pair again in that time. It is not an unlink | Link Hidden-Number Chats to Contacts |
A name that only looks like a contact's name is not evidence. The assistant should link only when it has something real, such as the same phone number or the same message.
If the assistant sends the exact same change again within 24 hours, nothing changes. It gets back the first answer and how things stand now, marked as a repeat.
Every answer also carries two links: one to the Links tab and one to the chat's identity card, so you can check the result yourself.
Limits
| Limit | Value |
|---|---|
| Changes per key | 50 attempts an hour, refused ones included |
| Changes per organization | 200 attempts an hour across all keys, refused ones included |
| Open suggestions per chat | 3 |
| Open suggestions per key | 20 |
When a limit is reached, the answer says how many seconds to wait.
Refusals
| Refusal | What it means | What to do |
|---|---|---|
link_locked | A person made or confirmed this chat's link, so the assistant cannot change or undo it | Leave it, or ask a person to change it in the Links tab |
name_locked | A person already named this contact, or the name is not a system label | Leave the name. A person can change it on the contact |
already_linked | The chat is already linked to another contact by an assistant or automatically | Undo that link with unlink_chat first, if the evidence says it is wrong |
contact_linked_elsewhere | The contact already holds another hidden-number chat. A contact holds only one | Undo the other link first, if the evidence says it is wrong |
needs_human_confirmation | Linking would combine two records that both hold data. A suggestion was recorded instead | A person decides it in the Links tab under Needs a decision |
already_proposed | The same suggestion is already waiting for a person | Wait for the decision |
proposal_cap | Too many suggestions are waiting: 3 for this chat, or 20 for this key | A person decides some of them in the Links tab first |
kept_separate | A person kept this chat and contact apart, or an undo paused the pair for 30 days | Do not suggest it again. A person can still link it by hand |
currently_linked | Keep apart was asked for a pair that is linked right now | Use unlink_chat first, if the evidence says the link is wrong |
ambiguous | More than one contact has that phone number | Choose the contact itself instead of the phone number |
not_found | The chat or the contact does not exist, or this key cannot see it | Check the chat and the contact |
stale_state | The link changed since the assistant last looked | Read the chat's identity again with get_chat_identity, then decide again |
identity_write_cap | This key made 50 change attempts in the last hour | Wait the number of seconds in the answer |
org_identity_write_cap | The organization made 200 change attempts in the last hour | Wait the number of seconds in the answer |
temporarily_unavailable | Spun could not check the limits just now, so it changed nothing | Try again in a moment |
missing_scope | The key does not have the permission for this tool | An organization manager adds it in Settings → AI Assistant (MCP) |
The general refusals that any tool can return (plan, allowance, key switched off and so on) are listed in Pipeline, Circles, reminders and the contact timeline for your AI assistant.
Weave does this too
Inside Spun, an organization manager can ask Weave to link, unlink or name a hidden-number chat in plain words. Weave always shows a confirmation card first and changes nothing until you confirm it, and the change is recorded as made by you through Weave. See Weave AI.