Saperly + Stream Deck

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

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: '<consentType>'} (the 'type' key is ABSENT when hasConsent is false). Saperly REFUSES outbound SMS (SAPERLY_SEND_SMS) and voice calls (SAPERLY_PLACE_CALL) — both of which are paid, balance-metered — to a destination without active consent, so call this free, read-only check FIRST to decide whether you need SAPERLY_RECORD_CONSENT before spending on a paid send/call that would otherwise fail the compliance gate. No side effects.

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

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

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

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

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

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