Send Message API

Use the Messaging API to integrate WhatsApp's messaging capabilities into your business systems.
Before calling the API, log on to the console API key create a key on the page.

Call address

POST https://wa.api.engagelab.cc/v1/messages

Call validation

The EngageLab REST API uses HTTP Basic Authentication as the authentication method, adding Authorization in the HTTP Header.

Authorization: Basic ${base64_auth_string}

          Authorization: Basic ${base64_auth_string}

This code block in the floating window

The preceding base64_auth_string generation algorithm is as follows: base64(dev_key:dev_secret)

the Header name is "Authorization" and the value is a base64-converted "username:password" pair (with a colon in the middle).
In WhatsApp API scenario, username is DevKey and password is DevSecret. In the console, choose configuration management- API key obtain the page.

Sample Requests

Request Header

POST /v1/messages HTTP/1.1 Content-Type: application/json Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

          POST /v1/messages  HTTP/1.1 
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

This code block in the floating window

Request body

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "code", "language": "zh_CN", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "12345" } ] } ] } }, "request_id": "123asdbbqwe9faweg", "custom_args": { "arg1": "string val", "arg2": 123 } }

          {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {
            "name": "code",
            "language": "zh_CN",
            "components": [
                {
                    "type": "body",
                    "parameters": [
                        {
                            "type": "text",
                            "text": "12345"
                        }
                    ]
                }
            ]
        }
    },
    "request_id": "123asdbbqwe9faweg",
    "custom_args": {
        "arg1": "string val",
        "arg2": 123
    }
}

This code block in the floating window

Request parameters

A request object is expressed in JSON format, so the request header must contain Content-Type: application/json.

Parameter	Type	Option	Description
from	String	optional	sending number
to	String Array	required	the phone number of the target.
body	JSON Object	required	message body
request_id	String	optional	the ID of the custom request that identifies the request.
custom_args	JSON Object	optional	the custom information is returned to the developer in the message status callback.

from

Parameter	Type	Option	Description
from	String	optional	the sending number, that is, the enterprise phone number used to send messages. You need to add the international area code. If you do not specify it, use the default sending number (required configure in the console )

to

Parameter	Type	Option	Description
to	String Array	required	the WhatsApp phone number of the target, and the international area code must be added.

body

A message body that contains the following fields:

Parameter	Type	Option	Description
type	string	required	the message type. Valid values: template: template Message text: text message image: image message audio: audio message video: a video message. document: document message sticker: sticker message only template messages can be sent to users., other types of messages require users to reply to messages within 24 hours before they can be delivered. Images, audio, video, documents, and stickers are all media messages. Media Message Format requirements
template	template object	optional	used when type = template. For more information, see template object description
text	text object	optional	used when type = text. For more information, see text object description
image	image object	optional	used when type = image. For more information, see image object description
audio	audio object	optional	used when type = audio. For more information, see audio object description
video	video object	optional	used when type = video. For more information, see video object description
document	document object	optional	Used when type = document. For more information, see document object description
sticker	sticker object	optional	used when type = sticker. For more information, see sticker object description

text object description

text message

Parameter	Type	Option	Description
body	String	required	the text content. The WhatsApp must be no more than 4096 characters/character.

Example

