Copy page

Programmable Voice

Programmable Voice

Programmable Voice lets you place and control phone calls from your own application. You create outbound calls with a REST request, and you script what happens on a live call, inbound or outbound, with OneML: an XML document your server returns from a URL that Signals requests. Use it for IVR menus, call forwarding, voicemail, spoken one-time passcodes, delivery notifications and any other flow that needs to start or steer a phone call in real time.

The pieces

Piece	What it is
Voice Account	The credential pair for the Calls API: an AccountSid (AC followed by 32 hexadecimal characters) and an auth token. Each Signals project has one. Find it in the console under Developers, Voice Account. The auth token also signs the webhooks Signals sends you.
Voice application	A named set of URLs on your server: the voice URL Signals requests when a call arrives, plus an optional status callback URL and fallback URL.
Number route	The link from a number your project owns to a voice application. Calls to that number run the application.
OneML	The XML your server returns. Each element, called a verb, does one thing on the call: speak, play audio, collect digits, record, dial another number.

How a call is controlled

Signals controls every call the same way: it requests a URL on your server and runs the OneML document your server returns. Inbound and outbound calls use the same loop.

1. A call starts. Either a caller dials a number routed to one of your voice applications, or you create an outbound call through the Calls API.
2. Signals requests the URL for that call (the application's voice URL, or the Url you passed when creating the call), sending parameters such as CallSid, From and To.
3. Your server returns a OneML document. Signals runs it verb by verb until the document ends or a verb ends the call.

Your server can return a different document at every step. A verb such as <Gather> sends the caller's input to an action URL, and the document returned from that URL decides what happens next. A call can move through menus, hold music, an agent transfer or voicemail entirely under your control.

For example, a caller dials +2342013300100. That number is routed to an application whose voice URL is https://voice.example.com/incoming. Signals sends a POST to that URL with From=+2348031234567, your server answers with <Response><Say>Thank you for calling.</Say></Response>, and the caller hears the greeting.

Two APIs

Programmable Voice uses two APIs with different credentials:

API	Base URL	Credential	Use it to
Calls API	https://api.signals.pressone.africa/2010-04-01/Accounts/{AccountSid}	HTTP Basic: AccountSid and auth token	Create, list, update and end calls, read recordings and download their audio, inspect call events.
Signals API	https://api.signals.pressone.africa/v1	Bearer sk_live_ API key	Create and manage voice applications and read the Voice Account.

The Calls API follows the Twilio 2010-04-01 request and response format, so most Twilio integrations and TwiML documents run with a changed base URL and credentials. See Moving from Twilio for the differences.

Next steps

Page	Description
Quickstart	Place your first call.
Receiving calls	Create a voice application, route a number to it and answer calls.
Webhooks	Request format, parameters, timeouts, fallback and call events.
Status callbacks	Get notified as a call moves through its lifecycle.
Recording calls	Record calls and download the audio.
Forwarding calls	Bridge a call to another number with <Dial>.
OneML reference	Every OneML verb and attribute.
Order-tracking tutorial	Build a complete order-status line.
Calls API reference	Every Calls API endpoint.