消息发送 API

使用消息发送 API 可以将 WhatsApp 的消息发送能力集成到你的业务系统中。
在调用 API 之前，请先在控制台 API 密钥页面创建密钥。

调用地址

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

调用验证

EngageLab REST API 采用 HTTP 基本认证的验证方式：HTTP Header（头）里加 Authorization：

Authorization: Basic ${base64_auth_string}

          Authorization: Basic ${base64_auth_string}

此代码块在浮窗中显示

上述 base64_auth_string 的生成算法为：base64(dev_key:dev_secret)

Header 名称是 "Authorization"，值是 base64 转换过的 "username:password" 对（中间有个冒号）。
在 WhatsApp API 的场景里，username 是 DevKey，password 是 DevSecret。请在控制台-配置管理- API 密钥页面获取。

请求示例

请求头

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

此代码块在浮窗中显示

请求体

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

此代码块在浮窗中显示

请求参数

一个请求对象以 JSON 格式表达，因此请求头需要带 Content-Type: application/json 。

参数	类型	选项	说明
from	String	选填	发送号
to	String Array	必填	发送目标的电话号码
body	JSON Object	必填	消息体
request_id	String	选填	自定义的请求 ID，用来标识是哪条请求，响应时返回。
custom_args	JSON Object	选填	自定义的信息，在消息状态回调中返回给开发者。

from

参数	类型	选项	说明
from	String	选填	发送号，即用于发送消息的企业电话号码。需要加上国际区号，未填写时使用默认发送号（需要在控制台配置）

to

参数	类型	选项	说明
to	String Array	必填	发送目标的 WhatsApp 电话号码，需要加上国际区号

body

一个消息体，包含的字段如下：

参数	类型	选项	说明
type	string	必填	消息类型，目前支持： template：模板消息 text：文本消息 image：图片消息 audio：音频消息 video：视频消息 document：文档消息 sticker：贴纸消息仅 template 消息才能主动发送给用户，其余类型的消息要求用户在 24 小时内回复过消息，才能被送达。其中图片/音频/视频/文档/贴纸皆为媒体消息，注意遵循媒体消息格式要求。
template	template object	可选	当 type=template 时使用，详见 template object 说明。
text	text object	可选	当 type=text 时使用，详见 text object 说明
image	image object	可选	当 type=image 时使用，详见 image object 说明。
audio	audio object	可选	当 type=audio 时使用，详见 audio object 说明。
video	video object	可选	当 type=video 时使用，详见 video object 说明。
document	document object	可选	当 type=document 时使用，详见 document object 说明。
sticker	sticker object	可选	当 type=sticker 时使用，详见 sticker object 说明。

text object 说明

文本消息

参数	类型	选项	说明
body	String	必填	文本内容，WhatsApp 要求不超过 4096 个字符/character

示例

