API OverviewDigital Messages

Send messages
#

Send WhatsApp Messages
#

The Send Messages API is part of Voiso's WhatsApp Digital Messages APIs. The API description is here.

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:

The key parameter is the Contact Center API key. for your contact center.

The optional agent parameter is the agent's extension. This tells Voiso who should get the interaction assigned.

The template_uuid parameter is the unique ID assigned to the message template to be sent. You can obtain a list of message template UUIDs using the List Templates API.

The from parameter is the originating phone number for your contact center's WhatsApp account.

The number must be specified in E.164 format without the preceding '+'. For example: 4407414992548

The recipients parameter refers to an object of type recipient. The recipients object includes a to parameter, which is the recipient's phone number, and an optional account_id parameter, which is an ID you have associated with the contact from your CRM or other external database.

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

With these parameters, you can make a cURL POST request:


POST https://cluster1.voiso.com/api/v3/messages/whatsapp

Request body: 
{
  "key": "cc7c76b8987...fbb89b00ab6c3",
  "agent": "1002",
  "template_uuid": "b08a3464-587b-4d6d-8e46-b64f53ca0c64",
  "from": "15053892577",
  "recipients":
      [
          {
              "to": "15555564236", "account_id": "AC001"
          },
          {
              "to": "15555578910", "account_id": "AC002"
          }
      ]
}

Note: you may have multiple recipients parameters.

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.

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