Place a voice call

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

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.

Endpoint

post /voice

Request URL

https://cpaas.zoho.com/v1.1/voice Copied!

Request Parameters

- Request Headers

ApiKeyAuthAPI Key

API key of an agent. Send the header as Authorization: Zoho-enczapikey {apiKey}. The agent and account are derived from the key.

- Request Body

application/json
JSON Object

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).

Show Sub-Attributes
fromstring(length: 8-20)Mandatory

Caller id - an approved voice number of the agent, including the country code.

Minimum Length :8Copied!
Maximum Length :20Copied!
tostring(length: 8-20)Mandatory

Recipient phone number, including the country code.

Minimum Length :8Copied!
Maximum Length :20Copied!
template_keyuuid(length <= 500)Optional

Key of a pre-created voice template. Provide this or template_alias (or message_content instead).

Maximum Length :500Copied!
template_aliasstring(length <= 100)Optional

Alias of a pre-created voice template. Provide this or template_key (or message_content instead).

Maximum Length :100Copied!
merge_infoJSON ObjectOptional

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.

Show Sub-Attributes
message_contentstring(length <= 5000)Optional

Text-to-speech message spoken to the recipient. Letters, digits, spaces and common punctuation are allowed. Use instead of a template.

Maximum Length :5000Copied!
languagestring(length: 2-10)Optional

Language code used for text-to-speech (e.g. en, hi, fr).

Default Value :enCopied!
Minimum Length :2Copied!
Maximum Length :10Copied!
voice_genderstringOptional

Voice used for text-to-speech.

Allowed Values :
Show Values ▾
maleCopied!
femaleCopied!
Copied!Copy all as JSON Array
Default Value :femaleCopied!
agent_keystring(length <= 300)Optional

Key of the sending agent. Optional - defaults to the agent bound to the API token.

Maximum Length :300Copied!
client_referencestring(length <= 100)Optional

Client-supplied reference identifier, echoed in call logs.

Maximum Length :100Copied!

Sample Request

Curl
Java
Python
Deluge
Copied!
curl --request POST \
  --url https://cpaas.zoho.com/v1.1/voice \
  --header 'Authorization: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"from":"14155550142","to":"919876543210","template_key":"794dc9c1-b268-11f1-bed6-b6d94062a427","merge_info":{"customer_name":"Paula","company_name":"Example Inc","order_id":"ORD-1001","currency":"INR","amount":"2499"},"client_reference":"order-confirm-1001"}'

Sample Request Body

Template call with merge values
Copied!
  {
    "from": "14155550142",
    "to": "919876543210",
    "template_key": "794dc9c1-b268-11f1-bed6-b6d94062a427",
    "merge_info": {
      "customer_name": "Paula",
      "company_name": "Example Inc",
      "order_id": "ORD-1001",
      "currency": "INR",
      "amount": "2499"
    },
    "client_reference": "order-confirm-1001"
  }
                
▼ Show full
Template call that transfers to an agent
Copied!
  {
    "from": "14155550142",
    "to": "919876543210",
    "template_key": "17af8320-b59c-11f1-8210-8688516064a9",
    "merge_info": {
      "number": "919845012345"
    },
    "client_reference": "support-callback-2213"
  }
                
▼ Show full
Ad-hoc text-to-speech call
Copied!
  {
    "from": "14155550142",
    "to": "919876543210",
    "message_content": "Hello. Your appointment is confirmed for tomorrow at 10 A M. Goodbye.",
    "language": "en",
    "voice_gender": "female",
    "client_reference": "appt-5501"
  }
                
▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json
JSON Object

Success response returned when the voice call is accepted and initiated.

Show Sub-Attributes
dataJSON Object
Show Sub-Attributes
codestring

Acceptance code.

message_iduuid

Unique identifier of the call. Use it with the call-details API.

messagestring
request_idstring

Unique identifier assigned to the send request.

statusstring

- HTTP code 400

Response Body - application/json
JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).

Show Sub-Attributes
errorJSON Object
Show Sub-Attributes
codestring
messagestring
detailsJSON Array
Show Sub-Attributes
object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).

messagestring
targetstring

The field the detail refers to, when applicable (e.g. from, to, merge_info).

target_value

The offending value, or for VOI_106 the comma-separated list of missing merge tag names.

request_idstring

Identifier of the failed request, when available.

- HTTP code 401

Response Body - application/json
JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).

