Saperly

Attach 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 NumberHasNoConnec…

Untrusted display-only summary

Check whether a contact currently has active TCPA consent for one of your Saperly numbers, given numberId (your number) and peerNumber (the contact's E.164 number) as query params. Returns {hasConsent: boolean} and, when hasConsent is true, {type: ' '} (the 'type' key is ABSENT when hasConsent is false). Saperly REFUS…

Untrusted display-only summary

Create 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 `instructio…

Untrusted display-only summary

PERMANENTLY 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…

Untrusted display-only summary

End 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 spe…

Untrusted display-only summary

Fetch 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 SAPE…

Untrusted display-only summary

Get 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…

Untrusted display-only summary

Fetch 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 settle…

Untrusted display-only summary

Fetch 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_…

Untrusted display-only summary

Fetch 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.

Untrusted display-only summary

Return 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…

Untrusted display-only summary

Return the full voice-call history (inbound + outbound) for the connected Saperly workspace. Each call carries its id, numberId, direction, to and from_number (E.164), status, rateCentsPerMin, durationSec, costCents, hasRecording and hasTranscript. Note: durationSec and costCents are null until the call settles (null…

Untrusted display-only summary

Return every connection (the AI persona / answering 'brain' that handles calls and SMS) in the connected Saperly workspace. Each carries id, name, mode (hosted|manual), backend, instructions, llm, tts voice, language, mcpServers, callControl, complianceEnabled, smsAutoReply, disclosure and recordingEnabled. Use this t…

Untrusted display-only summary

Return every TCPA consent record in the connected Saperly workspace, with each record's id, numberId (the Saperly number contact is authorized FROM), peerNumber (the contact's E.164 number), consentType (explicit_outbound or implied_inbound), source, grantedAt and revokedAt. Consent is Saperly's compliance gate: outbo…

Untrusted display-only summary

Return the spoken languages Saperly supports for voice connections, each as a {code, name} pair (about 42 entries, e.g. {'code':'en','name':'English'}). A language `code` is what you pass as a connection's `language` field, and as the `language` filter to SAPERLY_LIST_VOICES (that filter does a PREFIX match, so 'fr' a…

Untrusted display-only summary

Return SMS messages in the connected Saperly workspace (both inbound and outbound). Each message has id, numberId, direction, to, from_number, body, segments, status and createdAt. Pass `numberId` to filter to a single phone number's messages; `numberId` is the ONLY filter available. With no filter this returns the FU…

Untrusted display-only summary

Return every phone number provisioned in the connected Saperly workspace, with each number's id, phoneNumber (E.164), the connectionId (answering brain) bound to it, webhookUrl, country, numberType, monthlyPriceCents and lifecycle timestamps. Use this to discover a number's id before sending SMS, placing a call, or co…

Untrusted display-only summary

List the text-to-speech voices available for Saperly connections. Each voice has an id, name, gender and language; a voice id is what you pass as tts.voiceId when creating or updating a connection (SAPERLY_CREATE_CONNECTION / SAPERLY_UPDATE_CONNECTION). ALWAYS pass `language` to filter — the unfiltered list is ~751 vo…

Untrusted display-only summary

PAID / 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 conn…

Untrusted display-only summary

PAID / 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 expecte…

Untrusted display-only summary

READ-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 (wh…

Untrusted display-only summary

Record TCPA consent for a contact so outbound SMS (SAPERLY_SEND_SMS) and calls (SAPERLY_PLACE_CALL) from your number are permitted. Saperly's compliance gate: for a cold contact call this BEFORE sending; confirm with SAPERLY_CHECK_CONSENT, revoke with SAPERLY_REVOKE_CONSENT. LEGAL ARTEFACT — DO NOT FABRICATE CONSENT:…

Untrusted display-only summary

PERMANENTLY 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 permane…

Untrusted display-only summary

Revoke a contact's TCPA consent for a given Saperly number, blocking further outbound contact to them. CALL THIS WHEN A RECIPIENT SAYS 'STOP' / 'UNSUBSCRIBE' / 'do not contact me' — honoring an opt-out is a legal compliance obligation, and this is the primary legitimate use. OBSERVABLE EFFECT: once revoked, SAPERLY_SE…

Untrusted display-only summary

PAID / 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 t…

Untrusted display-only summary

Set 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…

Untrusted display-only summary

Set 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 alph…

Untrusted display-only summary

Set 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.

Untrusted display-only summary

PAID / 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…

Untrusted display-only summary

Partially 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…

Untrusted display-only summary