NAV Navbar

en es pt

WhatsApp API

This documentation provides you with information for the integration with the ChatClub platform for sending and receiving messages through Wavy’s WhatsApp Integration, as well as information for receiving status notifications (CallBack - WebHook). The ChatClub platform allows sending WhatsApp single and bulk messages. The API has REST integration, using the HTTP protocol with TLS, supporting the POST method with parameters sent in JSON format.

User authentication

In order to successfully use our API, you are required to present a valid user name - or email - and the associated authentication token. While creating the request, you have to provide the following parameters on the headers:

Field Details Data Type
UserName Name or email valid for user identification on ChatClub. String
AuthenticationToken Authentication token generated by our platform. Find it here or consult the support. here String

Connection Details

Hostname api-messaging.movile.com
Port 443 (https)
Protocol HTTPS (TLS encryption)
Authentication username + token
Encoding UTF-8

Send Messages

Sending Text Messages

Image request example (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "image": {
                    "type": "JPG",
                    "url": "http://...jpg"
                }
            }
        }

Image request example (Base64)

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "image": {
                   "type": "JPG",
                   "data": "ZmlsZQ=="
               }
           }
       }

Audio request example (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "url": "http://...mp3"
                }
            }
        }

Audio request example (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "data": "ZmlsZQ=="
                }
            }
        }

Document request example (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "url": "http://...pdf"
                }
            }
        }

Document request example (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "data": "ZmlsZQ=="
                }
            }
        }

Allows messages to be sent through the WhatsApp platform to one or more recipients.

POST https://api-messaging.movile.com/v1/whatsapp/send

The request body must contain a JSON object with the following fields:

Field Required Details Type
destinations Yes List of recipients Destination[]
message Yes Text message that will be sent to the recipient list Message
flowId No Bot flow identification String
defaultExtraInfo No Additional data that identifies the submission will be linked to all recipients who will receive the message String
campaignAlias No Campaign ID, is linked to all sending messages String

Destination:

Field Required Details Type
correlationId No Your defined id will be returned in a confirmation message (callback). This is useful in cases where you want to keep track of the sent message, since you can define different ids for different messages. String
destination Yes Telephone number to which the message will be sent (country code (55 for Brazil) and state must be present).Examples:5519900001111, +5519900001111, +55(19) 900001111. String

Message:

Field Required Details Type
image Yes Field used for in case you want to send an image content. Image
audio Yes Field used for in case you want to send an audio content. Audio
document Yes Field used for in case you want to send an document file. Document

Image:

Field Required Details Type
type Yes Type/extention of the image to be sent in the message. Available options: JPG, JPEG, PNG. String
caption No Text to be presented to the user under the image in Whatsapp String
url Yes URL where the content to be sent is hosted. String
data Yes Base64 encoded content String

Audio:

Field Required Details Type
type Yes Type/extention of the audio to be sent in the message. Available options: AAC, MP4, AMR, MP3, OGG. String
url Yes URL where the content to be sent is hosted. String
data Yes Base64 encoded content String

Document:

Field Required Details Type
type Yes Type/extention of the document to be sent in the message. Available options: PDF. String
url Yes URL where the content to be sent is hosted. String
data Yes Base64 encoded content String

Sending HSM messages

HSM Request Example

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "hsm": {
                   "namespace": "namespace",
                   "elementName": "elementName",
                   "parameters":[
                       "MyParam1",
                       "MyParam2"
                   ]
               }
           }
       }

It is also possible to send message base in previously defined templates (also called HSM), with addition of placeholders (“parameters”). The request body must contain a JSON object with the following fields:

Field Required Details Type
destinations Yes List of recipients Destination[]
message Yes Text message that will be sent to the recipient list Message
flowId No Bot flow identification String
defaultExtraInfo No Additional data that identifies the submission will be linked to all recipients who will receive the message String
campaignAlias No Campaign ID, is linked to all sending messages String

Destination:

Field Required Details Type
correlationId No Your defined id will be returned in a confirmation message (callback). This is useful in cases where you want to keep track of the sent message, since you can define different ids for different messages. String
destination Yes Telephone number to which the message will be sent (country code (55 for Brazil) and state must be present).Examples:5519900001111, +5519900001111, +55(19) 900001111. String

Message:

Field Required Details Type
hsm Yes HSM message content. HSM

HSM:

Field Required Details Type
namespace Yes The namespace that will be used String
elementName Yes The element name that indicates which template to use within the namespace String
parameters Yes, if the message template has variables This field is an array of values to apply to variables in the template String[]
languagePolicy No Parameter that identifies how the HSM language will be selected. Available options:FALLBACK: When the HSM template does not have a version for the language to user’s device, the defined language will be used. DETERMINISTIC: The message will always be sent in the languageCode, regardless of the language the end user device is set to. String
languageCode Mandatory if languagePolicy is present Language code or locale, accepts both formats: language (en) or language_locale (pt_BR). To confirm all available languages ​​for a particular HSM, contact our Support team. String