Show Sub-Attributes
errorJSON Object
Show Sub-Attributes
codestring
messagestring
detailsJSON Array
Show Sub-Attributes
object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).

messagestring
targetstring

The field the detail refers to, when applicable (e.g. from, to, merge_info).

target_value

The offending value, or for VOI_106 the comma-separated list of missing merge tag names.

request_idstring

Identifier of the failed request, when available.

- HTTP code 403

Response Body - application/json
JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).

Show Sub-Attributes
errorJSON Object
Show Sub-Attributes
codestring
messagestring
detailsJSON Array
Show Sub-Attributes
object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).

messagestring
targetstring

The field the detail refers to, when applicable (e.g. from, to, merge_info).

target_value

The offending value, or for VOI_106 the comma-separated list of missing merge tag names.

request_idstring

Identifier of the failed request, when available.

- HTTP code 422

Response Body - application/json
JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403), TM_3501 unprocessable entity (422).

Show Sub-Attributes
errorJSON Object
Show Sub-Attributes
codestring
messagestring
detailsJSON Array
Show Sub-Attributes
object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. VOI_102 (invalid phone number), VOI_104 (caller id required), VOI_105 (template or message content required), VOI_106 (required merge tags missing), MTR_107 (template not found), VOI_207 (from number not associated with the sending agent), SERR_110 (required parameter missing), SERR_157 (invalid API token).

messagestring
targetstring

The field the detail refers to, when applicable (e.g. from, to, merge_info).

target_value

The offending value, or for VOI_106 the comma-separated list of missing merge tag names.

request_idstring

Identifier of the failed request, when available.

Sample Response: HTTP 200

Copied!
  {
    "data": {
      "code": "MSG_102",
      "message_id": "7ed0c6c0-b670-11f1-8810-3ed350183096",
      "message": "Message sent successfully",
      "request_id": "2d6f.14350939.v1.7ed0c6c0-b670-11f1-8810-3ed350183096.1a0c8a9dd2c"
    },
    "status": "success"
  }
                
▼ Show full

Sample Response: HTTP 400

Copied!
  {
    "error": {
      "code": "TM_3301",
      "details": [
        {
          "code": "SERR_110",
          "message": "Parameter less than min occurrance",
          "target": "to"
        }
      ],
      "message": "Bad Syntax"
    }
  }
                
▼ Show full

Sample Response: HTTP 401

Copied!
  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SERR_157",
          "message": "Invalid API Token found"
        }
      ],
      "message": "Access Denied"
    }
  }
                
▼ Show full

Sample Response: HTTP 403

Copied!
  {
    "error": {
      "code": "TM_3601",
      "details": [
        {
          "code": "VOI_207",
          "target_value": "14155550142",
          "message": "The from number is not associated with this mail agent",
          "target": "from"
        }
      ],
      "message": "Request Denied"
    }
  }
                
▼ Show full

Sample Response: HTTP 422

Template merge tags missing (missing tag names are listed in target_value)
Copied!
  {
    "error": {
      "code": "TM_3501",
      "details": [
        {
          "code": "VOI_106",
          "target_value": "customer_name, company_name, order_id, currency, amount",
          "message": "Required merge tag(s) missing in the request",
          "target": "merge_info"
        }
      ],
      "message": "Unprocessable Entity"
    }
  }
                
▼ Show full
Caller id (from) missing
Copied!
  {
    "error": {
      "code": "TM_3501",
      "details": [
        {
          "code": "VOI_104",
          "message": "Caller ID (from) is required",
          "target": "from"
        }
      ],
      "message": "Unprocessable Entity"
    }
  }
                
▼ Show full
Neither template nor message content provided
Copied!
  {
    "error": {
      "code": "TM_3501",
      "details": [
        {
          "code": "VOI_105",
          "message": "Either template key/alias or message content is required"
        }
      ],
      "message": "Unprocessable Entity"
    }
  }
                
▼ Show full
Unknown template
Copied!
  {
    "error": {
      "code": "TM_3501",
      "details": [
        {
          "code": "MTR_107",
          "message": "Template not found"
        }
      ],
      "message": "Unprocessable Entity"
    }
  }
                
▼ Show full
Caller id is not an approved voice number of the agent
Copied!
  {
    "error": {
      "code": "TM_3501",
      "details": [
        {
          "code": "VOI_102",
          "target_value": "919876500000",
          "message": "Invalid phone number",
          "target": "from"
        }
      ],
      "message": "Unprocessable Entity"
    }
  }
                
▼ Show full