Python SDK

1
from agentphone import AgentPhone
2
3
client = AgentPhone(api_key="YOUR_API_KEY")
4
5
# Create an agent
6
agent = client.agents.create(name="Support Bot")
7
8
# Buy a number and attach it
9
number = client.numbers.buy(country="US", agent_id=agent.id)
10
11
# Make an AI-powered call
12
call = client.calls.make_conversation(
13
    agent_id=agent.id,
14
    to_number="+15559876543",
15
    topic="You are a helpful support assistant.",
16
    initial_greeting="Hi, this is Support Bot!",
17
)

1
from agentphone import AsyncAgentPhone
2
3
async with AsyncAgentPhone(api_key="YOUR_API_KEY") as client:
4
    agents = await client.agents.list()
5
    call = await client.calls.make_conversation(
6
        agent_id=agents.data[0].id,
7
        to_number="+15559876543",
8
        topic="You are a helpful assistant.",
9
    )

1
# List all agents
2
agents = client.agents.list(limit=20, offset=0)
3
4
# Create an agent
5
agent = client.agents.create(
6
    name="Support Bot",
7
    description="Handles customer inquiries",
8
)
9
10
# Get agent details
11
agent = client.agents.get(agent_id="agt_abc123")
12
13
# Attach a number to an agent
14
client.agents.attach_number(agent_id="agt_abc123", number_id="num_xyz789")

1
# List numbers
2
numbers = client.numbers.list(limit=20, offset=0)
3
4
# Buy a new number
5
number = client.numbers.buy(
6
    country="US",
7
    area_code="415",       # optional, US/CA only
8
    agent_id="agt_abc123", # optional: attach immediately
9
)
10
11
# Get messages for a number
12
messages = client.numbers.get_messages(number_id="num_xyz789", limit=50)
13
14
# Release a number (irreversible)
15
client.numbers.release(number_id="num_xyz789")

1
# List all conversations
2
convos = client.conversations.list(limit=20, offset=0)
3
4
# Get a conversation with messages
5
convo = client.conversations.get(
6
    conversation_id="conv_abc123",
7
    message_limit=50,
8
)

1
# List all calls
2
calls = client.calls.list(limit=20, offset=0)
3
4
# Get a call with transcript
5
call = client.calls.get(call_id="call_abc123")
6
7
# Make a webhook-based call (requires webhook configured)
8
call = client.calls.make(
9
    agent_id="agt_abc123",
10
    to_number="+15559876543",
11
    initial_greeting="Hello!",
12
)
13
14
# Make an AI conversation call (no webhook needed)
15
call = client.calls.make_conversation(
16
    agent_id="agt_abc123",
17
    to_number="+15559876543",
18
    topic="You are a support agent helping with order inquiries.",
19
    initial_greeting="Hello! How can I help you today?",
20
    model="gpt-4o-mini",  # optional
21
)

1
# Get webhook config
2
webhook = client.webhooks.get()
3
4
# Set or update webhook
5
webhook = client.webhooks.set(
6
    url="https://your-server.com/webhook",
7
    context_limit=10,  # 0-50 recent messages in payloads
8
)
9
print(webhook.secret)  # save this!
10
11
# View delivery history
12
deliveries = client.webhooks.list_deliveries(limit=50)
13
14
# Test webhook
15
client.webhooks.test()
16
17
# Delete webhook
18
client.webhooks.delete()

1
from agentphone import (
2
    AgentPhoneError,
3
    AuthenticationError,
4
    NotFoundError,
5
    RateLimitError,
6
)
7
8
try:
9
    agent = client.agents.get(agent_id="bad-id")
10
except NotFoundError:
11
    print("Agent not found")
12
except AuthenticationError:
13
    print("Invalid API key")
14
except RateLimitError:
15
    print("Too many requests")
16
except AgentPhoneError as e:
17
    print(f"API error {e.status}: {e.message}")

1
from agentphone import construct_event, verify_webhook, WebhookVerificationError
2
3
# Option 1: Verify signature only
4
try:
5
    verify_webhook(payload, signature, secret)
6
except WebhookVerificationError:
7
    print("Invalid signature")
8
9
# Option 2: Verify + parse into a typed event
10
event = construct_event(payload, signature, secret)
11
12
if event.event == "agent.message":
13
    print(event.data.message)
14
    print(event.data.from_number)
15
    print(event.recent_history)       # recent conversation context
16
    print(event.conversation_state)   # custom metadata

1
from flask import Flask, request, jsonify
2
from agentphone import construct_event
3
4
app = Flask(__name__)
5
6
@app.route("/webhook", methods=["POST"])
7
def webhook():
8
    event = construct_event(
9
        payload=request.data,
10
        signature=request.headers.get("X-Webhook-Signature", ""),
11
        secret="your_webhook_secret",
12
    )
13
14
    # Respond to the caller
15
    return jsonify({"response": f"Got your message: {event.data.message}"})

1
with AgentPhone(api_key="YOUR_API_KEY") as client:
2
    agents = client.agents.list()
3
# session is automatically closed

1
client = AgentPhone(
2
    api_key="YOUR_API_KEY",
3
    base_url="https://api.agentphone.to",
4
    timeout=30.0,
5
)