Sends a WhatsApp message

Sends a single WhatsApp message to a single recipient. The message content comes from a pre-approved WhatsApp template, addressed by template_key or template_alias; The message content is based on the merge_info which provides the values for the template placeholders. from must be a valid WhatsApp sender number configured for the sending agent. Both from and to must include the country code.

The message is queued on acceptance; template-variable and delivery failures surface asynchronously in the message logs (for example, a send with missing template variables is accepted but ends in the process_failed status).

Endpoint

post /whatsapp

Copy full URL

Request URL

https://cpaas.zoho.com/v1.1/whatsapp 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.

- Path Parameters

message_iduuidMandatory

Unique identifier of the SMS message, as returned by the send API (data.message_id) or the logs API.

- Request Body

application/json

JSON Object

Request body for sending a WhatsApp message. Provide exactly one of template_key / template_alias; the template supplies the message content.

Show Sub-Attributes

fromstring(length <= 20)Mandatory

WhatsApp sender number of the agent, including the country code.

Maximum Length :20Copied!

tostring(length <= 20)Mandatory

Recipient phone number, including the country code.

Maximum Length :20Copied!

template_keyuuid(length <= 500)Optional

Key of a pre-approved WhatsApp template. Provide this or template_alias.

Maximum Length :500Copied!

template_aliasstring(length <= 100)Optional

Alias of a pre-approved WhatsApp template. Provide this or template_key.

Maximum Length :100Copied!

merge_infoJSON ObjectOptional

Key-value map that supplies the template's variables. A message with missing variable values is accepted but fails asynchronously with the process_failed status.

agent_idstringOptional

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

client_referencestring(length <= 100)Optional

Client-supplied reference identifier, echoed in the message logs.

Maximum Length :100Copied!

Sample Request

Curl

Java

Python

Deluge

Copied!

curl --request POST \
  --url https://cpaas.zoho.com/v1.1/whatsapp \
  --header 'Authorization: REPLACE_KEY_VALUE' \
  --header 'content-type: application/json' \
  --data '{"from":"+14155550142","to":"+919876543210","template_key":"d0109d00-b191-11f1-95b1-aaa8828ce996","merge_info":{"code":"234234"},"client_reference":"otp-234234"}'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://cpaas.zoho.com/v1.1/whatsapp"))
        .header("content-type", "application/json")
        .header("Authorization", "REPLACE_KEY_VALUE")
        .method("POST", HttpRequest.BodyPublishers.ofString("{\"from\":\"+14155550142\",\"to\":\"+919876543210\",\"template_key\":\"d0109d00-b191-11f1-95b1-aaa8828ce996\",\"merge_info\":{\"code\":\"234234\"},\"client_reference\":\"otp-234234\"}"))
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("cpaas.zoho.com")

payload = "{\"from\":\"+14155550142\",\"to\":\"+919876543210\",\"template_key\":\"d0109d00-b191-11f1-95b1-aaa8828ce996\",\"merge_info\":{\"code\":\"234234\"},\"client_reference\":\"otp-234234\"}"

headers = {
    'content-type': "application/json",
    'Authorization': "REPLACE_KEY_VALUE"
    }

conn.request("POST", "/v1.1/whatsapp", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Authorization", "REPLACE_KEY_VALUE");
    headersMap.put("Content-Type", "application/json");
    headersMap.put("Accept", "application/json");

    data=Map();
    data.put("from","+14155550142");
    data.put("to","+919876543210");
    data.put("template_key","d0109d00-b191-11f1-95b1-aaa8828ce996");
    data.put("template_alias","value");
    data_merge_info=Map();
    data.put("merge_info",data_merge_info);
    data.put("agent_id","value");
    data.put("client_reference","otp-234234");

    response = invokeUrl
    [
        url: "https://cpaas.zoho.com/v1.1/whatsapp"
        type: POST
        headers: headersMap
        body: data
        connection: connection_name
    ]

    info response;

Sample Request Body

Template message with merge values

Copied!

  {
    "from": "+14155550142",
    "to": "+919876543210",
    "template_key": "d0109d00-b191-11f1-95b1-aaa8828ce996",
    "merge_info": {
      "code": "234234"
    },
    "client_reference": "otp-234234"
  }

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Success response returned when the WhatsApp message is queued for delivery.

Show Sub-Attributes

dataJSON Object

Show Sub-Attributes

codestring

Acceptance code.

message_iduuid

Unique identifier of the message. Use it with the message-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_3201 mandatory field missing (400), TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403).

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. SERR_110 (required parameter missing), GE_102 (mandatory field missing), WA_103 (invalid template), WSE_107 (sender number belongs to a different agent), SERR_157 (invalid API token).

messagestring

targetstring

The field the detail refers to, when applicable (e.g. from, to, template_key | template_alias).

target_value

The offending value, when applicable.

request_idstring

Identifier of the failed request, when available.

- HTTP code 401

Response Body - application/json

JSON Object

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

messagestring

targetstring

The field the detail refers to, when applicable (e.g. from, to, template_key | template_alias).

target_value

The offending value, when applicable.

request_idstring

Identifier of the failed request, when available.

- HTTP code 403

Response Body - application/json

JSON Object

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

messagestring

targetstring

The field the detail refers to, when applicable (e.g. from, to, template_key | template_alias).

target_value

The offending value, when applicable.

request_idstring

Identifier of the failed request, when available.

Sample Response: HTTP 200

Copied!

  {
    "data": {
      "code": "MSG_101",
      "message_id": "1ba7d8d0-b680-11f1-91b5-d2a30e0412c2",
      "message": "Message queued",
      "request_id": "2d6f.14350939.wa1.1ba7d8d0-b680-11f1-91b5-d2a30e0412c2.1a0c9102edd"
    },
    "status": "success"
  }

▼ Show full

Sample Response: HTTP 400

to missing

Copied!

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

▼ Show full

Neither template_key nor template_alias provided

Copied!

  {
    "error": {
      "code": "TM_3201",
      "details": [
        {
          "code": "GE_102",
          "message": "Mandatory field found empty",
          "target": "template_key | template_alias"
        }
      ],
      "message": "Mandatory Field missing"
    }
  }

▼ Show full

Sample Response: HTTP 401

Invalid API token

Copied!

  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SERR_157",
          "message": "Invalid API Token found"
        }
      ],
      "message": "Access Denied"
    }
  }

▼ Show full

Template not valid for the sending agent

Copied!

  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "WA_103",
          "message": "whatsapp.api.template.not.valid"
        }
      ],
      "message": "Access Denied"
    }
  }

▼ Show full

Sample Response: HTTP 403

Copied!

  {
    "error": {
      "code": "TM_3601",
      "details": [
        {
          "code": "WSE_107",
          "target_value": "+14155550142",
          "message": "whatsapp.sender.sender.added.different.agent",
          "target": "from"
        }
      ],
      "message": "Request Denied"
    }
  }

▼ Show full