Outbound Calls | Smallest AI Docs

Use start_outbound_call() to dial any phone number and connect it to your agent. This is the production outbound surface — full variables support for per-call personalization, optional caller-ID rotation, and version pinning.

Not to be confused with /agent/{id}/versions/{versionId}/test-call. That endpoint is a debug surface bound to a specific agent draft or version. It only accepts mode and toPhone, doesn’t carry per-call variables, and counts against test-call slot limits. For real outbound traffic — campaigns, lead callbacks, anything customer-facing — use the pattern on this page (which maps to POST /conversation/outbound).

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_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

These are the parameters the Python SDK’s start_outbound_call() method accepts today.

Parameter	Type	Required	Description
`agent_id`	string	Yes	ID of your agent (from the dashboard).
`phone_number`	string	Yes	E.164 format phone number (e.g. `+14155551234`, `+919876543210`).
`variables`	object	No	Per-call values that override the agent’s `defaultVariables` for this conversation. Keys are variable names; values must be `string`, `number`, or `boolean`. Nested objects are not supported. See Personalization below.
`from_product_id`	string	No	ID of the phone-number product to dial from. Use this to rotate caller IDs or pin a specific number per call. Get IDs via `GET /product/phone-numbers`. Omit to use the agent’s default.

REST-only parameters

The underlying POST /conversation/outbound endpoint accepts one additional parameter that is not yet exposed by the Python SDK. To use it today, call the REST API directly with requests or httpx:

Parameter	Type	Description
`versionId`	string	Pin the call to a specific published agent version. The call log is attributed to that version so you can A/B-test versions in production.

1 import os, requests
2 
3 response = requests.post(
4     "https://api.smallest.ai/atoms/v1/conversation/outbound",
5     headers={"Authorization": f"Bearer {os.environ['SMALLEST_API_KEY']}"},
6     json={
7         "agentId": "your-agent-id",
8         "phoneNumber": "+14155551234",
9         "variables": {"customer_name": "Sarah Johnson", "package": "Gold"},
10         "versionId": "your-version-id",
11     },
12 )
13 response.raise_for_status()
14 print("Call started:", response.json()["data"]["conversationId"])

Personalization (passing per-call variables)

Pass variables to carry caller-specific values into the conversation — names, lead source, amounts, anything the agent should reference.

1 response = client.atoms.calls.start_outbound_call(
2     agent_id="your-agent-id",
3     phone_number="+14155551234",
4     variables={
5         "customer_name": "Sarah Johnson",
6         "package": "Gold",
7         "lead_source": "facebook_ad",
8         "vip": True,
9     },
10 )

Scalar values only. string, number, boolean. Nested objects are rejected with HTTP 400 ("Invalid input") — flatten the payload client-side (address_city instead of address: { city: ... }).
Variables are persisted with the call. They appear on the conversation log at data.variables and can be retrieved via GET /conversation/{id}.

See Variables for the agent-side guide to defining and referencing variables.

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_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.