# VoiceML requests

When Cloud Voice needs instructions for a call, it sends a **VoiceML request** to one of the handler URIs configured for that call. The request is an HTTP `POST` with a JSON body. Your server replies with a [VoiceML](overview.md) XML document, and Cloud Voice executes the actions in that document on the call. When an action that has a `NextUri` finishes, Cloud Voice sends the next VoiceML request, and the cycle repeats until the call ends.

!!! note "Explaining the difference between VoiceML requests and webhooks"
    VoiceML requests are **synchronous request/response**: your server must reply with a VoiceML XML document, and Cloud Voice acts on that response. They are sent to the call's handler URIs &mdash; for incoming calls, the URI configured on the phone number; for outgoing calls, the `handlerUris` field of [`Call.options`](../api-reference/rest/v1beta1/projects.calls/overview.md#callapicalloptions).

    [Voice Webhooks](../webhooks.md) are **fire-and-forget event notifications** &mdash; you return any 2xx status code, and the response body is ignored. They are sent for events such as `CALL_STATE_UPDATE`, `FAX_READY`, `RECORDING_READY`, and `TRANSCRIPTION_READY`.

## Request

Cloud Voice sends a VoiceML request as:

- **Method**: `POST`
- **Headers**:
    - `Content-Type: application/json; charset=utf-8`
    - `X-Enfonica-Event: CALL`
    - `X-Enfonica-Signature`: HMAC-SHA256 signature for authenticity verification. See [Request signing](../../platform/request-signing.md) for the algorithm and reference implementations.
- **Body**: a JSON-serialized [`enfonica.voice.v1beta1.CallRequest`](https://github.com/enfonica/enfonicaapis/blob/master/enfonica/voice/v1beta1/call_request.proto).

## Request body

The body has two fields:

Field | Description
--|--
`call` | A JSON-serialized [`enfonica.voice.v1beta1.Call`](../api-reference/rest/v1beta1/projects.calls/overview.md#resource-call) representing the call at the time of the request. The `state` field reflects the call's state at the moment Cloud Voice issued the request &mdash; for example, `STARTING` for an incoming call that has not yet been answered, or `IN_PROGRESS` after an `<Input>` collected digits on an answered call.
`parameters` | A string-to-string map of return values from the action that most recently completed. Empty (or absent) on the **first** VoiceML request of a call. On subsequent requests, contains the parameters documented on the action that produced them (see [Return parameters](#return-parameters) below).

### Return parameters

The following actions populate `parameters` on the next VoiceML request:

- [`<Call>`](call.md#nexturi) &mdash; `action`, `callStatus`, `callEndpoint`
- [`<Input>`](input.md#nexturi) &mdash; `action`, `digits`
- [`<Record>`](record.md#nexturi) &mdash; `action`, `recording`, `estimatedDurationSeconds`
- [`<Stream>`](stream.md#passing-data-to-the-call) &mdash; any parameters set via `update_request_parameters`

Other actions (such as `<Say>`, `<Play>`, `<Wait>`) do not populate `parameters`.

### Example: first request

The first VoiceML request for an incoming PSTN call. The call has not been answered yet, so `state` is `STARTING` and `parameters` is empty.

```json
{
  "call": {
    "name": "projects/my-project/calls/abc123def456",
    "to": "+61399998888",
    "from": "+61400111222",
    "isPrivate": false,
    "transport": "PSTN",
    "direction": "INCOMING",
    "state": "STARTING",
    "createTime": "2026-05-15T14:23:01.234Z",
    "startTime": "2026-05-15T14:23:01.234Z",
    "createMethod": "INCOMING_CALL",
    "fromLocation": {
      "regionCode": "AU",
      "administrativeArea": "Victoria",
      "locality": "Melbourne"
    },
    "fromZone": "Melbourne"
  },
  "parameters": {}
}
```

### Example: follow-up request after `<Input>`

The same call after your application returned a VoiceML response containing `<Input>`, and the caller pressed `1#`. The call is now answered, so `state` is `IN_PROGRESS` and `answerTime` is set. The `parameters` map carries the values documented on [`<Input>`](input.md#nexturi).

```json
{
  "call": {
    "name": "projects/my-project/calls/abc123def456",
    "to": "+61399998888",
    "from": "+61400111222",
    "isPrivate": false,
    "transport": "PSTN",
    "direction": "INCOMING",
    "state": "IN_PROGRESS",
    "createTime": "2026-05-15T14:23:01.234Z",
    "startTime": "2026-05-15T14:23:01.234Z",
    "answerTime": "2026-05-15T14:23:03.456Z",
    "createMethod": "INCOMING_CALL",
    "fromLocation": {
      "regionCode": "AU",
      "administrativeArea": "Victoria",
      "locality": "Melbourne"
    },
    "fromZone": "Melbourne"
  },
  "parameters": {
    "action": "INPUT",
    "digits": "1"
  }
}
```

## Response

Your server replies with:

- **Status**: `200 OK`. Any 2xx status is accepted. Redirects (3xx) are followed.
- **Header**: `Content-Type` indicating XML, for example `application/xml`.
- **Body**: a VoiceML document &mdash; a `<Response>` element wrapping zero or more [VoiceML actions](overview.md#actions).

### Example response

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Input MaxDigitCount="1" NextUri="/menu">
        <Say>Press 1 for sales, 2 for support, or 3 for everything else.</Say>
    </Input>
</Response>
```

### Failure handling

Your server has 10 seconds to respond. A non-2xx response, a network failure, or a response that takes longer is treated as a failure, and Cloud Voice tries the call's next handler URI, if it has more than one.

Cloud Voice tries each handler URI once. Unlike [voice webhooks](../webhooks.md#response), a VoiceML request isn't retried. If no handler URI returns VoiceML, the call fails. See [Limits](../../platform/limits.md#cloud-voice).

A 2xx response that isn't valid VoiceML, or that has the wrong `Content-Type`, also fails the call. Cloud Voice doesn't try another handler URI after it.

The URIs in a [`<Redirect>`](redirect.md#failover) fail over the same way.

## Lifecycle

A typical call goes through this loop:

1. An event triggers the first request &mdash; an incoming call arrives, or an outgoing call created via the API reaches the point where it needs instructions.
2. Cloud Voice POSTs a `CallRequest` to the first handler URI. `parameters` is empty.
3. Your server replies `200 OK` with a `<Response>` document.
4. Cloud Voice executes the actions in order.
5. When an action with a `NextUri` finishes, Cloud Voice POSTs the next `CallRequest`. `parameters` contains the return values from the action that just completed.
6. If execution reaches the end of the document without a `NextUri` or other continuation, there may be no further `CallRequest`; the call flow ends after the final action completes.

## Cookies

VoiceML requests maintain cookies on the controlling call. You can use cookies to easily maintain state in a conversation by either setting cookies directly, or using the in-built session state in your programming language or framework of choice.
