Skip to main content
Saperly logo
  • Category: phone & sms
  • Auth: API_KEY
  • Composio-managed OAuth available? N/A
  • Tools: 30
  • Triggers: 0
  • Slug: SAPERLY
  • Version: 20261101_00

Tools

Slug: SAPERLY_ASSIGN_NUMBER_CONNECTIONAttach a connection (the AI persona / answering brain from SAPERLY_CREATE_CONNECTION) to a phone number, so inbound calls and SMS to that number — and outbound calls placed from it — are handled by that connection. A number without a bound connection cannot answer calls (and PLACE_CALL fails with 422 NumberHasNoConnection), so this is the wiring step that makes a number answerable. Get a connection id from SAPERLY_LIST_CONNECTIONS or create one with SAPERLY_CREATE_CONNECTION. Returns the updated number object. Free.

Input Parameters

string
required
The phone number’s id (a UUID) to bind, as returned by SAPERLY_LIST_NUMBERS or SAPERLY_GET_NUMBER.
string
required
The connection id (a UUID) to bind as this number’s answering brain. A connection is an agent persona / call handler that decides how inbound calls and SMS to this number are handled. Obtain one from SAPERLY_LIST_CONNECTIONS or create a new one with SAPERLY_CREATE_CONNECTION.
string
Optional idempotency key. Reusing the same key with an identical body safely replays the assignment instead of applying it twice.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_CREATE_CONNECTIONCreate a connection: the AI ‘brain’ that answers calls and (optionally) SMS on a Saperly phone number. A phone number binds to a connection via SAPERLY_ASSIGN_NUMBER_CONNECTION in order to answer calls. Only name is required. mode ‘hosted’ (default) = an in-network STT->LLM->TTS voice assistant driven by instructions (the system prompt), tts voice (voiceId from SAPERLY_LIST_VOICES), and language; mode ‘manual’ = your own webhook brain (set manualWebhookUrl). complianceEnabled defaults true — Saperly then speaks a TCPA disclosure as the first uninterruptible utterance, auto-filling a standard org-named disclosure if you leave it empty. Returns the created connection (201). Free. (The ‘backend’ field is intentionally not exposed: only ‘network’ works; ‘openai_realtime’ is server-rejected.)

Input Parameters

object
Model override for the hosted assistant.
object
The hosted assistant’s text-to-speech voice.
string ("hosted" | "manual")
How the line is handled. ‘hosted’ (default): an in-network voice assistant (STT -> LLM -> TTS) is the brain, driven by instructions, tts, and language. ‘manual’: your own webhook brain is the brain (set manualWebhookUrl).
string
required
Human-readable connection name (1-120 chars).
string
Spoken language as a BCP-47 tag (e.g. ‘en’, ‘es’, ‘en-US’), used as the transcription hint. See SAPERLY_LIST_LANGUAGES. Send ” to clear (auto-detect).
string
TCPA notice spoken first (uninterruptibly) when complianceEnabled is on. Leave empty to let Saperly auto-fill a standard org-named default.
array
MCP servers the hosted assistant may call as tools during a conversation. Hosted mode only.
object
Which call-control actions the connection’s brain may take.
string
System prompt defining the assistant’s behavior and opening line (there is no separate greeting field). Hosted mode.
boolean
Hosted-line opt-in to auto-answer inbound SMS with the model. Defaults off.
string
Optional idempotency key. Reusing the same key with an identical body safely replays the creation instead of creating a second connection.
string
HTTPS manual-mode webhook-brain URL where Saperly POSTs each turn. Only for mode=‘manual’.
boolean
When true (default), the do-not-message tool is exposed and disclosure is spoken first (an uninterruptible TCPA notice).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_DELETE_CONNECTIONPERMANENTLY AND IRREVERSIBLY delete a connection (the AI answering brain / persona that handles calls and SMS) by its id. THIS CANNOT BE UNDONE — there is no restore. WARNING: any phone number currently bound to this connection will immediately STOP handling inbound calls and SMS (it has no answering brain) until you bind another connection to it. Before deleting, call SAPERLY_LIST_NUMBERS to check which numbers reference this connectionId, and rebind them with SAPERLY_ASSIGN_NUMBER_CONNECTION first. Returns { status: ‘deleted’ }. Free, but destructive.

