Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt

Use this file to discover all available pages before exploring further.

This guide shows how to call real phone numbers using a telephony carrier — Twilio, Tenyx, or another carrier. Complete Quickstart first — you need a working agent_id and api_key. At the end: your agent can dial someone’s phone (outbound) and answer calls on a number you own (inbound).

​
Overview

In this guide you will:
  • Store a telephony integration in OneInbox
  • Search and register a phone number (for inbound)
  • Place an outbound call with POST /v1/calls

​
Prerequisites

ItemWhereWhy
api_keyDashboardAuthenticates requests
agent_idQuickstartAgent on the call
Telephony accountYour carrier (Twilio, Tenyx, etc.)Phone network
Carrier credentialsYour carrier consoleAPI key or auth token for POST /v1/credentials

​
Outbound vs inbound

TypeWho dials whomSetup
OutboundAgent calls the customerStep 4 — POST /v1/calls
InboundCustomer calls your numberSteps 2–3 — search + register
1

1. Add a telephony integration

​
Goal

Store your carrier credentials in OneInbox.
curl -X POST https://api.oneinbox.ai/v1/credentials \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Telephony",
    "provider": "twilio",
    "api_key": "<your_carrier_api_key_or_auth_token>"
  }'
Replace provider and api_key with your carrier’s values — e.g. twilio + Auth Token, or tenyx + Tenyx API key.
{
  "id": "cred_telephony_abc123",
  "name": "Production Telephony",
  "provider": "twilio"
}
2

2. Search for an available number

​
Goal

List numbers you can register. Skip if you only need outbound and already have a from_number.Number search is available for carriers that support it (e.g. Twilio):
curl "https://api.oneinbox.ai/v1/phone-numbers/search?country=US&area_code=415&limit=10&credential_id=<telephony_integration_id>" \
  -H "Authorization: Bearer <api_key>"
Query paramMeaning
countryISO code: US, GB, IN, etc.
area_codeOptional filter
containsOptional digit pattern
credential_idTelephony integration ID from step 1
If your carrier does not support search, use a number you already own from the carrier console and go to step 3.
3

3. Register the number (inbound)

​
Goal

Route inbound calls on this number to your agent.Option A — integration ID (Twilio and similar):
curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Support Line",
    "provider": "twilio",
    "agent_id": "<agent_id>",
    "credential_id": "<telephony_integration_id>"
  }'
Option B — SIP trunk (any carrier with SIP, including Tenyx):
curl -X POST https://api.oneinbox.ai/v1/phone-numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "friendly_name": "Support Line",
    "provider": "twilio",
    "agent_id": "<agent_id>",
    "provider_config": {
      "trunk_address": "your-carrier.pstn.example.com",
      "auth_username": "<sip_username>",
      "auth_password": "<sip_password>"
    }
  }'
Set provider to your carrier’s value. See Register phone number.
4

4. Make an outbound call

​
Goal

Your agent dials a phone number and starts a conversation.
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": "Sam", "order_id": "ORD-001" },
    "webhook_url": "https://example.com/per-call-webhook"
  }'
FieldRequiredDescription
to_numberYesE.164 format
from_numberYesRegistered carrier number
variablesNoPer-call prompt context
webhook_urlNoOverride webhook for this call
{
  "id": "call_xyz789",
  "status": "initiated",
  "to_number": "+919876543210",
  "from_number": "+15739693824"
}

​
Verify a call

curl https://api.oneinbox.ai/v1/calls/<call_id> \
  -H "Authorization: Bearer <api_key>"
Wait for "status": "completed", then read transcript.

​
Troubleshooting

ProblemLikely causeFix
401Wrong tokenUse dashboard api_key
Invalid numberFormatE.164: +14155551234
International failsCarrier geo settingsEnable outbound in your carrier console
Inbound no agentRegistrationRedo step 3 with correct agent_id
Invalid carrier credentialsWrong key or tokenRe-create integration in step 1

​
Next steps

Integrations

Telephony and BYOK

Webhooks

Call lifecycle events

Agents

Tune voice and behavior

API reference

Full outbound options