Common HTTP Status Code Response

Successful request response (200)

{
 "Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "destinations": [{
  "id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "correlationId": "MyCorrelationId",
  "destination": "5519900001111."
}]
}

If successful, a list of recipients (“destinations”) with uuids generated from the application side is expected:

Authentication error response (401)

{
  "errorCode": 401,
  "errorMessage": "Authentication Error: No user was found with this combination of username and authentication token."
}

If there is a problem in user authentication, the following error message is expected:

Status Update Callback

Example

{
  "total": 1,
  "data": [
    {
      "id": "100",
      "correlationId": "100",
      "destination": "+5519900000000",
      "campaignId": 100,
      "campaignAlias": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "flowId": "...",
      "extraInfo": "xxxxx",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891
    }
  ]
}

Each update on the status of sent messages (delivery confirmation to the end user, message reading, etc.), a callback/webhook is sent. Callbacks are sent in batch.

IMPORTANT: The endpoint in which the webhook will be sent must be previously configured with the support / operations team.

The format of this return will be according to the following description:

Field Required Details Type
total Number of callbacks in the call. String
data Callback list. Data[]

Data:

Field Required Details Type
id Last message id. String
correlationId A unique ID set by you to match with the message status (callback and DLR). This parameter is optional, and you can use the ID generated by ChatClub for this matching. String
destination Phone to which the message was sent (including country code). Example: 5511900000000. String
campaignId Previously defined campaignID. String
campaignAlias Previously defined Campaign alias. String
extraInfo Extra information sent with the original message. String
sent Indicates whether the message was sent. Boolean
sentStatusCode Status code generated by the ChatClub for message indicating the sending status. Number
sentStatus Sent status description. Boolean
sentDate Date the message was sent. Format: yyyy-MM-dd’T'HH:mm:ssZ. String
sentAt Time when the message was sent, using Unix_time format Number
delivered Indicates whether the message was delivered to the destination. Boolean
deliveredStatusCode Status code generated by the ChatClub for message indicating the message was delivered. Number
deliveredStatus Delivery status description. String
deliveredDate Date the message was delivered. Format:: yyyy-MM-dd’T'HH:mm:ssZ String
deliveredAt Time when the message was delivered, using Unix_time format Number
read Indicates whether the message was read by the destination. Boolean
readDate Date the message was read. Format: yyyy-MM-dd’T'HH:mm:ssZ String
readAt Time when the message was read, using Unix_time format String
updatedDate Date the message status was updated. Format: yyyy-MM-dd’T'HH:mm:ssZ String
updatedAt Date when the message status was updated, using Unix_time format String

MO (messages send by the end user to the Whatsapp Account)

Text Message example:

{
  "total": 1,
  "data": [
    {
      "id": "100",
      "source": "+5519900000000",
      "campaignId": 100,
      "correlationId": "correlationId",
      "campaignAlias": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "TEXT",
"messageText": "Olá, essa é uma mensagem do usuário."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Media Message example

{
  "total": 1,
  "data": [
    {
      "id": "100",
      "source": "+5519900000000",
      "campaignId": 100,
      "correlationId":"correlationId",
      "campaignAlias":"ce425ffe-bc62-421f-9261-e6819a5eab43",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "IMAGE",
           "mediaUrl": "https://...",
           "mimeType": "image/jpg",
           "caption": "..."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Location message example:

{
  "total": 1,
  "data": [
    {
      "id": "100",
      "source": "+5519900000000",
      "campaignId": 100,
      "correlationId": "correlationId",
      "campaignAlias": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "LOCATION",
"location": "lat,lng"
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

At each end-user response (MO or Mobile Originated) a callback/webhook is sent. These MOs are sent in batch.

IMPORTANT: The endpoint in which the webhook will be sent must be previously configured with the support / operations team.

The format of this return will be according to the following description:

Field Details Type
total Number of callbacks in the call. String
data List of Mobile Originated messages. Data[]
Field Details Type
id Last message identification String
source ID of the sender String
correlationId A unique ID set by you to match with the message status (callback and DLR). This parameter is optional, and you can use the ID generated by ChatClub for this matching. String
campaignId Previously defined campaignID. String
campaignAlias Previously defined Campaign alias. String
message MO message. Message
receivedAt Date the message was received. Format: yyyy-MM-dd’T'HH:mm:ssZ String
receivedDate Date when the message was received, using Unix_time format String

Message:

type Type of message sent by the end user: TEXT - IMAGE - AUDIO - DOCUMENT
messageText The text message (MO) sent by the end user.
mediaUrl Url to download the media sent by the end user.
mimeType Mime type of the file sent by the end user.
caption Media label sent by end user.
location Location sent by end user. Format: “latitude,longitude”