Input Parameters

string
required
The connection id (a UUID) to permanently delete, as returned by SAPERLY_LIST_CONNECTIONS or SAPERLY_CREATE_CONNECTION. IRREVERSIBLE: the connection is destroyed and cannot be recovered.
string
Optional idempotency key for safe retries. Reusing the same key replays the same result instead of failing on an already-deleted connection.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_END_CALLEnd an in-progress call by its id, hanging up and settling the metered cost. This is the safe, cheap, RECOMMENDED companion to SAPERLY_PLACE_CALL: placing a call starts per-minute billing, and this tool is how an agent stops that meter — call it as soon as you are done with the call. Ending is itself free (it ends spend rather than adding it). Returns the call object; durationSec and costCents may still be NULL if the call has not settled yet (null does NOT mean free — poll SAPERLY_GET_CALL afterwards for the final cost and duration). Only meaningful while a call is live; ending an already-ended call is a best-effort no-op.

Input Parameters

string
required
The call id (a UUID) to end, as returned by SAPERLY_PLACE_CALL or SAPERLY_LIST_CALLS. Ending an in-progress call hangs it up and stops the per-minute billing.
string
Optional idempotency key for safe retries. Reusing the same key replays the original end request rather than issuing a second one.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_GET_CALLFetch a single call by its id, returning its status, per-minute rate, final duration (durationSec) and cost (costCents), and the hasRecording / hasTranscript flags. costCents and durationSec are NULL until the call settles (in progress / not yet billed) — null does NOT mean free, so this is the tool to poll after SAPERLY_PLACE_CALL to learn a call’s final cost and duration. Check hasRecording / hasTranscript before calling SAPERLY_GET_CALL_RECORDING / SAPERLY_GET_CALL_TRANSCRIPT: those artefact endpoints 404 until the call has ended and been processed, and a 404 there means ‘no artefact yet’, not ‘no such call’. Free, read-only.

Input Parameters

string
required
The call id (a UUID) to fetch, as returned by SAPERLY_PLACE_CALL or SAPERLY_LIST_CALLS.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_GET_CALL_RECORDINGGet the audio recording for a call and return it as a downloadable file. The API answers with a 302 redirect to a signed download URL when a recording exists; the recording is fetched and returned as a file reference (under content). A recording exists only if the call’s connection had recordingEnabled=true AND the call actually connected and completed — so for many calls there is simply no recording. The endpoint uses the same 404 response for an unknown call and a call without an artifact, so verify the id and check SAPERLY_GET_CALL.hasRecording=true before calling this. Free, read-only.

Input Parameters

string
required
The call id (a UUID) whose audio recording to fetch, as returned by SAPERLY_PLACE_CALL or SAPERLY_LIST_CALLS. Call SAPERLY_GET_CALL first and ensure hasRecording=true — this endpoint returns 404 (meaning ‘no recording available’), not an error, when the call has no recording.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_GET_CALL_TRANSCRIPTFetch the transcript (conversation turns/segments) of a completed call by its id. Transcripts only exist AFTER a call connects, ends, and is processed. The endpoint uses the same 404 for an unknown call and a valid call whose transcript is not ready. Before calling this, poll SAPERLY_GET_CALL until the call has settled (durationSec / costCents are non-null) and hasTranscript is true. The returned payload is exposed under a ‘transcript’ key with call metadata and ordered role/text/timestamp turns. Free, read-only.

Input Parameters

string
required
The call id (a UUID) whose transcript to fetch, as returned by SAPERLY_PLACE_CALL or SAPERLY_LIST_CALLS. Call SAPERLY_GET_CALL first and ensure hasTranscript=true — this endpoint 404s until the call has ended and been processed.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_GET_CONNECTIONFetch a single connection (the AI answering brain / persona that handles calls and SMS) by its id, returning its full config: name, mode, backend, instructions, tts voice, language, compliance/disclosure settings, recordingEnabled, and manual webhook URL. Sensitive signing secrets are redacted. Use after SAPERLY_LIST_CONNECTIONS to inspect one connection. Free, read-only.

Input Parameters

