---
title: "Saperly integration for LuumenAI"
url: "https://www.luumen.ai/integrations/saperly/"
entity: SoftwareIntegration
category: "Communication"
audience: "SRE, DevOps, platform engineering, IT operations"
---

# Saperly integration for LuumenAI

Phone numbers, voice, and SMS your agent can read and act on

## What LuumenAI can do with Saperly

LuumenAI connects to Saperly with an API token and exposes 30 tools (15 read-only · 11 write · 4 destructive). For connected tools, admins configure which actions may run automatically and which require approval, within the access granted to the user.

## Key facts

- Authentication: API token
- Tools available: 30 tools (15 read-only · 11 write · 4 destructive)
- Deployment: scoped as part of your Pilot, Platform, or Managed rollout
- Category: Communication

## About Saperly with LuumenAI

Saperly gives your team phone numbers, outbound voice, and SMS behind one API. Connected to Luumen, the agent reads call history, transcripts, message logs, consent records, and your prepaid balance on request. Placing a call, sending a message, or provisioning a number is previewed first and sent for approval before anything bills or rings.

## Example tools

Read-only (15 in total):

- `SAPERLY_CHECK_CONSENT` — 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.
- `SAPERLY_GET_CALL` — Fetch a single call by its id, returning its status, per-minute rate, final duration (durationSec) and cost (costCents), and the hasRecording / hasTranscript flags.
- `SAPERLY_GET_CALL_RECORDING` — Get the audio recording for a call and return it as a downloadable file.
- `SAPERLY_GET_CALL_TRANSCRIPT` — Fetch the transcript (conversation turns/segments) of a completed call by its id.
- `SAPERLY_GET_CONNECTION` — 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…
- `SAPERLY_GET_NUMBER` — Fetch a single phone number by its id, returning its E.164 phoneNumber, bound connectionId, webhookUrl, country, numberType, pricing and lifecycle fields.
- `SAPERLY_GET_USAGE` — Return the workspace usage summary and prepaid balance: calls {count, totalCostCents, totalDurationSec}, messages {count}, and balanceCents (the prepaid balance, in cents).
- `SAPERLY_LIST_CALLS` — Return the full voice-call history (inbound + outbound) for the connected Saperly workspace.

Write and destructive (15 in total, subject to configured approval policy):

- `SAPERLY_ASSIGN_NUMBER_CONNECTION` — 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…
- `SAPERLY_CREATE_CONNECTION` — Create a connection: the AI 'brain' that answers calls and (optionally) SMS on a Saperly phone number.
- `SAPERLY_DELETE_CONNECTION` — PERMANENTLY AND IRREVERSIBLY delete a connection (the AI answering brain / persona that handles calls and SMS) by its id.
- `SAPERLY_END_CALL` — End an in-progress call by its id, hanging up and settling the metered cost.
- `SAPERLY_PLACE_CALL` — 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.
- `SAPERLY_PROVISION_NUMBER` — PAID / METERED: provision (buy) a new phone number in a country.
- `SAPERLY_RECORD_CONSENT` — Record TCPA consent for a contact so outbound SMS (SAPERLY_SEND_SMS) and calls (SAPERLY_PLACE_CALL) from your number are permitted.
- `SAPERLY_RELEASE_NUMBER` — PERMANENTLY AND IRREVERSIBLY release a phone number back to the carrier.

## Frequently asked questions

### How does LuumenAI connect to Saperly?

Authorize once with API token. Luumen lists the scopes each action needs before you approve the connection, and credentials never appear in the chat.

### Can LuumenAI change things in Saperly on its own?

For connected tools, admins configure which actions may run automatically and which require approval, within the access granted to the user.

### Is there an audit trail?

Every call to Saperly — read or write, approved or declined — is recorded with the actor, the input, and the result.

Full page: https://www.luumen.ai/integrations/saperly/