{ "from": "8613800138000", //sender's phone number "to": "8613800138000", //the recipient's phone number "body": { "type": "text", //type of message "text": { "body": "your-text-message-content" // message content } } }

          {
    "from": "8613800138000", //sender's phone number
    "to": "8613800138000", //the recipient's phone number
    "body": {
        "type": "text", //type of message
        "text": {
            "body": "your-text-message-content" // message content
        }
    }
}

This code block in the floating window

image object description

image message

Parameter	Type	Option	Description
id	String	optional	the id and link generated by the WhatsApp must have a value.
link	String	optional	image link, http/https link, follow media Message Format requirements
caption	String	optional	the description of the image. It cannot exceed 1024 characters in length.

Example

{ "from": "8613800138000",//the sender's phone number "to": "8613800138000",//receiver's phone number "body": { "type": "image",//the message type "image": { "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //image link "caption": "caption info" // optional, text description below the image, within 1024 characters } } }

          {
  "from": "8613800138000",//the sender's phone number
  "to": "8613800138000",//receiver's phone number
    "body": {			
            "type": "image",//the message type
            "image": {
                "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //image link
        "caption": "caption info" // optional, text description below the image, within 1024 characters
            }
    }
}

This code block in the floating window

video object description

video message

Parameter	Type	Option	Description
id	String	optional	WhatsApp generated media_id; Both id and link must have a value.
link	String	optional	video link, http/https link, follow media Message Format requirements
caption	String	optional	Description of the video , up to 1024 characters in length.

Example

{ "from": "8613800138000",//the sender's phone number "to": "8613800138001", //the recipient's phone number "body": { "type": "video",//the message type "video": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //video link "caption": "caption info" // optional, text description below the video, within 1024 characters } } }

          {
  "from": "8613800138000",//the sender's phone number
  "to": "8613800138001", //the recipient's phone number
    "body": {			
            "type": "video",//the message type
            "video": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //video link
        "caption": "caption info" // optional, text description below the video, within 1024 characters
            }
    }
}

This code block in the floating window

audio object description

audio message

Parameter	Type	Option	Description
id	String	optional	WhatsApp generated media_id; Both id and link must have a value.
link	String	optional	audio link, http/https link, follow media Message Format requirements

Example

{ "from": "8613800138000",//the sender's phone number "to": "8613800138001", //the recipient's phone number "body": { "type": "audio",//the message type "audio": { "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //audio link } } }

          {
  "from": "8613800138000",//the sender's phone number
  "to": "8613800138001", //the recipient's phone number
    "body": {
            "type": "audio",//the message type
            "audio": {
                "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //audio link
            }
    }
}

This code block in the floating window

document object description

file message

Parameter	Type	Option	Description
id	String	optional	WhatsApp generated media_id; Both id and link must have a value.
link	String	optional	document link, http/https link, follow media Message Format requirements
caption	String	optional	Description of the file , up to 1024 characters in length.
filename	String	optional	The name of the file. If the filename field is not filled in but the caption field is filled in, the caption will be used as the file name; if filename is filled in, the value of filename will be used as the file name.

Example

{ "from": "8613800138000",//the sender's phone number "to": "8613800138001", //the recipient's phone number "body": { "type": "document",//the message type "document": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", // document link "caption": "caption info", // optionally, the text description at the bottom of the document, within 1024 characters "filename": "document file name" // optional, the name of the file } } }

          {
  "from": "8613800138000",//the sender's phone number
  "to": "8613800138001", //the recipient's phone number
    "body": {
            "type": "document",//the message type
            "document": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", // document link
        "caption": "caption info", // optionally, the text description at the bottom of the document, within 1024 characters
        "filename": "document file name" // optional, the name of the file
            }
    }
}

This code block in the floating window

sticker object description

Sticker message

Parameter	Type	Option	Description
id	String	optional	media_id on the whatsapp side; Both id and link must have a value.
link	String	optional	sticker link, http/https link, follow media Message Format requirements

Example

{ "from": "8613800138000",//the sender's phone number "to": "8613800138001", //the recipient's phone number "body": { "type": "sticker",//the message type "sticker": { "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //sticker link } } }

          {
  "from": "8613800138000",//the sender's phone number
  "to": "8613800138001", //the recipient's phone number
    "body": {
            "type": "sticker",//the message type
            "sticker": {
                "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //sticker link
            }
    }
}

This code block in the floating window

template object description

template message, you need to create a template first, you can console operations or create an API .

Parameter	Type	Type	Description
name	String	required	the name of the template. You can find it on the message templates page in the console. Only lowercase numbers and underscores are supported.
language	String	required	template language code . When creating a template, you can set the content of the same template name in multiple languages. Therefore, you need to use the name and language fields to determine the selected template.
components	components-object array	optional	if a variable exists in the template, you need to fill this field. Only one components object element is set in the array.

template.components object description

Parameter	Type	Option	Description
type	String	required	the template component. Which component in the template contains variables, you need to pass the value to the component. Valid values: header: header body: body footer: footer button: button
parameters	parameters object	required	set variable content

template.components.parameters object description

Parameter	Type	Option	Description
type	string	required	the type of the variable. Valid values: text, currency, date_time, image, video, and document. Multimedia material types (image, video, and document) only exist in the header. For more information about the supported formats, see media Message Format requirements .
text	string	optional	When type = text, it is the specific content of the variable.
date_time	localizable object	optional	Used when type = date_time, the difference with text is that it can be localized and adapted to display
currency	localizable object	optional	used when type = currency, the difference with text is that it can be localized and adapted to display
image	image object	optional	used when type = image, and image object the content format is consistent.
video	video object	optional	Used when type = video, and video object the content format is consistent.
document	document object	optional	Used when type = document, and document object the content format is consistent.

Example

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "your-template-name", "language": "zh_CN", "components": [ { "type" : "header", "parameters": [{ "type": "document", "document": { "link": "http(s)://the-url", "filename": "your-document-filename" } }] }, { "type": "body", "parameters": [ { "type": "text", "text": "your-text-string" }, { "type": "currency", "currency": { "fallback_value": "$100.99", "code": "USD", "amount_1000": 100990 } }, { "type": "date_time", "date_time": { "fallback_value": "February 25, 1977", "day_of_week": 5, "day_of_month": 25, "year": 1977, "month": 2, "hour": 15, "minute": 33 } }, { "type": "date_time", "date_time": { "fallback_value": "February 25, 1977", "timestamp": 1485470276 } } ] } ] } } }

          {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {          
            "name": "your-template-name",
                        "language": "zh_CN",
            "components": [
              {
                "type" : "header",
                "parameters": [{
                         "type": "document",
                         "document": {
                             "link": "http(s)://the-url",
                             "filename": "your-document-filename"
                       }
                }]
              },
              {
                 "type": "body",
                 "parameters": [
                        {
                            "type": "text",
                            "text": "your-text-string"
                        },
                        {
                            "type": "currency",
                            "currency": {
                                "fallback_value": "$100.99",
                                "code": "USD",
                                "amount_1000": 100990
                            }
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "February 25, 1977",
                                "day_of_week": 5,
                                "day_of_month": 25,
                                "year": 1977,
                                "month": 2,
                                "hour": 15,
                                "minute": 33
                            }
                        },
                        {
                            "type": "date_time",
                            "date_time": {
                                "fallback_value": "February 25, 1977",
                                "timestamp": 1485470276
                            }
                        }
                    ]
                }
            ]
        }
    }
}