string
required
The connection id (a UUID) to fetch, as returned by SAPERLY_LIST_CONNECTIONS or SAPERLY_CREATE_CONNECTION.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_GET_NUMBERFetch a single phone number by its id, returning its E.164 phoneNumber, bound connectionId, webhookUrl, country, numberType, pricing and lifecycle fields. Use after SAPERLY_LIST_NUMBERS to inspect one number’s current configuration. Free, read-only.

Input Parameters

string
required
The phone number id (a UUID) to fetch, as returned by SAPERLY_LIST_NUMBERS.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_GET_USAGEReturn the workspace usage summary and prepaid balance: calls {count, totalCostCents, totalDurationSec}, messages {count}, and balanceCents (the prepaid balance, in cents). ALWAYS call this before any paid action to check balanceCents: SAPERLY_PROVISION_NUMBER (~$2/mo), SAPERLY_SEND_SMS (~2c/segment) and SAPERLY_PLACE_CALL (~26c/min) all draw down this single balance, and a depleted (0) balance causes them to fail. This is also the best whoami / key check: a 200 confirms the connected key is valid and which workspace it maps to (prefer it over /health for that). Pass the optional ‘since’ (ISO-8601) to scope the usage window. Free, read-only, no pagination.

Input Parameters

string
Optional ISO-8601 timestamp lower bound (e.g. ‘2026-07-01T00:00:00Z’). Only usage at or after this instant is counted; omit for all-time totals. Does not affect balanceCents (always the current balance).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_LIST_CALLSList voice calls in the connected Saperly workspace, including status, rates, duration, cost and recording and transcript flags. Results are returned under the calls key; this tool exposes no filters or pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_LIST_CONNECTIONSList connections in the connected Saperly workspace, including their configuration and recording settings. Results are returned under the connections key; this tool exposes no pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_LIST_LANGUAGESList spoken languages supported for voice connections as code and name pairs. Results are returned under the languages key; this tool exposes no pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_LIST_MESSAGESList inbound and outbound SMS messages in the connected Saperly workspace, optionally filtered by phone number ID. Results are returned under the messages key; this tool exposes no pagination.

Input Parameters

string
Optional filter: return only messages on this phone number id (a UUID, as returned by SAPERLY_LIST_NUMBERS). Omit to return every message in the workspace. This is the ONLY filter the API supports.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_LIST_NUMBERSList phone numbers in the connected Saperly workspace, including their IDs, connection, webhook, pricing and lifecycle details. Returns the numbers in a numbers array; read-only with no pagination.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_LIST_VOICESList text-to-speech voices available for Saperly connections, optionally filtered by language prefix or family. Returns a voices array containing IDs, names, genders and languages; voice IDs can be used for connection TTS settings.

Input Parameters

string
Optional language filter. PREFIX / family match, NOT exact: ‘fr’ returns both ‘fr’ and ‘fr-CA’; ‘en’ returns ‘en’, ‘en-US’, ‘en-GB’, etc. Strongly recommended — the unfiltered list is ~751 voices. Uses the broader voice tag set (regional variants like en-US, fr-CA), which is wider than SAPERLY_LIST_LANGUAGES’ base codes; get base codes there.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_PLACE_CALLPAID / METERED — places a REAL outbound voice call that RINGS A REAL PHONE and BILLS PER MINUTE (~26¢/min); it keeps billing until hung up — end it with SAPERLY_END_CALL to stop the meter. Calls FROM a Saperly number (fromNumberId from SAPERLY_LIST_NUMBERS) TO an E.164 destination (to, e.g. +14155550123). The connection bound to the originating number answers; a number with NO bound connection cannot hold a conversation (bind one with SAPERLY_ASSIGN_NUMBER_CONNECTION). Optionally override the brain for this call with connectionId and/or a per-call instructions prompt. CONSENT GATE (TCPA): the destination MUST have active consent — call SAPERLY_RECORD_CONSENT first and SAPERLY_CHECK_CONSENT to verify, or it is rejected (403). Returns the call (201) with id + status; durationSec/costCents are NULL until the call settles (ends) — null does NOT mean it was free. Pass idempotency_key on retries to avoid double-dialing. May fail 402 (funds) or 422 (no connection).

Input Parameters

