---
title: "Place a voice call"
method: POST
path: "/voice"
tags: ["voice"]
---

# Place a voice call

`POST /voice`

## Request

- Base URL: `https://cpaas.zoho.com/v1.1`
- URL: `https://cpaas.zoho.com/v1.1/voice`
- Auth: API key in header `Authorization`

Places an outbound voice call to a single recipient. Accepts a single content source - either a pre-created voice template (`template_key` or `template_alias`), which may define a multi-step IVR flow with keypad input and call transfer, or an ad-hoc text-to-speech message (`message_content` with optional `language` and `voice_gender`). Exactly one content source is required.

`from` must be an approved voice number of the agent and `to` is the recipient; both must include the country code. If the template defines merge tags, all of them must be supplied in `merge_info` - a request with missing tags is rejected with the missing tag names listed. Phone numbers should be provided as merge values (for example the agent number of a call-transfer step) and also include country code.

## Request body

- VoiceSendVoiceRequest: Request body for sending a voice call. Exactly one content source is required: `template_key`/`template_alias` (a pre-created voice template) or `message_content` (ad-hoc text-to-speech).
  - `voice_gender` 'male' | 'female': Voice used for text-to-speech.
  - `message_content` string: Text-to-speech message spoken to the recipient. Letters, digits, spaces and common punctuation are allowed. Use instead of a template.
  - `template_key` string, uuid: Key of a pre-created voice template. Provide this or `template_alias` (or `message_content` instead).
  - `client_reference` string: Client-supplied reference identifier, echoed in call logs.
  - `agent_key` string: Key of the sending agent. Optional - defaults to the agent bound to the API token.
  - `merge_info` object: Key-value map that resolves the template's `{{merge_tags}}`. All tags defined by the template are mandatory; if any are missing, the request is rejected and the missing tag names are listed in the error. Phone numbers passed as merge values (for example the agent number of a call-transfer step) must include the country code.
  - `from` string, required: Caller id - an approved voice number of the agent, including the country code.
  - `language` string: Language code used for text-to-speech (e.g. `en`, `hi`, `fr`).
  - `to` string, required: Recipient phone number, including the country code.
  - `template_alias` string: Alias of a pre-created voice template. Provide this or `template_key` (or `message_content` instead).

## Response `200`

Voice call accepted and initiated.

- VoiceSendVoiceResponse: Success response returned when the voice call is accepted and initiated.
  - `data` object
    - `code` string: Acceptance code.
    - `message_id` string, uuid: Unique identifier of the call. Use it with the call-details API.
    - `message` string
    - `request_id` string: Unique identifier assigned to the send request.
  - `status` string

## Other responses

- `400`: Bad Request (`TM_3301`) - a required parameter is missing or the payload is malformed.
- `401`: Access Denied (`TM_4001`) - missing or invalid API token.
- `403`: Request Denied (`TM_3601`) - the `from` number is a voice number not associated with the sending agent (`VOI_207`).
- `422`: Unprocessable Entity (`TM_3501`) - the request is well-formed but cannot be processed: missing caller id, missing content, unknown template, missing merge tags, or a phone number that is not valid for the account.

---

[API](https://skmtc.dev/zoho/apis/zoho-cpaas.md) - [All operations](https://skmtc.dev/zoho/apis/zoho-cpaas/llms.txt) - [OpenAPI document](https://skmtc.dev/zoho/apis/zoho-cpaas/revisions/f0858a38e8b0?raw)