Outbound Calls

View as MarkdownOpen in Claude

Use start_outbound_call() to dial any phone number and connect it to your agent.

Basic Call

1from smallestai.atoms import AtomsClient
2
3client = AtomsClient()
4
5response = client.start_outbound_call(
6 conversation_outbound_post_request={
7 "agentId": "your-agent-id",
8 "phoneNumber": "+14155551234"
9 }
10)
11
12conversation_id = response.data.conversation_id
13print(f"Call started: {conversation_id}")

Parameters

ParameterTypeRequiredDescription
agentIdstringYesID of your agent (from dashboard)
phoneNumberstringYesE.164 format phone number

Phone numbers must be in E.164 format: +[country code][number]

Examples: +14155551234 (US), +919876543210 (India)

Response

1# response.data.conversation_id = "CALL-1767900635803-8a3bee"
FieldTypeDescription
conversation_idstringUnique ID to track this call

Save this ID to retrieve transcripts and analytics later.

Error Handling

1try:
2 response = client.start_outbound_call(
3 conversation_outbound_post_request={
4 "agentId": "agent-123",
5 "phoneNumber": "+14155551234"
6 }
7 )
8 print(f"Call started: {response.data.conversation_id}")
9
10except Exception as e:
11 error = str(e)
12
13 if "Invalid agent id" in error:
14 print("Error: Agent not found. Check your agent ID.")
15 elif "Invalid phone" in error:
16 print("Error: Invalid phone number. Use E.164 format.")
17 elif "401" in error:
18 print("Error: Check your API key.")
19 else:
20 print(f"Error: {error}")

Tips

Use a library like phonenumbers to validate before calling. Invalid numbers waste API calls.

Wait 5-10 seconds between calls to avoid rate limits.

Save them in your database to retrieve transcripts later.

Wrap calls in try/except and log failures for retry.