string
required
Destination phone number to dial, in E.164 format (e.g. +14155550123). The destination MUST have an active consent record (TCPA gate): record it first with SAPERLY_RECORD_CONSENT and confirm with SAPERLY_CHECK_CONSENT, or the call is rejected (403 RecipientOptedOut).
string
Optional connection id (a UUID) to use as the answering brain for THIS call, overriding the connection bound to the originating number. Omit to use the number’s bound connection. Get one from SAPERLY_LIST_CONNECTIONS.
string
required
Id (a UUID) of the Saperly number to place the call FROM, as returned by SAPERLY_LIST_NUMBERS. This number MUST have a bound connection (the answering brain) or the call cannot hold a conversation — bind one first with SAPERLY_ASSIGN_NUMBER_CONNECTION.
string
Optional per-call system prompt that overrides the connection’s saved instructions for this call only. Omit to use the connection’s defaults.
string
Optional idempotency key. STRONGLY recommended on retries: reusing the same key with an identical body safely replays the original call instead of placing (and billing) a second one.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_PROVISION_NUMBERPAID / METERED: provision (buy) a new phone number in a country. This SPENDS MONEY — it charges the workspace prepaid balance an upfront fee plus a RECURRING MONTHLY rent (US local ~ $1.79/mo, varies by country/type). Before calling this: (1) call SAPERLY_QUOTE_NUMBER_PRICE to get the live price and pass it as expectedMonthlyPriceCents / expectedUpfrontPriceCents to guard against price drift (a higher live price fails with 409 PriceChanged unless approveHigherPrice=true); (2) confirm sufficient funds by checking balanceCents via SAPERLY_GET_USAGE. Defaults country=‘US’, numberType=‘local’. Pass an idempotency_key to avoid double-provisioning on retry. Fails 402 (InsufficientFunds / PaymentMethodRequired), 403 (CountryNotAvailable), 404 (NoNumbersAvailable), 409 (NumberQuotaExceeded / PriceChanged).

Input Parameters

string
ISO 3166-1 alpha-2 country code to provision a number in (e.g. US, GB). Defaults to US.
string
Preferred area code / city prefix to search within the country (e.g. 415). Omit to take any available number.
string ("local" | "toll_free" | "mobile" | "national")
Kind of number to provision: one of ‘local’, ‘toll_free’, ‘mobile’, ‘national’. Defaults to ‘local’.
string
Optional idempotency key. The same key plus the same body replays the same result instead of provisioning again — pass it on retries to prevent double-charging.
boolean
Set true to accept a live order price higher than the expected* values you quoted, instead of failing with 409 PriceChanged.
integer
The monthly price (in cents) you expect, taken from SAPERLY_QUOTE_NUMBER_PRICE. If the live order price exceeds it, provision fails with 409 PriceChanged instead of charging — resubmit with approveHigherPrice=true to accept the higher price.
integer
The one-time upfront price (in cents) you expect, from SAPERLY_QUOTE_NUMBER_PRICE. Same PriceChanged guard as expectedMonthlyPriceCents.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_QUOTE_NUMBER_PRICEREAD-ONLY and FREE: quote the price to provision a phone number in a country/type, returning { customerMonthlyCents, customerUpfrontCents }. This DOES NOT provision, reserve, or charge anything — despite the name it has NO side effects. This is exactly the tool to call BEFORE the expensive SAPERLY_PROVISION_NUMBER (which spends ~$2/mo): (1) use it to size the cost and feed customerMonthlyCents / customerUpfrontCents straight into SAPERLY_PROVISION_NUMBER’s expectedMonthlyPriceCents / expectedUpfrontPriceCents price-drift guards (the safe provisioning pattern); (2) compare against balanceCents from SAPERLY_GET_USAGE to confirm sufficient funds. Both country and numberType are required. Live-verified: US/local quoted 179 cents monthly and 179 cents upfront.

Input Parameters

string
required
Required ISO 3166-1 alpha-2 country code to price a number in (e.g. US, GB). Mirrors SAPERLY_PROVISION_NUMBER’s country input.
string ("local" | "toll_free" | "mobile" | "national")
required
Required kind of number to price: one of ‘local’, ‘toll_free’, ‘mobile’, ‘national’. Mirrors SAPERLY_PROVISION_NUMBER’s numberType input.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_RELEASE_NUMBERPERMANENTLY AND IRREVERSIBLY release a phone number back to the carrier. THIS CANNOT BE UNDONE: the number leaves the workspace, is returned to the carrier pool, and CANNOT be recovered or reclaimed. Inbound calls and SMS to it STOP IMMEDIATELY, and its monthly rent stops (releasedAt is set). Only call this to permanently decommission a number you are certain you no longer want — there is no undo. Free, but destructive.

