Outbound Calls

Basic Call

1 from smallestai import SmallestAI
2 
3 # Reads SMALLEST_API_KEY from the environment, or pass api_key="sk_..." explicitly
4 client = SmallestAI()
5 
6 response = client.atoms.calls.start_an_outbound_call(
7     agent_id="your-agent-id",
8     phone_number="+14155551234",
9 )
10 
11 print(f"Call started: {response.data.conversation_id}")

Get your API key at app.smallest.ai/dashboard/api-keys and export it as SMALLEST_API_KEY, or pass SmallestAI(api_key="sk_...") directly.

Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	ID of your agent (from the dashboard)
`phone_number`	string	Yes	E.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"

Field	Type	Description
`conversation_id`	string	Unique ID to track this call

Save this ID to retrieve transcripts and analytics later.

Error Handling

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

Tips

Validate phone numbers first

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

Add delays between calls

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

Store conversation IDs

Save them in your database to retrieve transcripts later.

Handle errors gracefully

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

1	from smallestai import SmallestAI
2
3	# Reads SMALLEST_API_KEY from the environment, or pass api_key="sk_..." explicitly
4	client = SmallestAI()
5
6	response = client.atoms.calls.start_an_outbound_call(
7	agent_id="your-agent-id",
8	phone_number="+14155551234",
9	)
10
11	print(f"Call started: {response.data.conversation_id}")

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