Phone Calls - OneInbox

Overview

Phone calls go through your telephony provider. OneInbox currently supports Twilio and Telnyx as telephony providers. Before you can make or receive calls you need to:

Store your provider integration
Register a phone number
Make an outbound call or let inbound calls route to your agent

Step 1 — Add your provider integration

Create an integration with your telephony provider’s API key. Set provider to match your carrier (e.g., twilio, telnyx). For Twilio, your Account SID and auth token are available in the Twilio Console — Dashboard → Account Info.

curl -X POST https://api.oneinbox.ai/v1/credentials \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Carrier",
    "provider": "twilio",
    "api_key": "<your_provider_api_key>"
  }'

{
  "id": "crd_abc123",
  "name": "My Carrier",
  "provider": "twilio"
}

Save the id — you’ll use it as credential_id in Step 2.

Step 2 — Register a phone number

Use the credential_id from Step 1 to link your provider integration to the phone number. This tells OneInbox which provider account to route calls through and which agent to connect the call to.

curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15739693824",
    "friendly_name": "Sales Line",
    "provider": "twilio",
    "agent_id": "<agent_id>",
    "credential_id": "<crd_abc123>"
  }'

{
  "id": "phn_abc123",
  "phone_number": "+15739693824",
  "agent_id": "agt_abc123",
  "status": "active"
}

To reassign the number to a different agent later, use PATCH Update phone number with { "agent_id": "..." }.

Step 3 — Make an outbound call

Pass the registered from_number and the destination to_number. Use variables to inject per-call context (e.g., the customer’s name or order ID) into the agent’s first message and system prompt.

curl -X POST https://api.oneinbox.ai/v1/calls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<agent_id>",
    "to_number": "+919876543210",
    "from_number": "+15739693824",
    "variables": { "customer_name": "Sama", "order_id": "ORD-001" },
    "webhook_url": "https://your-server.com/per-call-webhook"
  }'

{
  "id": "call_abc123",
  "status": "initiated",
  "to_number": "+919876543210",
  "from_number": "+15739693824"
}

The call goes through these states:

Status	Meaning
`initiated`	Call created, connecting through your provider
`in_progress`	Call connected, agent is talking
`completed`	Call ended normally
`failed`	Call failed to connect

Step 4 — Read the results

After the call ends, fetch the full record to get the transcript, outcome, and summary.

# 1. Stop the call (if not already ended by the agent)
curl -X POST https://api.oneinbox.ai/v1/calls/<call_id>/stop \
  -H "Authorization: Bearer <api_key>"

# 2. Wait 2–3 seconds for processing to complete

# 3. Fetch the full record
curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"

{
  "id": "call_abc123",
  "status": "completed",
  "duration_seconds": 87,
  "messages": [
    { "role": "agent", "content": "Hi Sama! This is Aria from Acme." },
    { "role": "user",  "content": "Oh hi, yes I've been expecting your call." }
  ],
  "analysis": {
    "outcome": "Appointment Booked",
    "summary": "Caller agreed to a product demo on Thursday at 3pm."
  },
  "recording_url": "https://storage.oneinbox.ai/recordings/call_abc123.mp3"
}

messages and analysis are only populated after the call ends. Stop first, wait 2–3 seconds, then fetch.

Inbound calls

For inbound calls, register the phone number with your agent (Step 2 above). When someone dials the number, the call is automatically routed to the assigned agent — no extra configuration needed. To reassign a number to a different agent, use PATCH Update phone number:

curl -X PATCH https://api.oneinbox.ai/v1/phone-numbers/<phone_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "<new_agent_id>" }'

Search for available numbers

Search for available numbers from your provider before registering:

curl "https://api.oneinbox.ai/v1/phone-numbers/search?country=US&area_code=415&limit=10" \
  -H "Authorization: Bearer <api_key>"

​Overview

​Step 1 — Add your provider integration

​Step 2 — Register a phone number

​Step 3 — Make an outbound call

​Step 4 — Read the results

​Inbound calls

​Search for available numbers

​API reference