Telephony
Phone numbers, SMS, call routing, and provider webhooks.
Telephony routes inbound and outbound voice and SMS through Twilio, OpenAI Realtime, or ElevenLabs depending on the number and agent configuration. Use these endpoints to inventory numbers, manage routing, inspect calls, send SMS, and receive provider callbacks.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /api/v1/telephony | Overview (numbers, recent calls). |
GET | /api/v1/telephony/calls | List calls. |
GET | /api/v1/telephony/numbers | List numbers. |
POST | /api/v1/telephony/numbers/import | Import a number. |
GET | /api/v1/telephony/routing | Routing rules. |
POST | /api/v1/telephony/routing | Create routing rule. Browser session + fresh step-up required; API keys rejected. |
PATCH | /api/v1/telephony/routing | Update routing. Browser session + fresh step-up required; API keys rejected. |
DELETE | /api/v1/telephony/routing | Delete routing rule. Browser session + fresh step-up required; API keys rejected. |
GET | /api/v1/telephony/sms | List SMS messages. |
POST | /api/v1/telephony/sms | Send SMS. |
POST | /api/v1/telephony/openai/webhook | OpenAI realtime voice webhook. |
POST | /api/v1/telephony/elevenlabs/webhook | ElevenLabs webhook. |
POST | /api/v1/telephony/elevenlabs/tools/close-conversation | ElevenLabs tool callback to close a conversation. |
POST | /api/v1/telephony/elevenlabs/tools/queue-agent-run | ElevenLabs tool callback to queue an agent run. |
POST | /api/v1/telephony/webhooks/conference-bridge | Provider conference bridge webhook. |
POST | /api/v1/telephony/webhooks/outbound-target-status | Provider outbound target status webhook. |
POST | /api/v1/telephony/webhooks/sms | Provider SMS webhook. |
POST | /api/v1/telephony/webhooks/status | Provider call status webhook. |
POST | /api/v1/telephony/webhooks/voice | Provider voice webhook. |
Numbers and routing
Numbers belong to the current organization. GET /api/v1/telephony/numbers lists imported phone numbers and POST /api/v1/telephony/numbers/import attaches an existing provider number so Alumia can route it.
Routing rules decide which agent or workflow handles inbound calls. Read the active rules with GET /api/v1/telephony/routing. Creating, updating, or deleting routing rules requires a browser session with fresh step-up; API keys are rejected.
SMS
GET /api/v1/telephony/sms returns the organization's SMS message history. POST /api/v1/telephony/sms sends an outbound SMS through the configured provider number.
Provider webhooks
Provider webhooks (/api/v1/telephony/webhooks/*, OpenAI callbacks, and ElevenLabs callbacks) are unauthenticated ingress endpoints verified by provider signatures or provider-specific secrets. They are not general-purpose webhook receivers; use Webhooks for signed inbound receivers you create yourself.
See Voice for realtime audio sessions and phone-call voice behavior.