The Send Messages API is part of Voiso's WhatsApp Digital Messages APIs. The API description is here.
To initiate WhatsApp messages for agents from external systems.
The Send Messages API requires the base URL (cluster_id) and the contact center API key (client_api_key). It uses the following parameters to initiate a call:
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| key | The Contact Center API key for authentication. | string | Required | |
| agent | The agent's contact center phone extension. | string | Required | This tells Voiso who should get the interaction assigned. |
| template_uuid | The unique identifier assigned to the message template. | string | Required | You can obtain a list of message template UUIDs using the List Templates API. |
| from | The originating WhatsApp phone number used by your contact center. | string | Required | The number must be specified in E.164 format without the preceding '+'. For example: 4407414992548. |
| recipients | An array of phone numbers and account IDs for the message recipients. | array | Required |
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| to | The WhatsApp phone number for the message recipient. | string | Required | Must be in E.164 format without the preceding ‘+’. |
| account_id | An identifier assigned to the contact in an external application such as a CRM. | string | Optional | Voiso uses the account ID in the Agent Panel, CDR, and other interfaces to mask the contact's WhatsApp phone number from your users. For information about masking, refer to Number Masking. |
| template_data | An array of data to be substituted for placeholders in the template. | array | Optional | Some templates include placeholders for variable values such as the contact name, OTP, account number, amount owing, and so on. The placeholders array contains a list of parameter values. If the template does not require any param, the template_data section can be omitted. |
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| body | An array of message parameter placeholders | array | Optional |
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| placeholders | A comma-separated list of parameters. | array | Placeholder parameters should be of type string. They are variable names for substitution content such as usernames, relevant numbers, or other custom content. There must be one placeholder value for each placeholder in the message template. Template parameters must be placed in the same order as provided in the template. The number of parameters must match the number required by the template. Empty values are permitted. |
With these parameters, you can make a POST request:
{
"method": "POST",
"url": "https://cluster1.voiso.com/api/v3/messages/whatsapp",
"headers": {
"Content-Type": "application/json"
},
"body": {
"key": "cc7c76b8987...fbb89b00ab6c3",
"agent": "1002",
"template_uuid": "b08a3464-587b-4d6d-8e46-b64f53ca0c64",
"from": "15053892577",
"recipients": [
{
"to": "15555564236",
"account_id": "AC001",
"template_data": {
"body": {
"placeholders": [
"parameter1",
"parameter2",
"parameterX"
]
}
}
},
{
"to": "15555578910",
"account_id": "AC002",
"template_data": {
"body": {
"placeholders": [
"parameter1",
"parameter2",
"parameterX"
]
}
}
}
]
}
}
A status object is returned if the message is sent successfully. The following table describes the elements of the status object.
| Element | Description | Type | Notes |
|---|---|---|---|
| to | The phone number of the WhatsApp user. | string | |
| success | An indication of whether the message was successfully delivered to the recipient. | Boolean | Values are true and false |
| uuid | The unique ID associated with the interaction stored in the Call Details Record (CDR). | string | You can use this ID to get information about the call using the CDR API. |
{
"status": [
{
"to": "155555555555",
"success": true,
"uuid": "1f2a3a7f-8b42-42d4-aab6-9f9d03b285a8"
}
]
}
The following issues are sometimes encountered:
The Send Messages API requires the contact center API key to validate the request. If you see this error, "error": "The API key specified is invalid", check that you are using the correct contact center API key. For more information about API keys, refer to Authentication.
If you see this error, "error": "Invalid destination", it means that the outbound phone number is not in E.164 format, the number does not exist, or the number is not associated with a WhatsApp account.
If you see this error, "error": "Provide at least one destination number", it means you have not specified any recipient phone numbers in the request.
If you see this error, "error": "The agent settings for the requested sending are incorrect", it means the agent specified by the agent extension is not configured correctly to handle WhatsApp interactions. Refer to the Prerequisites above.
If you see this error, "error": "Invalid agent extension", it means the specified agent phone extension does not exist in your contact center.
If you see this error, "Parameter mismatch: the specified template requires x parameters, but request contains y parameters.", it means that you have not specified the number of parameters requried by the template. You must specify the correct number of parameters in the placeholders parameter array, in the correct order required by the template. Empty values are permitted, but total number of parameters must match the number required in template. If the template does not require any parameters, the template_data section can be omitted.
If you see this error, "error": "The message to this destination already exists", it means the message has already been sent to the recipient by another user (agent).
If you see this error, "error": "Rate limit exceeded", the number of permitted requests to the server is exceeded, and requests are being throttled.
If you see this error, "error": "Invalid sender", the message sender is not one of the previously created WhatsApp numbers. For more information, refer to Enabling WhatsApp outbound messaging.
If you see this error, "error": "Invalid message template UUID", the unique ID assigned to the message template does not exist. You can obtain a list of message template UUIDs using the List Templates API.
If you see this error, "error": "Invalid 'template_uuid' for specified 'from' option", the unique ID assigned to the message template is not associated with the sender phone number. You can obtain a list of message template UUIDs and their corresponding sender phone numbers using the List Templates API.
If you see this error, The WhatsApp Outbound Messaging is disabled for your contact center. Please contact support@voiso.com to enable this function, you do not have the WhatsApp outbound messaging feature enabled for your contact center. For more information, refer to Enabling WhatsApp outbound messaging.
Was this page helpful?
Back to top