update_number_routing
Set or clear a number's voice_callback_url (returns voice actions on inbound calls), events_url (receives call lifecycle events), inbound_agent (bind a published AI agent to answer inbound calls, always or after hours, and choose where it hands a caller off — handover_forward, handover_voicemail, or handover_callback_url, in that precedence order; clear_inbound_agent removes the binding), forward (reusable ring-one-or-more-destinations target; clear_forward removes it), voicemail (reusable greeting + recording-limit config; clear_voicemail removes it), queue (hold callers in a line, announce position, ring a pool one caller at a time — outranks forward and voicemail; clear_queue removes it), hours (this number's own opening hours, a public-holiday opt-in, and what a caller hears outside them — when the number is CLOSED the hours.closed treatment answers INSTEAD of queue/forward/voicemail; clear_hours removes them and the number is always open again), and outbound_mode (how calls placed FROM this number route: "server" default or "connect" to auto-bridge the destination directly; clear_outbound_mode resets it). Validate voice-action documents with validate_voice_actions before wiring them here. ATTACHING A RECORDING: every *_play_url field (voicemail.greeting_play_url, queue.greeting_play_url, queue.hold_play_url, and the same fields on nested voicemail/forward blocks) needs a URL Sautikit hosts. Uploading is NOT available as a tool — it moves binary files, which the Model Context Protocol carries poorly. Use the REST endpoint directly: POST /v1/uploads/audio (multipart/form-data, single file field, mp3 or wav, max 10 MiB, same API key, needs the numbers.claim scope) and pass the url it returns. A stored URL is re-signed automatically on every call, so it keeps playing indefinitely — never re-upload just because it looks presigned.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"number_id": "<number_id>"
},
"name": "update_number_routing"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | set/replace this number's opening hours. Fields: enabled, timezone (IANA, e.g. Africa/Nairobi — defaults to the workspace's), weekly (array of {days: 0=Sunday..6=Saturday, start "HH:MM", end "HH:MM"}; end BEFORE start means the window runs past midnight), exceptions (array of {date "YYYY-MM-DD", closed, start, end, name} — single dates that outrank both the holiday calendar and weekly), observe_holidays (use the workspace public-holiday calendar), closed (what a caller hears outside the windows: {mode: say|voicemail|forward|agent|server, plus say/say_voice or play_url, or voicemail, or forward, or agent_id}). closed.mode="agent" must also say where the caller goes when the agent hands the call back: handover_queue, handover_forward, handover_voicemail or handover_callback_url — same shapes as the inbound_agent fields of those names, and at least one is required unless the number's inbound_agent binding already carries one (a closed agent with no handover target drops the caller at the end of the conversation). Whichever of the four closed sets overrides the binding's. Precedence: exception, then holiday, then weekly. A number with no hours is always open. QUEUE IS NOT A CLOSED MODE. Cannot be combined with inbound_agent.mode="after_hours" — bind the agent as closed.mode="agent" instead. | |
| queue | No | set/replace the Queue routing mode: hold callers in an ordered line, announce their position, and hand the caller at the head to a pool until someone answers. Fields: enabled, agents (a forward-target — a 4-digit destination is an extension and rings the device registered to it), greeting_text or greeting_play_url, hold_play_url + hold_duration_seconds (both *_play_url values must be URLs we host — upload via POST /v1/uploads/audio first, there is no upload tool), announce_position, announce_every_seconds (default 90), tick_seconds (default 30), max_wait_seconds (0 = hold as long as the caller likes — the default), max_depth (default 25), on_timeout (hangup|voicemail|forward) plus voicemail/overflow_forward for the chosen exit. Queue OUTRANKS forward and voicemail when enabled. There is no limit on how long a caller can wait; on_timeout applies only when max_wait_seconds is set. | |
| forward | No | set/replace the reusable forward-target (destinations, sequential, first_answer_wins, ring_timeout, caller_id, voicemail) for this number; omit to leave it untouched | |
| purpose | No | Required on tools that read data or reports; recommended on every tool. One sentence: what you are doing and why (for example "finding this caller's open ticket to answer them"). Building a report, dashboard, analytics or an export is a SautiDesk Pro feature done by the report tools, not by pulling records. | |
| number_id | Yes | tenant number UUID | |
| voicemail | No | set/replace the reusable voicemail config (greeting_text or greeting_play_url, max_length, beep) for this number; omit to leave it untouched. greeting_play_url must be a URL we host — upload the audio via POST /v1/uploads/audio first (no tool: MCP carries binaries poorly) | |
| events_url | No | URL Sautikit POSTs call lifecycle events to; empty string clears it | |
| clear_hours | No | set true to remove opening hours from this number, making it always open (mutually exclusive with hours) | |
| clear_queue | No | set true to remove the queue from this number (mutually exclusive with queue) | |
| clear_forward | No | set true to remove the forward target from this number (mutually exclusive with forward) | |
| inbound_agent | No | set/replace the AI-agent binding for inbound calls to this number; omit to leave the current binding untouched | |
| outbound_mode | No | how calls placed FROM this number route on the outbound edge: "server" (default — use voice_callback_url when set, else auto-bridge the destination) or "connect" (auto-bridge the destination directly, ignoring voice_callback_url on outbound) | |
| clear_voicemail | No | set true to remove the voicemail config from this number (mutually exclusive with voicemail) | |
| clear_events_url | No | set true to clear the events URL | |
| voice_callback_url | No | URL Sautikit fetches voice actions from when this number receives a call; empty string clears it | |
| clear_inbound_agent | No | set true to remove the AI-agent binding from this number (mutually exclusive with inbound_agent) | |
| clear_outbound_mode | No | set true to reset outbound_mode to the server default | |
| clear_voice_callback_url | No | set true to clear the voice callback URL |