Send messages description

Please refer to the detailed API endpoint specification: Send messages

Purpose

To initiate WhatsApp messages for agents from external systems.

Prerequisites

Your contact center must have the Omnichannel feature enabled.
Your contact center must have WhatsApp Outbound Messaging enabled by your Voiso account manager.
Your contact center must have a WhatsApp business account with a phone number acting as a sending ID.
Your contact center must have at least one approved WhatsApp message template. You can obtain the UUIDs of your message templates using the List Templates API. Each template must be associated with an approved WhatsApp phone number sender ID.
You must have access to your contact center API key.
The agent should be a user in your contact center and have an extension configured.
You must configure your contact center Omnichannel settings.
Omnichannel Workspace Enabled must be enabled for the agent's security access group.
The WhatsApp channel must be assigned to the agent's profile and a WhatsApp channel must be assigned. For more information, refer to Enabling WhatsApp outbound messaging.
One or more valid WhatsApp user phone numbers.

Making requests

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

Recipients array

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.

Template data array

Parameter	Description	Type	Required	Notes
body	An array of message parameter placeholders	array	Optional

Body array

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"
            ]
          }
        }
      }
    ]
  }
}

Response

If the message is sent successfully, a status object is returned. 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.

Response sample

{
    "status": [
        {
            "to": "155555555555",
            "success": true,
            "uuid": "1f2a3a7f-8b42-42d4-aab6-9f9d03b285a8"
        }
    ]
}

Troubleshooting

The following issues are sometimes encountered:

The API key specified is invalid

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.

Invalid destination

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.

Provide at least one destination number

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.

The agent settings for the requested sending are incorrect

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.

Invalid agent extension

If you see this error, "error": "Invalid agent extension", it means the specified agent phone extension does not exist in your contact center.

Parameter mismatch

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.

The message to this destination already exists

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

API rate limit exceeded

If you see this error, "error": "Rate limit exceeded", the number of permitted requests to the server is exceeded, and requests are being throttled.

Invalid sender

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.

Invalid message template UUID

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.

Invalid 'template_uuid' for specified 'from' option

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.

The WhatsApp Outbound Messaging is disabled

If you see this error, The WhatsApp Outbound Messaging is disabled for your contact center. Please contact [email protected] 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.