# 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](/api/voice-calls) | `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](/api/programmable-voice) | `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](/programmable-voice/twilio-compatibility) for the differences.

## Next steps

| Page | Description |
|------|-------------|
| [Quickstart](/programmable-voice/quickstart) | Place your first call. |
| [Receiving calls](/programmable-voice/receiving-calls) | Create a voice application, route a number to it and answer calls. |
| [Webhooks](/programmable-voice/webhooks) | Request format, parameters, timeouts, fallback and call events. |
| [Status callbacks](/programmable-voice/status-callbacks) | Get notified as a call moves through its lifecycle. |
| [Recording calls](/programmable-voice/recording-calls) | Record calls and download the audio. |
| [Forwarding calls](/programmable-voice/forwarding-calls) | Bridge a call to another number with `<Dial>`. |
| [OneML reference](/programmable-voice/oneml/overview) | Every OneML verb and attribute. |
| [Order-tracking tutorial](/programmable-voice/tutorials/order-tracking-line) | Build a complete order-status line. |
| [Calls API reference](/api/voice-calls) | Every Calls API endpoint. |