Input Parameters

string
required
The phone number id (a UUID) to release, as returned by SAPERLY_LIST_NUMBERS. IRREVERSIBLE: this number is returned to the carrier pool and cannot be reclaimed.
string
Optional idempotency key for safe retries. Reusing the same key replays the same result instead of releasing twice.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_SEND_SMSPAID / METERED: send a single SMS from one of your Saperly numbers to an E.164 destination. This SPENDS REAL MONEY and sends a REAL text message to a REAL phone (~2 cents per 160-character segment; a long body is split into multiple segments, each billed). TCPA CONSENT GATE (required): the API refuses to send unless the recipient has an active consent record (or messaged you within the last 24h). For cold outbound you MUST first call SAPERLY_RECORD_CONSENT for the destination, and you can verify it with SAPERLY_CHECK_CONSENT — otherwise this fails with 403 RecipientOptedOut / compliance. Before sending, confirm sufficient funds via SAPERLY_GET_USAGE (balanceCents). Pass idempotency_key to prevent a double-send on retry. Returns 201 with the queued message (id, status, segments). NOTE the response echoes the sending number as ‘numberId’ and ‘from_number’ (not ‘fromNumberId’). Fails 402 (InsufficientFunds / SpendLimitExceeded), 400 (DestinationNotSupported / invalid request).

Input Parameters

string
required
Recipient phone number in E.164 format (leading ’+’, full international number), e.g. +14155550123.
string
required
The message text (1-1600 characters). Long messages are split into multiple 160-character segments and BILLED PER SEGMENT (~2c each).
string
required
Id of the Saperly number to send FROM (from SAPERLY_LIST_NUMBERS). Must be a number owned by the connected workspace and within the key’s number allow-list. NOTE: the API echoes this back as ‘numberId’ in the response.
string
Optional idempotency key. The same key plus the same body replays the same result instead of sending again — pass it on retries to prevent double-sending and double-charging.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_SET_NUMBER_CALLER_IDSet the outbound caller ID name / CNAM (1-15 characters: letters, digits, spaces) presented to recipients on outbound calls from a Saperly phone number, or pass callerIdName=null to CLEAR it. callerIdName is required — supply a name to set it, or null to unset it. Returns the updated number object. Note: CNAM display depends on the destination carrier and does not propagate instantly, so recipients may not see the change immediately. Free.

Input Parameters

string
required
The phone number’s id (a UUID) whose outbound caller ID name to set, as returned by SAPERLY_LIST_NUMBERS or SAPERLY_GET_NUMBER.
string
required
The outbound caller ID name (CNAM) to display to call recipients — 1-15 characters, letters/digits/spaces only. Pass null to CLEAR a previously set caller ID. This field is required: supply a name to set it, or null to unset it. Note: CNAM propagation is carrier-dependent and not instantaneous, so recipients may not see the change immediately.
string
Optional idempotency key for safe retries. Reusing the same key with an identical body replays the original result; reusing it with a different body is rejected (422).

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_SET_NUMBER_SMS_SENDERSet the alphanumeric SMS sender id (1-11 alphanumeric chars, e.g. a brand name) shown as the ‘from’ on outbound SMS from this number, or pass smsSenderId=null to CLEAR it. Returns the updated number object. NOTE: sender-id support and display vary by destination country/carrier (the US and Canada notably restrict alphanumeric sender ids). Free.

Input Parameters