{ "from": "8613800138000", //发送方的电话号码 "to": ["8613800138000"], //收件人的电话号码 "body": { "type": "text", //消息类型 "text": { "body": "your-text-message-content" //消息内容 } } }

          {
    "from": "8613800138000", //发送方的电话号码
    "to": ["8613800138000"], //收件人的电话号码
    "body": {
        "type": "text", //消息类型
        "text": {
            "body": "your-text-message-content" //消息内容
        }
    }
}

此代码块在浮窗中显示

image object 说明

图片消息

参数	类型	选项	说明
id	String	可选	WhatsApp 生成的 media_id ；id 和 link 其一必须有值。
link	String	可选	图片链接，http/https 链接，注意遵循媒体消息格式要求。
caption	String	可选	对图片的描述，不超过 1024 个字符。

示例

{ "from": "8613800138000",//发送方的电话号码 "to": ["8613800138000"], //收件人的电话号码 "body": { "type": "image",//消息类型 "image": { "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //图片链接 "caption": "caption info" // 可选，图片下方的文本描述，1024个字符内 } } }

          {
    "from": "8613800138000",//发送方的电话号码
    "to": ["8613800138000"], //收件人的电话号码
    "body": {			
            "type": "image",//消息类型
            "image": {
                "link": "https://img.jiguang.cn/jiguang/public/img/c866bd2.png", //图片链接
        "caption": "caption info"   // 可选，图片下方的文本描述，1024个字符内
            }
    }
}

此代码块在浮窗中显示

video object 说明

视频消息

参数	类型	选项	说明
id	String	可选	WhatsApp 生成的 media_id ；id 和 link 其一必须有值。
link	String	可选	视频链接，http/https 链接，注意遵循媒体消息格式要求。
caption	String	可选	对视频的描述，不超过 1024 个字符。

示例

{ "from": "8613800138000",//发送方的电话号码 "to": ["8613800138000"], //收件人的电话号码 "body": { "type": "video",//消息类型 "video": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //视频链接 "caption": "caption info" // 可选，视频下方的文本描述，1024个字符内 } } }

          {
    "from": "8613800138000",//发送方的电话号码
    "to": ["8613800138000"], //收件人的电话号码
    "body": {			
            "type": "video",//消息类型
            "video": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //视频链接
        "caption": "caption info"   // 可选，视频下方的文本描述，1024个字符内
            }
    }
}

此代码块在浮窗中显示

audio object 说明

音频消息

参数	类型	选项	说明
id	String	可选	WhatsApp 生成的 media_id ；id 和 link 其一必须有值。
link	String	可选	音频链接，http/https 链接，注意遵循媒体消息格式要求。

示例

{ "from": "8613800138000",//发送方的电话号码 "to": ["8613800138000"], //收件人的电话号码 "body": { "type": "audio",//消息类型 "audio": { "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //音频链接 } } }

          {
    "from": "8613800138000",//发送方的电话号码
    "to": ["8613800138000"], //收件人的电话号码
    "body": {
            "type": "audio",//消息类型
            "audio": {
                "link": "https://file-examples.com/storage/fe5947fd2362fc197a3c2df/2017/11/file_example_MP3_700KB.mp3" //音频链接
            }
    }
}

此代码块在浮窗中显示

document object 说明

文件消息

参数	类型	选项	说明
id	String	可选	WhatsApp 生成的 media_id ；id 和 link 其一必须有值。
link	String	可选	文档链接，http/https 链接，注意遵循媒体消息格式要求。
caption	String	可选	对文件的描述，不超过 1024 个字符。
filename	String	可选	文件名称。若未填写`filename`字段而填写了`caption`字段，则会以`caption`作为文件名；若填写了`filename`则会以`filename`的值作为文件名。

示例

{ "from": "8613800138000",//发送方的电话号码 "to": ["8613800138000"], //收件人的电话号码 "body": { "type": "document",//消息类型 "document": { "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //文件链接 "caption": "caption info", // 可选，文件下方的文本描述，1024个字符内 "filename": "document file name" // 可选，文件名称 } } }

          {
    "from": "8613800138000",//发送方的电话号码
    "to": ["8613800138000"], //收件人的电话号码
    "body": {
            "type": "document",//消息类型
            "document": {
                "link": "https://img.jiguang.cn/jiguang/public/videos/432acc5.mp4", //文件链接
        "caption": "caption info",   // 可选，文件下方的文本描述，1024个字符内
        "filename": "document file name"    // 可选，文件名称
            }
    }
}

此代码块在浮窗中显示

sticker object 说明

贴纸消息

参数	类型	选项	说明
id	String	可选	whatsapp 侧的 media_id ；id 和 link 其一必须有值。
link	String	可选	贴纸链接，http/https 链接，注意遵循媒体消息格式要求。

示例

{ "from": "8613800138000",//发送方的电话号码 "to": ["8613800138000"], //收件人的电话号码 "body": { "type": "sticker",//消息类型 "sticker": { "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //贴纸链接 } } }

          {
    "from": "8613800138000",//发送方的电话号码
    "to": ["8613800138000"], //收件人的电话号码
    "body": {
            "type": "sticker",//消息类型
            "sticker": {
                "link": "http://sample-file.bazadanni.com/download/images/webp/sample.webp" //贴纸链接
            }
    }
}

此代码块在浮窗中显示

template object 说明

模板消息，需要先创建模板，可以在控制台操作或调用 API 创建。

参数	类型	类型	说明
name	String	必填	模板名称。可以在控制台-消息模板页面找到，仅支持小写数字及下划线。
language	String	必填	模板语言代码。创建模板时对同一个模板名称可以设置多个语言的内容，因此发送时需要使用 name 和 language 字段共同决定所选模板。
components	components-object array	可选	当模板中存在可变变量时，需要填充此字段，数组中仅设置 1 个 components 对象元素即可。

template.components object 说明

参数	类型	选项	说明
type	String	必填	模板组件，模板中哪一个组件包含变量，就需要对该组件传值，取值： header：页眉 body：正文 footer：页脚 button：按钮
parameters	parameters object	必填	设置可变变量内容

template.components.parameters object 说明

参数	类型	选项	说明
type	string	必填	变量内容的类型，取值 text、currency、date_time、image、video、document。多媒体素材类型（image、video、document）仅在页眉（header）中存在，素材支持的格式请参考媒体消息格式要求。
text	string	可选	当 type=text 时使用，为可变变量的具体内容
date_time	localizable object	可选	当 type=date_time 时使用，与 text 区别在于可本地化适配显示。
currency	localizable object	可选	当 type=currency 时使用，与 text 区别在于可本地化适配显示。
image	image object	可选	当 type=image 时使用，与 image object 内容格式一致。
video	video object	可选	当 type=video 时使用，与 video object 内容格式一致。
document	document object	可选	当 type=document 时使用，与 document object 内容格式一致。

示例

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

此代码块在浮窗中显示

身份验证类别的特别说明

对于身份验证类别（即 category 为 AUTHENTICATION）的模版消息，按照 WhatsApp 最新的规则（2023/06/01），创建/编辑身份验证类别的模版时，提交的模版字段，与 WhatsApp 侧最终生成的模版字段，是不一致的（具体参考创建/编辑模版 API 文档说明），故针对身份验证类别的模版消息下发，除了 BODY 需要传变量外，BUTTON 也需要传变量，且变量值需一致。

{ "from": "+8613800138000", "to": [ "00447911123456" ], "body": { "type": "template", "template": { "name": "your-template-name", "language": "zh_CN", "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "123456" } ] }, // 需要添加 button 变量值，本质上模版的 button 变成了包含变量的 url 类型 { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "123456"//验证码的具体 code 值 } ] } ] } } }

          {
    "from": "+8613800138000",
    "to": [
        "00447911123456"
    ],
    "body": {
        "type": "template",
        "template": {          
            "name": "your-template-name",
                        "language": "zh_CN",
            "components": [
              {
                 "type": "body",
                 "parameters": [
                        {
                            "type": "text",
                            "text": "123456"
                        }
                  ]
              },
              // 需要添加 button 变量值，本质上模版的 button 变成了包含变量的 url 类型
              {			
                 "type": "button",
                 "sub_type": "url",
                 "index": 0,
                 "parameters": [
                        {
                            "type": "text",
                            "text": "123456"//验证码的具体 code 值
                        }
                  ]
              }
            ]
        }
    }
}

此代码块在浮窗中显示

返回参数

成功返回

字段	类型	选项	描述
message_id	String	必选	EngageLab WhatsApp 的消息 ID，唯一标识某一条消息。
request_id	String	可选	请求时提交的自定义 ID，响应时原样返回。

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

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

此代码块在浮窗中显示

失败返回

http 状态码为 4xx 或者 5xx，响应体包含字段如下：

字段	类型	选项	描述
code	int	必选	错误码，详见错误码说明
message	String	必选	错误详情

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

此代码块在浮窗中显示

错误码

错误码	http code	说明
1000	500	内部错误
2001	401	EngageLab 侧鉴权失败，未携带有效数据格式的 token。
2002	401	EngageLab 侧鉴权失败，token已过期或已被禁用。
2003	400	WhatsApp 侧鉴权失败，请联系 EngageLab 客服处理。
2004	403	无调用此 API 的权限，请检查您是否有对该 API 秘钥授权了消息发送 API （某发送号）的权限。
3001	400	请求参数格式无效，请检查是否采用 JSON 格式。
3002	400	请求参数有误，请检查请求参数是否符合要求。
3003	400	请求参数有误，相关业务校验失败，详情参考 message 字段的错误描述。
4001	400	相关资源不存在，如模版消息下发时使用了不存在的模版。

注释

媒体消息格式要求

媒体类型	支持的格式类型 Content-Type	大小限制
image	image/jpeg, image/png，不支持透明背景	5 MB
video	video/mp4, video/3gpp 注：编码上仅支持 H.264 视频编码和 AAC 音频编码	16MB
audio	audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus（注：基础的 audio/ogg 不支持，仅支持 audio/ogg; codecs=opus）	16MB
document	1、发送文件消息时，支持任何的 MIME-type 类型 2、发送模板消息时，页眉中的文件仅支持 PDF 格式	100 MB
sticker	image/webp	Static stickers:100KB Animated stickers: 500KB 512x512 像素

语言代码

相关语言和对应代码的对应关系，请下载本文件查看：
模板语言代码.xlsx