This code block in the floating window

Response parameters

Success response

Field	Type	Option	Description
message_id	String	required	the ID of the EngageLab WhatsApp message that uniquely identifies a message.
request_id	String	optional	the custom ID submitted during the request. The ID is returned as it is when the request is received.

{ "message_id": "cbggf4if6o9ukqaalfug", "request_id": "your-sendno-string" }

          {
    "message_id": "cbggf4if6o9ukqaalfug",
    "request_id": "your-sendno-string"
}

This code block in the floating window

Failed response

the http status code is 4xx or 5xx. The response body contains the following fields:

Field	Type	Option	Description
code	int	required	the error code. For more information, see error Codes description
message	String	required	error details

{ "code": 3002, "message": "whatsapp.template field must be set correctly when type is template" }

          {
    "code": 3002,
    "message": "whatsapp.template field must be set correctly when type is template"
}

This code block in the floating window

Error Codes

Error Codes	Http Code	Description
1000	500	internal error
2001	401	EngageLab authentication failed without a valid token.
2002	401	EngageLab-side authentication failed. The token has expired or has been disabled.
2003	400	WhatsApp authentication failed, please contact EngageLab customer service
2004	403	you do not have the permission to call this API. Check whether you have the permission to send messages (a sending number) to this API key.
3001	400	The request parameter format is invalid. Check whether the JSON format is used.
3002	400	The request parameters are incorrect. Check whether the request parameters meet the requirements.
3003	400	The error message returned because the request parameter is invalid. For more information, see the error description of the message field.
4001	400	The relevant resource does not exist. For example, a template that does not exist is used when the template message is sent.

Comments

media Message Format requirements

Media Type	Supported format types Content-Type	Size Limit
image	image/jpeg, image/png, does not support transparent background	5MB
video	video/mp4 , video/3gpp note: encoding only supports H.264 video encoding and AAC audio encoding.	16MB
audio	audio/aac, audio/mp4, audio/amr, audio/mpeg audio/ogg; codecs = opus (note: basic audio/ogg is not supported, only audio/ogg is supported; codecs = opus)	16MB
document	1. Any MIME-type type is supported when sending file messages. 2. When sending a template message, the file in the header only supports PDF format.	100MB
sticker	image/webp	Static stickers:100KB Animated stickers: 500KB

Language code

for more information about the relationship between the language and the corresponding code, download this file:
Template language code.xlsx