string
required
The phone number id (a UUID) whose SMS sender id to set, as returned by SAPERLY_LIST_NUMBERS.
string
required
The alphanumeric SMS sender id (1-11 alphanumeric characters, e.g. a brand name like ‘ACME’) shown as the ‘from’ on outbound SMS from this number. Pass null to CLEAR the sender id and fall back to the numeric caller. This is a required key — provide a string to set it or null to unset it. Note: alphanumeric sender ids are not supported by every destination country/carrier (the US and Canada notably restrict them and may ignore or reject the value); support and display vary by destination.
string
Optional idempotency key for safe retries. Reusing the same key with an identical body replays the original result; reusing it with a different body is rejected.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_SET_NUMBER_WEBHOOKSet the HTTPS webhook URL that Saperly POSTs this number’s events (inbound SMS/calls, status) to. The url is required and must be https://. Returns the updated number object. NOTE: this endpoint has no way to clear the URL back to null — once set it can only be changed to another URL, so set it deliberately. Free.

Input Parameters

string
required
The phone number id (a UUID) whose event webhook to set, as returned by SAPERLY_LIST_NUMBERS.
string
required
The HTTPS webhook URL that Saperly will POST this number’s events (inbound SMS/calls, status updates) to. Must start with ‘https://’. Note: this endpoint has no way to clear the URL back to null once set — it can only be changed to another URL, so set it deliberately.
string
Optional idempotency key for safe retries. Reusing the same key with an identical body replays the original result; reusing it with a different body is rejected.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_TRANSFER_CALLPAID / METERED — BLIND-transfers a LIVE, in-progress voice call to another destination to (an E.164 number like +15551230000, or a sip: URI). BLIND means the call is handed off UNCONDITIONALLY: there is NO confirmation from the transferee and the AI agent LOSES CONTROL of the call once transferred — treat it as a one-way, irrecoverable handoff. Only meaningful on a call that is actually connected/in-progress (identify it via SAPERLY_PLACE_CALL or SAPERLY_LIST_CALLS). The transferred leg KEEPS BILLING per minute, so this is not free — the meter runs on the new leg until the call ends. Returns the call object with its updated status; durationSec / costCents stay NULL until the call settles (null does NOT mean it was free). Pass idempotency_key on retries to avoid starting a second transfer leg. Fails 502 CallStartFailed if the transfer leg cannot be started, and 404 if the call id is unknown.

Input Parameters

string
required
The id (a UUID) of the LIVE, in-progress call to blind-transfer, as returned by SAPERLY_PLACE_CALL or SAPERLY_LIST_CALLS. The call must be currently connected/in-progress for a transfer to be meaningful.
string
required
Where to blind-transfer the live leg — an E.164 phone number (e.g. +15551230000) OR a sip: URI (e.g. sip:agent@example.com). The call is handed off UNCONDITIONALLY with no confirmation from this destination, and the AI agent loses control of the call once transferred.
string
Optional idempotency key. STRONGLY recommended on retries: reusing the same key with an identical body safely replays the original transfer instead of starting (and billing) a second transfer leg.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: SAPERLY_UPDATE_CONNECTIONPartially update a connection (the AI answering brain bound to a number). Send only the fields you want to change (name, mode, instructions, llm, tts, language, mcpServers, callControl, complianceEnabled, smsAutoReply, disclosure, manualWebhookUrl); every unset field is left untouched. Send mcpServers=[] to clear all tools, or manualWebhookUrl="" to clear it. Writing RE-SYNCS the carrier, so an update has side effects beyond the stored record. Returns 200 with the full updated connection. Free.

Input Parameters

string
required
The connection id (uuid) to update.
object
New model override for the hosted assistant. Omit to keep the managed default. Hosted mode only.
object
New TTS voice for the hosted assistant. Hosted mode only.
string ("hosted" | "manual")
Change handling mode. ‘hosted’: an in-network voice assistant is the brain. ‘manual’: your own LLM is the brain.
string
New name (1–120 chars).
string
New spoken language BCP-47 tag.
string
New TCPA notice spoken first, uninterruptibly, when compliance is on.
array
MCP tool servers the assistant may call. Send [] to clear all tools.
object
Which call-control actions the brain may take (end call, DTMF, transfer). Omitted sub-fields fall back to defaults.
string
New system prompt that defines the hosted assistant’s behavior.
boolean
Hosted-line opt-in to auto-answer inbound SMS with the model. Default off.
string
Optional idempotency key. The same key + an identical body replays the same result; the same key + a different body is 422-rejected.
string
HTTPS manual-mode webhook-brain URL. Only meaningful for manual mode; send "" to clear it.
boolean
Toggle the do-not-message tool + the TCPA disclosure opener.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not