消息发送 API

最新更新:2023-11-13

使用消息发送 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

    在文档中心打开
    icon
    Contact Sales