Pipeline, Circles, reminders and the contact timeline for your AI assistant
Spun has tools for a connected AI assistant covering your sales boards, Contact Circles, alarms, Keep In Touch list, quick replies, chat language settings and one history for each contact. This page says which work today, and lists every tool, the permission it needs, what the Free plan includes, and what each refusal means in plain words.
New to connecting an assistant? Start with Connect ChatGPT, Claude or another AI assistant to Spun.
At a glance
- The three access levels include these tools. Since 10 November 2026 every access level reads your boards, circles, alarms, Keep In Touch list and quick replies, and the two Assistant levels also change them. On a key you can still tick each permission by itself. See Permissions for these tools.
- None of these tools sends a message itself. They change your boards, circles and reminders. Your own stage rules can send when a contact enters a stage, so a move that would start a message needs the send permission as well. See When a stage move would start a message.
- Each area has its own permission. Reading and changing are separate, so a key can read a board without being able to move a card.
- Free plan rules are per tool. With the permission on the key, the Free plan reads all of this and manages Circles. Moving cards, setting alarms, changing Keep In Touch and changing chat language settings are on Starter and up.
- Deleting a circle always needs a person. The assistant can only ask, and an organization manager decides.
Permissions for these tools
A key only reaches the tools its permissions allow. A tool the key has no permission for is hidden from the assistant.
| Permission | Scope | What it lets the assistant do | In an access level |
|---|---|---|---|
| Read Pipeline | read_pipeline | See your boards, cards, stage history and board numbers | All three |
| Move Pipeline Stages | manage_pipeline | Move contacts between stages and undo a move. It cannot add, rename or archive stages | Assistant, no sends and Assistant with sends |
| Read Circles | read_circles | See your circles, their members and the circles a contact belongs to | All three |
| Manage Circles | manage_circles | Create and rename circles, add and remove members, and ask for a circle to be deleted | Assistant, no sends and Assistant with sends |
| Read Alarms | read_alarms | See reminders set on chats and labels | All three |
| Manage Alarms | manage_alarms | Set a reminder for your team and dismiss one that has fired | Assistant, no sends and Assistant with sends |
| Read Keep In Touch | read_keep_in_touch | See who has gone quiet past their cadence | All three |
| Manage Keep In Touch | manage_keep_in_touch | Put a contact on a cadence, or take them off it, using your existing labels | Assistant, no sends and Assistant with sends |
| Read Quick Replies | read_quick_replies | Read your saved replies. No permission lets an assistant change them | All three |
All nine are in the access levels. The five read permissions are in all three levels, and the four that change something are in Assistant, no sends and Assistant with sends. Create & Update Contacts, which a stage move needs when a chat has no saved contact yet, is in the two Assistant levels as well. Each permission is also on the list when you create or edit a key in Settings → AI Assistant (MCP) → Manage API keys. An app you connected earlier gains nothing by itself: until its key carries a permission, the tools that need it stay hidden from the assistant. An app that signed in with your Spun account before 10 November 2026 gets these permissions when an organization manager presses Review and update access under Connected AI apps and confirms; the review lists what would be added. The Free plan rules below apply at every access level.
Chat language settings and the contact timeline use permissions you may already have:
- Contact timeline: Read Contacts and Read Conversations, both in Read-only analyst.
- Chat language settings: Chat Status, which is in Assistant, no sends.
Free plan
On the Free plan, every successful tool call counts toward your 100 Connected AI calls a month, including circle changes. Usage and status checks, questions about Spun itself, and failed or refused calls do not count. At 100, reads stop until the reset; circle changes are not stopped by the 100, they have the limits in the table below. Of the changes on this page, Free can only make circle changes. The other Free limits are in the table below.
| Area | Free plan | Starter and up |
|---|---|---|
| Pipeline | Read every board, card, history and number | Also move and undo |
| Circles | Read and manage, up to 3 circles, 500 memberships in total and 100 changes in any 24 hours | Read and manage, without those three limits |
| Alarms | Read | Also set and dismiss |
| Keep In Touch | Read | Also set and clear |
| Quick replies | Read | Read |
| Chat language settings | Read | Also change |
| Contact timeline | Read, with messages from the last 7 days | Read, without the 7-day limit |
When a tool is on a paid plan, the assistant gets the refusal plan_required with a sentence such as "Moving contacts between pipeline stages from Connected AI is on the Starter plan and up." Nothing changes.
Two limits apply on every plan: a circle holds up to 200 members, and a contact can belong to up to 25 circles.
Pipeline
| Tool | What it does | Permission |
|---|---|---|
list_pipelines | Lists your boards and their stages, with how many cards sit in each | Read Pipeline |
get_pipeline_board | Shows the cards of a board, or of one stage | Read Pipeline |
get_contact_stage | Shows where one contact sits on every board | Read Pipeline |
list_stage_history | Lists stage moves, newest first, with who moved each card and when | Read Pipeline |
get_pipeline_metrics | Gives the numbers from the board's Metrics view, compared with the previous period | Read Pipeline |
move_stage | Moves one contact to a stage, or takes it off the board | Move Pipeline Stages |
bulk_move_stage | Moves up to 100 contacts to one stage, with a separate result for each | Move Pipeline Stages |
undo_stage_move | Puts a card back where it was, within 8 seconds of the move | Move Pipeline Stages |
A chat with no saved contact can be moved too. Spun saves the contact first, which needs the Create & Update Contacts permission as well.
When a stage move would start a message
A stage move sends nothing itself. Your own stage rules can: a stage can be set up to send a WhatsApp message or an email when a contact enters it, or to add a label that starts a coaching series. When a move would start one of these, the key also needs Propose Sends (mcp_send_message), which is in Assistant with sends. Without it the assistant gets missing_scope, the card stays where it was, and nothing is sent. With it, the move goes through and your stage rules run exactly as they do when a person moves the card in Spun, with the same quiet hours and limits.
In bulk_move_stage this rule covers the whole batch: when entering the stage would start a message, the whole call is refused and no card moves. Moves that people make in Spun are not affected by this rule.
| Refusal | What it means | What to do |
|---|---|---|
missing_scope | Entering this stage would start an automated message to the contact, and the key cannot send | Use Assistant with sends, add Propose Sends to the key, or have a person move the card in Spun |
stage_conflict | The card moved after the assistant last looked at it | Read the current stage and try again |
hierarchy_blocked | An automated move may not take the card out of the stage it is in | A person moves it on the board |
terminal_locked | The card is in Won or Lost | A person can move it out on the board |
unresolved_contact | The contact could not be found for this card | Check the contact, or search for it first |
cannot_create_contact | The chat has no contact, and the key may not create one | Add Create & Update Contacts to the key, or create the contact first |
label_not_in_pipeline | The stage belongs to a different board | Use a stage from this board |
lost_reason_required | This stage needs a reason | Move the card again with the reason |
stage_archived | The stage is archived | Choose an active stage |
undo_window_expired | More than 8 seconds have passed since the move | Move the card back with move_stage |
invalid_undo | The move cannot be undone: a contact merge wrote it, it is itself an undo, or it was already undone | Move the card with move_stage if needed |
not_eligible | The move is not allowed for this key, or an automation tried to take a card off the board | A person makes the change on the board |
feature_not_ready | Stage moves are not switched on for this workspace yet | Reading the boards still works |
Circles
| Tool | What it does | Permission |
|---|---|---|
list_circles | Lists your circles and how many members each holds | Read Circles |
get_circle | Shows one circle and its members, with their roles | Read Circles |
list_contact_circles | Lists the circles one contact belongs to | Read Circles |
create_circle | Creates an empty circle | Manage Circles |
update_circle | Renames a circle or changes its color or icon | Manage Circles |
add_circle_members | Adds up to 100 contacts in one call, with an optional role | Manage Circles |
set_circle_member_role | Sets or clears the role of one contact who is already a member. The role holds in that circle only | Manage Circles |
remove_circle_members | Takes up to 100 contacts out of a circle. The contacts themselves stay | Manage Circles |
delete_circle | Asks for a circle to be deleted | Manage Circles |
Deleting a circle needs a person. delete_circle deletes nothing itself. It files a request in Spun Tools → Automate → AI Sends, and an organization manager approves or rejects it. A circle with more than 20 members also needs the assistant to confirm the request first. Approval removes the circle and its memberships; the contacts and their chats stay.
Adding members. Contacts that fit are added even when others are refused. Each contact gets its own result:
| Result | What it means |
|---|---|
added | The contact is now a member |
already_member | The contact was already in the circle |
not_found | There is no such contact |
deleted | The contact was deleted |
circle_full | The circle already has 200 members |
contact_circle_limit | The contact is already in 25 circles |
org_membership_limit | The account reached 500 memberships on the Free plan |
When removing, each contact gets removed, or not_member if it was not in the circle.
| Refusal | What it means | What to do |
|---|---|---|
already_exists | Another circle has this name, whatever the letter case | Use the existing circle, or pick another name |
plan_limit_reached | On a circle change: the account reached a Free plan limit on circles, memberships, or changes in the last 24 hours. The same code also means the monthly calls are used up, see the last table on this page | Remove something, wait, or move to a paid plan |
confirm_required | The circle has more than 20 members | Ask again with confirmation |
not_eligible | The connection belongs to a person who sees only some chats. It can read what they see but cannot change circles or filter by them | A person with full access makes the change in Spun |
missing_scope | Filtering by circle needs Read Circles | Add Read Circles to the key, or leave the filter out |
feature_not_ready | Deleting through approval is not switched on for this workspace yet | Delete the circle in Spun |
Alarms
| Tool | What it does | Permission |
|---|---|---|
list_alarms | Lists shared reminders plus the signed-in person's private ones, soonest first | Read Alarms |
create_alarm | Sets a one-time reminder on a chat for the whole team. Asking again with the same chat, time and note while that reminder is still waiting returns the same reminder and adds no second one | Manage Alarms |
dismiss_alarm | Dismisses an alarm that has fired | Manage Alarms |
An alarm notifies your team. It sends nothing to the customer.
A connection that is limited to chosen labels or chats lists and dismisses only the alarms on chats inside its limit and the label alarms of labels inside it. An alarm that is on neither a chat nor a label is outside every limit; to such a connection it answers not_found.
| Refusal | What it means | What to do |
|---|---|---|
invalid_params | The alarm needs exactly one chat or contact, a note, and a time in the future | Fix the request |
not_found | There is no such chat or contact, or no fired alarm with this id. A pending or snoozed alarm cannot be dismissed | Wait until it fires, or check the id |
Keep In Touch
| Tool | What it does | Permission |
|---|---|---|
list_keep_in_touch | Lists contacts who have gone quiet past their cadence, plus every cadence you can assign | Read Keep In Touch |
set_keep_in_touch | Puts a contact on a cadence by giving them the label that carries it | Manage Keep In Touch |
clear_keep_in_touch | Takes a contact off Keep In Touch by removing their cadence labels. Other labels stay | Manage Keep In Touch |
A cadence comes from a label set up in Labels. The assistant never creates a label or changes a cadence. If the cadence label is one that starts a coaching series for the contacts who get it, setting it also needs Propose Sends, as with a stage move.
| Refusal | What it means | What to do |
|---|---|---|
missing_scope | The cadence label would start a coaching series for the contact, and the key cannot send | Use Assistant with sends, add Propose Sends to the key, or have a person set the label in Spun |
invalid_params | The label has no cadence | Pick a label that has one |
not_found | No label carries that number of days, or the contact or label does not exist | Set the cadence in Labels first |
conflict | Several labels share this cadence | Name the label to use |
use_move_stage | The label is a pipeline stage | Move the card with move_stage |
send_block_label_immutable | The label blocks sending, so the assistant cannot remove it | A person changes it in Spun |
ai_protected_label_immutable | The label is protected from AI changes | A person changes it in Spun |
Quick replies
| Tool | What it does | Permission |
|---|---|---|
list_quick_replies | Lists your active quick replies, with a short preview of each | Read Quick Replies |
get_quick_reply | Reads one quick reply in full | Read Quick Replies |
Quick replies are read-only here. You create and edit them in Spun. If an id does not match an active quick reply, the assistant gets not_found.
Chat language settings
| Tool | What it does | Permission |
|---|---|---|
get_chat_language_settings | Reads one chat's language and voice settings | Chat Status |
set_chat_language_settings | Changes one chat's language and voice settings. Only the settings named change | Chat Status |
Three settings belong to one person: translating your outgoing messages, the language you record in and the language you send voice in. They need an app connected with a Spun account, so a plain key reads them as empty and cannot change them. Organization-wide defaults stay in Settings. Changing these sends nothing to the customer.
| Refusal | What it means | What to do |
|---|---|---|
invalid_params | The language is not supported, no setting was given, or two settings that cannot go together were sent | Fix the request |
not_eligible | A personal setting needs a connected account, and this key has none | Connect the app with your Spun account |
not_found | There is no such chat | Check the chat |
provider_error | Some settings could not be saved. The answer lists what was saved and what was not | Try the unsaved settings again |
Contact timeline
| Tool | What it does | Permission |
|---|---|---|
get_contact_timeline | Shows one contact's history as one list, newest first: messages, stage moves, tasks, alarms, notes and identity events | Read Contacts and Read Conversations |
The assistant can filter by kind and by date, and read up to 200 entries a call. On the Free plan, messages go back 7 days and the answer says so; the other kinds are not limited. If the contact does not exist, the assistant gets not_found.
Refusals that can come from any of these tools
| Refusal | What it means | What to do |
|---|---|---|
missing_scope | The key does not have the permission for this tool | Add the permission to the key in Settings |
tool_not_enabled | The tool is outside the set of tools this key is limited to | Change the tools the key may use, or use a key that includes this tool |
tool_not_released | This connection does not include the tool | Use another tool for the job |
plan_required | The tool is on a paid plan | See Pricing |
plan_limit_reached | The monthly Connected AI calls are used up. The sentence with the refusal says what applies to the account | Wait for the date in that sentence, or choose a plan in Settings → Plan & Usage. During a trial, choosing a plan is the only way to continue |
trial_ended | The free trial ended with no plan and no card on file | An account admin picks a plan in Settings → Plan & Usage, or saves a card there to continue on the Free plan |
self_proxy_paused | The free trial ended and the account's Self Proxy is paused | An account admin picks a plan in Settings → Plan & Usage, or switches the line to a shared proxy there to continue on the Free plan |
org_mcp_disabled | AI connections are switched off for this organization, or the organization was not found | An organization admin turns them on in Settings → AI Assistant |
kill_switch_engaged | Spun has paused changes through AI connections, for the whole platform, this organization or this key. Reads keep working | Contact support. Nothing in Settings lifts this |
key_inactive | This key is switched off | An organization admin turns it back on in Settings → AI Assistant, or creates a new key there |
key_expired | This key has passed its expiry date | An organization admin creates a new key in Settings → AI Assistant |
quota_unavailable | Spun could not check the rate limits for this change just now, so it refused the change instead of risking going over | Wait a moment and try again. If it keeps happening, contact support |
invalid_params | Something in the request is missing or the wrong shape | Fix the request |
invalid_cursor | A page marker is out of date or does not belong to this list | Start the list again from the first page |
not_found | The item does not exist, or this key cannot see it | Check the id |
rate_limited | Too many calls in a short time | Wait a moment and try again |
internal_error | Something went wrong on the Spun side | Try again. If it keeps happening, contact support |