Agent onboarding

Two ways to get a working line. Hand the prompt below to your AI coding agent and walk away, or follow the manual four-step flow yourself.

For your AI agent

Paste this prompt into Cursor, Claude Code, Codex, or OpenClaw. Your agent will install the SDK, provision a line, and place a test call.

Copy this into your AI coding agent

I want to give my AI agent a real phone number using Saperly
(https://saperly.com), the first phone carrier built for AI agents.
One-time setup (human, in browser):
1. Sign in at https://saperly.com/login (magic link, Google, or GitHub).
2. Open https://saperly.com/settings/keys and create an API key.
   The plaintext is shown once. Copy it.
3. export SAPERLY_API_KEY=<your-key>
Now do the rest autonomously:
1. Install the Saperly SDK. Pick the language that matches this project:
   - Node / TypeScript: npm install @saperly/sdk
   - Python: pip install saperly
2. Read SAPERLY_API_KEY from the environment.
3. Provision a hosted line. Hosted mode means Saperly runs the AI for you
   (no webhook server or audio handler needed). POST /v1/lines with:
     { "name": "my agent",
       "mode": "hosted",
       "system_prompt": "You are a helpful assistant." }
   Reuse an existing line named "my agent" if one already exists; do not
   provision duplicates. Save the returned line_id.
4. Place a test outbound call to a phone I own. POST /v1/calls with:
     { "line_id": "<from step 3>", "to_number": "<my real E.164 number>" }
   Important: ask me for the to_number before placing the call. Never call
   +1 555-0100 through +1 555-0199; those are reserved test numbers that will
   never connect.
5. Poll GET /v1/calls/{id} until status is "completed" or "failed",
   then print the call summary.
For the canonical patterns and pitfalls, read
https://github.com/Saperly/saperly-node/blob/main/AGENTS.md
(or the Python equivalent at https://github.com/Saperly/saperly-python/blob/main/AGENTS.md).
Docs: https://docs.saperly.com/quickstart
Full reference: https://saperly.com/llms.txt

For your team

The same flow, by hand. Use this when you’re integrating Saperly into an existing codebase yourself.

1. Set your API key

Sign in at saperly.com/login, open Settings → API Keys, create a key, and save it as SAPERLY_API_KEY in your environment.

$ export SAPERLY_API_KEY=sk_live_...

2. Provision a hosted line

1 import os
2 from saperly import SaperlyClient
3 
4 saperly = SaperlyClient(api_key=os.environ["SAPERLY_API_KEY"])
5 
6 line = saperly.lines.create(
7     name="my agent",
8     mode="hosted",
9     system_prompt="You are a helpful assistant.",
10 )
11 
12 print(line.id, line.phone_number)

3. Place a test outbound call

1 call = saperly.calls.create(
2     line_id=line.id,
3     to_number="+14155551234",  # replace with your real E.164 number
4 )
5 print(call.id, call.status)

4. Verify call status

1 fetched = saperly.calls.get(call.id)
2 print(fetched.status, fetched.duration_sec)

Done. You have a hosted line, a test call placed against it, and a status record. From here, see Hosted mode for inbound, voice tuning, and SMS, or Service keys to let the agent mint its own scoped credentials.