消息（Message）

发送消息（Send Message）

请求接口​地址

POST	https://api.innopaas.com/api/whatsapp/v3/msg/submit

​ 请求参数

字段	数据类型	是否必填	描述
wabaId	String		WhatsApp商业账户唯一标识
messageType	String		消息内容类型:template:模板**（首次发送，必须使用模板消息来触达用户）​以下类型：​在用户回复后的24小时内，可以使用**text:文本image:图片video:视频audio:音频location:定位document:文档sticker:贴图contacts：联系人​interactive：互动消息
uid	String		客户批次号,不超过32字符
sendNumber	String		发送号码，格式：国家码+手机号
recipientNumber	String		接收号码，格式：国家码+手机号多个号码使用逗号分隔，最多1000个号码
body	String		消息体，messageType=text时必填
language	String		消息语言（需要传语言缩写编码）,详见 附1,Language Code ListmessageType=template时必填
templateName	String		模板名称。允许小写字母、数字、字符和下划线，必须唯一。messageType=template时必填
templateGroupId	String		模板组ID,当使用模板组发送时，必填. 当使用模板组时，有限从模板组中获取一个模板，如果没有匹配到可用模板，可以配置templateName来兜底发送
header	Object		模板的消息头信息。详见 HeaderDto
bodyParams	String[]		模板正文中有变量时必填
buttonParams	Object[]		模板按钮类型是动态链接时必填详见 ParameterDto
media	Object		详见媒体消息：media消息
location	Object		详见媒体消息：location消息
contacts	Object[]		详见媒体消息：contacts消息
interactive	Object		详见媒体消息：interactive消息
namedParams	Object[]		按变量名自定义变量，当模版的变量格式parameterFormat=named时使用。格式：[{"name":"变量名1","vakue":"值1"},{"name":"变量名2","vakue":"值2"},]

请求示例（验证码）

{
   "wabaId": wabaId,
   "messageType": "template",
   "bodyParams": [
       "888888"
   ],
   "recipientNumber": "8618621753276",
   "sendNumber": "62844343232343",
   "templateName": "otp0001",
   "templateGroupId":"9802803984029834028304098",//当使用模板组发送时，填写
   "language": "zh_HK",
    "buttonParams": [
        {
            "type": "text",
            "value": "888888"
        }
    ]
}

非验证码示例

{
    "header":{
        "type":"image",
        "link":"https://www.pianshen.com/thumbs/886/535cfdc357b166dc020c70d0533d85f6.JPEG"
    },
    "bodyParams": ["Lucy"],
    "buttonParams": [
        {
            "type":"text",
            "value":"http://xxxxx?type=yHkYRww90" 
        }
    ],
    "wabaId":"110129512080522",
    "language":"en_US",
    "messageType":"template",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "templateName": "marketing_template"
}

响应示例

{
    "code": "0",
    "message": "Success",
    "data":"110129512080522" //messageId 
}

多媒体消息

media 消息

当messageType为（image、video、audio、document）时，可以发送媒体消息。

字段	数据类型	是否必填	描述
link	String	是	资源访问地址，改地址必须可以外网访问
caption	String	否	标题或描述，当messageType=audio,该属性不能填写
filename	String	否	messageType=document时必填填

{
    "wabaId":"110129512080522",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "messageType": "image",
    "image":{
        "link": "http://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/online/BASE-FILE/2023/03/24/cd56097f-c888-4be5-961d-584d0fa150f3.jpg"
    }
}

location 消息

当messageType为 location 时，可以发送位置消息。

字段	数据类型	是否必填	描述
latitude	String	是	纬度 eg:31.23593
longitude	String	是	经度 eg:31.23593
name	String	是	位置名称,Pizz Hut
address	String	是	地址xxxx Road No.666

{
    "wabaId":"110129512080522",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "messageType": "location",
    "location":{
        "latitude": "-5.15161",
        "longitude":"119.41629",
        "name":"Pizza Hut",
        "address":"xxx road No.123"
    }
}

contacts 消息

当messageType为 contacts 时，可以发送联系人消息。

字段	数据类型	是否必填	描述
name	Object[]	是	姓名
├─formattedName	String	是	全名
├─firstName	String	否	姓
├─lastName	String	否	名
├─middleName	String	否	中间名
├─suffix	String	否	前缀
├─prefix	String	否	后缀
phones	Object[]	否	手机号码
├─type	String	是	类型：HOME/WORK
├─phone	String	是	手机号码
├─waID	String	是	WhatsApp商业账户唯一标识
org	Object[]	否	组织/部门
├─company	String	是	公司名称
├─department	String	是	部门
├─title	String	是	职位
addresses	Object[]	否	地址
├─type	String	否	类型：HOME/WORK
├─street	String	否	街道信息：XX街道XX号
├─city	String	否	城市：北京
├─state	String	否	州缩写，Contact's State
├─zip	String	否	邮政编码：000001
├─country	String	否	国家
├─countryCode	String	否	国家码
birthday	String	否	生日
emails	Object[]	否	电子邮件
├─type	String	是	类型：HOME/WORK
├─email	String	是	邮箱地址[e-mail]
urls	Object[]	否	网址
├─type	String	是	类型：HOME/WORK
├─url	String	是	网址 https://www.chuanglan.com/

{
    "uid": "2023052500002",//批次号 可选
    "wabaId": "110129512080522",
    "messageType": "contacts",
    "recipientNumber": "8616685177612",
    "sendNumber": "8615121041046",
    "contacts": [
        {
            "addresses": [
                {
                    "street": "XXX街道XX号",
                    "city": "XX市",
                    "state": "XX州",
                    "zip": "553301",
                    "country": "cn",
                    "countryCode": "0086",
                    "type": "WORK"
                }
            ],
            "birthday": "1992-08-13",
            "emails": [
                {
                    "email": "[e-mail]",
                    "type": "WORK"
                }
            ],
            "name": {
                "formattedName": "jack chen",
                "firstName": "chen",
                "lastName": "jack",
                "middleName": "jin",
                "suffix": "jack",
                "prefix": "chen"
            },
            "org": {
                "company": "微软",
                "department": "研发",
                "title": "你好啊"
            },
            "phones": [
                {
                    "phone": "8616685177612",
                    "waId": "28288282",
                    "type": "work"
                }
            ],
            "urls": [
                {
                    "url": "https://www.google.com/",
                    "type": "HOME"
                }
            ]
        }
    ]
}

interactive 消息

当messageType为 interactive 时，可以发送交互消息。

字段	数据类型	是否必填	描述
type	String	是	互动消息类型:list/button/product/product_list
header	String	否	互动消息请求头：product_list 类型时候必要、 product类型不能设置header 其他类型可选详见：InteractiveHeader
├─type			媒体类型：text/image/video/document
├─link			媒体链接type不是text时必填
├─caption			标题type不是text时有效
├─paramValue			变量type=text时有效，仅支持一个变量
body		是	类型为product时可选，其他消息类型必需 详见：Body
├─text			文本内容
footer		否	页脚详见：Footer
├─text			文本内容
action		是	操作
├─catalogId			type=product/product_type时必填：链接到您的WhatsApp商业帐户的Facebook目录的唯一标识符。这个ID可以通过Commerce Manager检索
├─productRetailerId			type=product/product_type时必填： 产品在目录中的唯一标识符。单产品和多产品消息最多100个字符。
├─buttons			按钮对象： 详见：Button
├─button			按钮内容： type=list时必填，不能为空字符串
├─sections			清单消息(type=list)和多产品消息（type=product_list）必填。详见：Section

Button参数

字段	数据类型	是否必填	描述
type	String	是	按钮类型：当前可选值：reply
title	String	是	按钮标题：不能为空字符串、当前消息中必须唯一,支持表情符号，不支持markdown。最大长度:20个字符
id	String	是	按钮的唯一标识符。当用户单击按钮时，在webhook中返回此ID。最大长度:256个字符

sections参数

字段	数据类型	是否必填	描述
title	String	否	section标题,最大不超过24字符
rows	String	否	消息类型为list时必填, 一个Row的list对象,最多为10个详见：Row
productItems	String	否	type=product_list时必填， 产品对象的数组。每个部分至少有1个产品，所有部分最多有30个产品。详见：ProductItem

Row参数

字段	数据类型	是否必填	描述
title	String	是	标题：最大长度24个字符
id	String	是	唯一Id标识，最大长度200个字符
description	String	否	描述

ProductItem参数

字段	数据类型	是否必填	描述
productRetailerId	String	是	产品在目录中的唯一标识符

{
    "uid": "2023052500002",
    "wabaId": "110129512080523",
    "messageType": "interactive",
    "recipientNumber": "8616685177612",
    "sendNumber": "8615121041046",
    "interactive": {
        "type": "list",
        "header": {
            "type": "text",
            "text": "5G Message header"
        },
        "body": {
            "text": "meta Message Text "
        },
        "footer": {
            "text": "meta Message Text Footer"
        },
        "action": {
            "button": "button name",
            "sections": [
                {
                    "title": "meta Message Title1",
                    "rows": [
                        {
                            "id": "20230524001",
                            "title": "title1",
                            "description": "some description"
                        },
                        {
                            "id": "20230524002",
                            "title": "title12",
                            "description": "some description"
                        }
                    ]
                },
                {
                    "title": "meta Message Title2",
                    "rows": [
                        {
                            "id": "20230524003",
                            "title": "title text",
                            "description": "some description"
                        },
                        {
                            "id": "20230524004",
                            "title": "title text1",
                            "description": "some description"
                        }
                    ]
                }
            ]
        }
    }
}

button 消息

{
    "uid": "2023052500002",
    "wabaId": "110129512080532",
    "messageType": "interactive",
    "recipientNumber": "8616685177612",
    "sendNumber": "8615121041046",
    "interactive": {
        "type": "button",
        "header": {
            "type": "text",
            "text": "Meta Message header"
        },
        "body": {
            "text": "Meta Message Text "
        },
        "footer": {
            "text": "Meta Message Text Footer"
        },
        "action": {
            "buttons": [
                {
                    "type": "reply",
                    "reply": {
                        "id": "unique-postback-id",
                        "title": "Button’s Title2"
                    }
                },
                {
                    "type": "reply",
                    "reply": {
                        "id": "unique-postback-id1",
                        "title": "Button’s Title3"
                    }
                }
            ]
        }
    }
}

product 消息

{
    "uid": "2023052500002",
    "wabaId": "110129512080532",
    "messageType": "interactive",
    "recipientNumber": "8616685177612",
    "sendNumber": "8615121041046",
    "interactive": {
        "type": "product",
        "body": {
            "text": "Meta Message Text "
        },
        "footer": {
            "text": "Meta Message Text Footer"
        },
        "action": {
            "catalogId": "202305241564", //必须为真实数据
            "productRetailerId": "2023052415640001" //必须为真实数据
        }
    }
}

product_list 消息

{
    "uid": "2023052500002",
    "wabaId": "110129512080532",
    "messageType": "interactive",
    "recipientNumber": "8616685177612",
    "sendNumber": "8615121041046",
    "interactive": {
        "type": "product_list",
        "header": {
            "type": "text",
            "text": "5G Message header"
        },
        "body": {
            "text": "Meta Message Text "
        },
        "footer": {
            "text": "Meta Message Text Footer"
        },
        "action": {
            "catalogId": "202305241564",
            "sections": [
                {
                    "title": "title1",
                    "productItems": [
                        {
                            "productRetailerId": "product-SKU-in-catalog" //必须为真实数据
                        },
                        {
                            "productRetailerId": "product-SKU-in-catalog2"//必须为真实数据
                        }
                    ]
                },
                {
                    "title": "title2",
                    "productItems": [
                        {
                            "productRetailerId": "product-SKU-in-catalog"//必须为真实数据
                        },
                        {
                            "productRetailerId": "product-SKU-in-catalog2"//必须为真实数据
                        }
                    ]
                }
            ]
        }
    }
}

模板消息

无参数模板消息（通知/营销）

{
    "wabaId":"110129512080522",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "messageType":"template",
    "language":"en",
    "templateName": "gogoalshop"
}

带Header、按钮（call，visit website）（通知/营销）

{
    "header":{
        "type":"image",
        "link":"https://www.pianshen.com/thumbs/886/535cfdc357b166dc020c70d0533d85f6.JPEG"
    },
    "bodyParams": ["Lucy"],
    "buttonParams": [
        {
            "type":"text",
            "value":"http://xxxxx?type=yHkYRww90" 
        }
    ],
    "wabaId":"110129512080522",
    "language":"en_US",
    "messageType":"template",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "templateName": "marketing_template"
}

带Header、无按钮（通知/营销）

{
    "header":{
        "type":"image",
        "link":"https://www.pianshen.com/thumbs/886/535cfdc357b166dc020c70d0533d85f6.JPEG"
    },
    "bodyParams": ["TIG Cinema", "2023-03-17 10:00:00", "F", "66"],
    "wabaId":"110129512080522",
    "language":"en_US",
    "messageType":"template",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "templateName": "sample_movie_ticket_confirmation"
}

无Header、无按钮、变量（通知/营销）

{
    "bodyParams": ["TIG Cinema", "2023-03-17 10:00:00", "F", "66"],
    "wabaId":"110129512080522",
    "language":"en_US",
    "messageType":"template",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "templateName": "sample_movie_ticket_confirmation"
}

无Header，带按钮（2个快捷回复）（通知/营销）

{
    "wabaId":"110129512080522",
    "bodyParams": ["TIG", "665578"],
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "messageType":"template",
    "language":"en_US",
    "templateName": "tiga_opt"
}

发送 MMLite 消息

MMLite 需要授权MMLite API权限后才可以使用，并且仅支持发送模版营销消息

请求接口地址

POST	https://api.innopaas.com/api/whatsapp/v3/lite/submit

请求参数

字段	数据类型	是否必填	描述
wabaId	String		WhatsApp商业账户唯一标识
messageType	String		消息内容类型:template:模板
uid	String		客户批次号,不超过32字符
sendNumber	String		发送号码，格式：国家码+手机号
recipientNumber	String		接收号码，格式：国家码+手机号多个号码使用逗号分隔，最多1000个号码
body	String		消息体，messageType=text时必填
language	String		消息语言（需要传语言缩写编码）,详见 附1,Language Code ListmessageType=template时必填
templateName	String		模板名称。允许小写字母、数字、字符和下划线，必须唯一。messageType=template时必填
header	Object		模板的消息头信息。详见 HeaderDto
bodyParams	String[]		模板正文中有变量时必填
buttonParams	Object[]		模板按钮类型是动态链接时必填详见 ParameterDto

请求示例

{
    "header":{
        "type":"image",
        "link":"https://www.pianshen.com/thumbs/886/535cfdc357b166dc020c70d0533d85f6.JPEG"
    },
    "bodyParams": ["Lucy"],
    "buttonParams": [
        {
            "type":"text",
            "value":"http://xxxxx?type=yHkYRww90" 
        }
    ],
    "wabaId":"110129512080522",
    "language":"en_US",
    "messageType":"template",
    "recipientNumber": "6285234567899",
    "sendNumber": "8618912123456",
    "templateName": "marketing_template"
}

响应示例

{
    "code": "0",
    "message": "Success",
    "data":"110129512080522" //messageId 
}

查询消息日志

请求接口地址

POST	https://api.innopaas.com/api/whatsapp/v3/message/log

​ 请求参数

字段	数据类型	是否必填	描述
messageId	String	否	消息ID
sender	String	否	下发显示号码
direction	Integet	是	消息发送方式，1-下行发送；2-上行用户发送，默认：1
recipientNumber	String	否	用户WhatsApp号码
wabaId	String	否	WhatsApp商业账户唯一标识
templateId	String	否	模板ID
templateName	String	否	模板名称
status	String	否	消息状态sending（待发送）delivered（已送达）read-（已读）failed-（发送失败）
category	String	否	模板类型。marketing：营销utility：通知authentication：验证
sendStartTime	String	是	开始时间 格式:yyyy-MM-dd HH:mm:ss
sendEndTime	String	是	结束时间 格式:yyyy-MM-dd HH:mm:ss
page	Integer	是	当前页，默认：1
pageSize	Integer	是	每页查询数量：默认：10

请求示例

{
    "messageId": "12312312312312312",
    "sender": "62189819829898",
    "recipientNumber": "86157116666112",
    "wabaId": "12312312312312",
    "templateId": "851E7BCBBB494A95AC74BDD7720A8569",
    "templateName": "Test模版",
    "status": "sending",
    "category": "utility",
    "sendStartTime": "2015-04-05 14:17:50",
    "sendEndTime": "1975-05-22 08:27:57",
    "direction": 1,
    "page": 1,
    "pageSize": 100
}

响应参数

字段	数据类型	是否必填	描述
messageId	String	是	消息ID
remoteMessageId	String	否	Meta 返回的消息ID
sender	String	是	下发显示号码
direction	Integet	是	消息发送方式，1-下行发送；2-上行用户发送，默认：1
recipientNumber	String	否	用户WhatsApp号码
wabaId	String	否	WhatsApp商业账户唯一标识
templateId	String	否	模板ID
templateName	String	否	模板名称
status	String	是	消息状态sending（待发送）delivered（已送达）read-（已读）failed-（发送失败）
category	String	是	模板类型。marketing：营销utility：通知authentication：验证service:服务自由消息
sendTime	String	是	发送时间格式:yyyy-MM-dd HH:mm:ss
updateTime	String	是	更新时间 ​格式:yyyy-MM-dd HH:mm:ss
messageType	String	是	消息内容类型:template:模板text:文本image:图片video:视频audio:音频location:定位document:文档sticker:贴图contacts：联系人​interactive：互动消息
content	JSON	否	根据messageType 返回不同的内容
errorCode	String	否	错误码
errorMessage	String	否	错误描述

响应示例

{
  "code": "",
  "success": false,
  "message": "",
  "data": {
   "pageNo": 0,
   "pageSize": 0,   
   "total": 0，
    "data": [
      {
        "messageId": "490509047917690880",
        "remoteMessageId": "wamid.HBgNNjI4MjEzOTMzMTYyNhUCABEYEjREQkUxRkYwQjZGQkU5QTQ2QgA",
        "sender": "6185212129316",
        "recipientNumber": "6285212129316",
        "templateId": "7EF920AFD52043009AAC4DDE806500FB",
        "templateName": "disbursement_completed_slik_test",
        "status": "read",
        "category": "service",
        "messageType": "text",
        "content": {
          "text": "这是一个条测试消息"
        },
        "sendTime": "2026-02-06 07:54:10",
        "updateTime": "2026-02-06 07:54:10",
        "direction": 1,
        "errorCode": "",
        "errorMessage": ""
      }
    ]

  }
}

当 messageType = text 时，content 的数据格式

"content":{
    "text": "这是一个条测试消息"
}

当 messageType = template 时，content 的数据格式，详见发送消息时提交的数据

"content":{
    "header":{
        "type":"image",
        "link":"https://www.pianshen.com/thumbs/886/535cfdc357b166dc020c70d0533d85f6.JPEG"
    },
    "bodyParams": ["Lucy"],
    "buttonParams": [
        {
            "type":"text",
            "value":"http://xxxxx?type=yHkYRww90" 
        }
    ]

}

当messageType为多媒体类型时，content 的数据格式，详见发送消息时提交的数据

//如 当messageType为（image、video、audio、document）时
"content":{
  "media":{
        "link": "http://oss-ycloud-publicread.oss-ap-southeast-1.aliyuncs.com/online/BASE-FILE/2023/03/24/cd56097f-c888-4be5-961d-584d0fa150f3.jpg"
    }
 }
 
//如 当messageType为 location时
 "content":{
     "location":{
        "latitude": "-5.15161",
        "longitude":"119.41629",
        "name":"Pizza Hut",
        "address":"xxx road No.123"
     }
 }
 
//其他消息类型参数详见多媒体消息

消息回执（Read）

请求接口地址

POST	https://api.innopaas.com/api/whatsapp/v3/chat/message/status/read

请求参数

字段	数据类型	是否必填	描述
sendNumberId	String	否	下发Sender的号码ID**( sendNumberId 和 sendNumber 二选一必填一个 )**
sendNumber	String	否	下发Sender
wamid	String	是	Meta 的消息ID
typing	Bool	否	是否显示正在输入中，为 true 可以在客户端显示正在输入中效果。默认：false

请求示例

{
    "sendNumber": "[phone]",
    "wamid": "wamid.HBgMNjM5NTQ0MjMwNDQ1FQIAEhgUM0ExRDdFNzZBRkFBREEyRTlGQkQA",
    "typing": false
}

响应参数

字段	数据类型	是否必填	描述
code	String	是	状态码，0 成功，其他失败
success	String	是	请求状态
message	String	否	下发显示号码

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": null
}

小组（Group）

小组（Groups）API 提供管理 WhatsApp 群组整个生命周期的能力。创建群组时会自动生成一个群组邀请链接；由于无法通过 API 手动添加群组成员，需要将邀请链接发送给 WhatsApp 用户，由其自行点击加入。如需接收群组相关的 webhook 通知，需先订阅以下 webhook 字段：group\_lifecycle\_update（群组生命周期）、group\_participants\_update（群组成员变更）、group\_settings\_update（群组设置变更）、group\_status\_update（群组状态）。

创建群组（Create Group）

创建一个新群组并生成初始群组邀请链接。群组创建成功后会收到包含 invite\_link 参数的 webhook，可将该邀请链接发送给有意加入群组的 WhatsApp 用户。也可以创建需要审批加入的群组（join\_approval\_mode 设为 approval\_required），此后用户点击邀请链接需先提交加入请求、经商家批准后才能入群。群组创建成功或失败均会触发 group\_lifecycle\_update webhook。

请求接口​地址

POST	https://api.innopaas.com/api/whatsapp/v3//groups

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
subject	String	是	群组主题。最长 128 字符，首尾空白字符会被去除
description	String	否	群组描述。最长 2048 字符
join_approval_mode	String	否	用户点击邀请链接后的加入方式：approval_required（需经加入请求审批后才能入群）；auto_approve（无需审批直接入群）。缺省时默认为 auto_approve
invite_config	Object	否	邀请配置，JSON 对象。建群成功后平台自动向配置的目标发送群组邀请链接模板消息（异步）。不传或 send_invite 为 false 时不发送；配置异常不影响建群受理。整体序列化后最长 4096 字符。子字段见下表

invite_config 子字段

字段	数据类型	是否必填	描述
send_invite	Boolean	否	建群成功后是否自动发送群组邀请链接模板消息。缺省为 false
notify_language	String	否	邀请通知模板语言（如 zh_CN、en）见文档附1语言编码。send_invite 为 true 时必填 邀请模板不存在时 系统自动创建邀请模板
wa_ids	String	否	手动号码邀请目标数组，元素为手机号 String
template_id	String	否	模板id，群组邀请链接模板消息优先发送该模板，如果模板不存在，则降级创建notify_language语言的模板

请求示例

{
    "messaging_product": "whatsapp",
    "subject": "New Purchase Inquiry",
    "description": "Jim, an existing client, would like to learn about new car purchase options for current year models.",
    "join_approval_mode": "auto_approve",
     "invite_config": {
        "send_invite": true,
        "notify_language": "en",
        "wa_ids": ["8613800000002"]
    }
}

响应说明

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": null
}

群组创建结果通过 group\_lifecycle\_update webhook 通知：创建成功时 webhook 中包含 invite\_link 参数（群组邀请链接）；创建失败时返回失败原因。

删除群组（Delete Group）

删除群组并移除所有群组成员（包括商家号码本身）。无需请求体。删除成功或失败均会触发 group\_lifecycle\_update webhook。

请求接口​地址

DELETE	https://api.innopaas.com/api/whatsapp/v3/

请求参数

字段	数据类型	是否必填	描述
GROUP_ID	String	是	要删除的群组 ID

响应说明

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": null
}

删除结果通过 group\_lifecycle\_update  webhook 通知（删除成功 / 删除失败）。

获取加入请求列表（Get Join Requests）

用于"已启用加入请求的群组"：创建群组时将 join\_approval\_mode 设为 approval\_required 后，用户点击群组邀请链接可提交加入请求或取消已有请求；用户通过加入请求入群时会触发 group\_participants\_update webhook。本接口用于获取当前待处理的加入请求列表。

请求接口​地址

GET	https://api.innopaas.com/api/whatsapp/v3//join_requests

请求参数

字段	数据类型	是否必填	描述
GROUP_ID	String	是	群组 ID

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": [
        {
            "join_request_id": "<JOIN_REQUEST_ID>",
            "wa_id": "<WHATSAPP_USER_ID>",
            "creation_timestamp": "<JOIN_REQUEST_CREATION_TIMESTAMP>"
        }
        //如有其他加入请求，继续在此列出
    ],
    "paging": {
        "cursors": {
            "before": "<BEFORE_CURSOR>",
            "after": "<AFTER_CURSOR>"
        }
    }
}

响应参数

字段	数据类型	是否必填	描述
data[].join_request_id	String	是	加入请求 ID
data[].wa_id	String	是	WhatsApp 用户 ID
data[].creation_timestamp	Integer	是	加入请求创建时间的 Unix 时间戳
paging.cursors	Object	是	分页游标（before / after），用于翻页查询

批准加入请求（Approve Join Requests）

批准用户的加入请求。被批准的用户点击群组邀请链接即可进入群组。批准成功会触发 group_participants_update webhook（用户接受加入请求）。

请求接口​地址

POST	https://api.innopaas.com/api/whatsapp/v3//join_requests

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
join_requests	Array	是	要批准的加入请求 ID 列表，支持批量批准

请求示例

{
    "messaging_product": "whatsapp",
    "join_requests": [
        "<JOIN_REQUEST_ID>"
        //批量批准时，继续在此添加加入请求 ID
    ]
}

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
        "messaging_product": "whatsapp",
        "approved_join_requests": [
            "<JOIN_REQUEST_ID>"
        ],
        "failed_join_requests": [
            {
                "join_request_id": "<JOIN_REQUEST_ID>",
                "errors": [
                    {
                        "code": "<ERROR_CODE>",
                        "message": "<ERROR_MESSAGE>",
                        "title": "<ERROR_TITLE>",
                        "error_data": {
                            "details": "<ERROR_DETAILS>"
                        }
                    }
                ]
            }
        ],
        "errors": [
            {
                "code": "<ERROR_CODE>",
                "message": "<ERROR_MESSAGE>",
                "title": "<ERROR_TITLE>",
                "error_data": {
                    "details": "<ERROR_DETAILS>"
                }
            }
        ]
    }
}

响应参数

字段	数据类型	是否必填	描述
approved_join_requests	Array	是	批准成功的加入请求 ID 列表
failed_join_requests[].join_request_id	String	否	无法批准的加入请求 ID
errors[].code	Integer	否	错误码，如 131203（用户未接受新的服务条款和隐私政策）
errors[].message	String	否	错误信息，如 (#131203) Recipient has not accepted our new Terms of Service and Privacy Policy.
errors[].title	String	否	错误标题，如 Unable to add participant to group
errors[].error_data.details	String	否	错误详情

拒绝加入请求（Reject Join Requests）

拒绝用户的加入请求。被拒绝的用户再次访问群组邀请链接时，会重新看到"申请加入"（Request to join）按钮。拒绝操作不触发任何 webhook。

请求接口​地址

DELETE	https://api.innopaas.com/api/whatsapp/v3//join_requests

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
join_requests	Array	是	要拒绝的加入请求 ID 列表，支持批量拒绝

请求示例

{
    "messaging_product": "whatsapp",
    "join_requests": [
        "<JOIN_REQUEST_ID>"
        //批量拒绝时，继续在此添加加入请求 ID
    ]
}

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
    "messaging_product": "whatsapp",
    "rejected_join_requests": [
        "<JOIN_REQUEST_ID>"
        //批量拒绝时，继续在此列出
    ],
    //仅当存在无法拒绝的加入请求时返回
    "failed_join_requests": [
        {
            "join_request_id": "<JOIN_REQUEST_ID>",
            "errors": [
                {
                    "code": "<ERROR_CODE>",
                    "message": "<ERROR_MESSAGE>",
                    "title": "<ERROR_TITLE>",
                    "error_data": {
                        "details": "<ERROR_DETAILS>"
                    }
                }
            ]
        }
    ]
    }
}

获取群组邀请链接（Get Group Invite Link）

群组创建时会自动生成邀请链接，本接口用于获取当前有效的群组邀请链接。返回的 invite_link 固定以 https://chat.whatsapp.com/ 为前缀，唯一变化部分为 <LINK_ID>。

请求接口地址

GET	https://api.innopaas.com/api/whatsapp/v3//invite_link

请求参数

字段	数据类型	是否必填	描述
GROUP_ID	String	是	要获取邀请链接的群组 ID

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
    "messaging_product": "whatsapp",
    "invite_link": "https://chat.whatsapp.com/<LINK_ID>"
    }
}

重置群组邀请链接（Reset Group Invite Link）

重置群组邀请链接。注意：邀请链接重置后，之前的所有邀请链接将全部失效。

请求接口​地址

POST	https://api.innopaas.com/api/whatsapp/v3//invite_link

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp

请求示例

{
    "messaging_product": "whatsapp"
}

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
    "messaging_product": "whatsapp",
    "invite_link": "https://chat.whatsapp.com/<LINK_ID>"
      }

}

发送群组邀请链接模板消息（Send Group Invite Link Template Message）

向 WhatsApp 用户发送携带群组邀请链接的模板消息，分两步完成：第一步在模板库中添加群组邀请链接模板；第二步发送该模板消息。在请求中提供 group_id，消息送达时会自动转换为对应的群组邀请链接。用户通过邀请链接加入群组时会触发 webhook。

第一步：添加群组邀请链接模板（二选一）

方式一（WhatsApp Manager 操作）：进入 Template Library，点击 Group invite link 下拉框，勾选 Group invite upon request，选择所需模板、命名后提交审批。模板审批最多需要 24 小时，审批通过后即可使用该模板发送消息。

方式二（API 查询模板库）：

GET	https://api.innopaas.com/api/whatsapp/v3//message_template_library?category=utility&topic=group_invite_link&language=en

第二步：发送模板消息

POST	https://api.innopaas.com/api/whatsapp/v3//messages

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
to	String	是	接收方 WhatsApp 用户手机号
type	String	是	消息类型，固定值：template
template.name	String	是	模板名称（第一步中命名的模板名）
template.language.code	String	是	模板语言代码，如 en_US
template.components[].type	String	是	组件类型，固定值：body
template.components[].parameters[].type	String	是	参数类型，固定值：group_id
template.components[].parameters[].group_id	String	是	群组 ID，消息送达时自动转换为对应的群组邀请链接

请求示例

{
    "messaging_product": "whatsapp",
    "to": "<WHATSAPP_USER_PHONE_NUMBER>",
    "type": "template",
    "template": {
        "name": "<TEMPLATE_NAME>",
        "language": {
            "code": "<TEMPLATE_LANGUAGE>"
        },
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "group_id",
                        "group_id": "<GROUP_ID>"
                    }
                    //其他模板参数继续在此添加
                ]
            }
        ]
    }
}

移除群组成员（Remove Group Participants）

从群组中移除成员。注意：成员被移除后，将无法再通过该群组的邀请链接加入。创建群组的商家号码始终以创建者（creator）和管理员（admin）身份留在群组中，不可通过本接口移除。移除操作会触发 group_participants_update webhook。

请求接口地址

DELETE	https://api.innopaas.com/api/whatsapp/v3//participants

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
participants	Array	是	要移除的成员数组，元素格式为 {"user": "<手机号或 WhatsApp ID>"}。单次最多移除 8 名成员；数组不能为空

请求示例

{
    "messaging_product": "whatsapp",
    "participants": [
        { "user": "[phone]" },
        { "user": "[phone]" }
    ]

}

响应说明

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": null
}

移除结果通过 group\_participants\_update webhook 通知。

获取群组信息（Get Group Info）

获取单个群组的元数据。注意：不指定 fields 查询参数时，仅返回群组 ID 和 messaging_product。

请求接口地址

GET	https://api.innopaas.com/api/whatsapp/v3/?fields=

请求参数

字段	数据类型	是否必填	描述
GROUP_ID	String	是	要查询的群组 ID
fields	String	否	逗号分隔的返回字段列表，如 "subject,description,participants,join_approval_mode"；不传时仅返回群组 ID

可用字段（fields）说明

字段	数据类型	是否必填	描述
join_approval_mode	String	否	用户点击邀请链接后的加入方式：approval_required（需经加入请求审批）；auto_approve（无需审批直接入群）
subject	String	否	群组主题
description	String	否	群组描述（创建群组时设置的描述）
suspended	Boolean	否	群组是否已被 WhatsApp 暂停
creation_timestamp	Integer	否	群组创建时间的 Unix 时间戳（秒）
participants	Array	否	群组成员列表，对象数组，格式 [{"wa_id": ""}]
total_participant_count	Integer	否	群组成员总数（不含商家号码）

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
        "messaging_product": "whatsapp",
        "id": "<GROUP_ID>",
        "subject": "<SUBJECT>",
        "creation_timestamp": "<TIMESTAMP>",
        "suspended": "<SUSPENDED>",
        "description": "<DESCRIPTION>",
        "total_participant_count": "<TOTAL_PARTICIPANT_COUNT>",
        "participants": [
            {
                "wa_id": "<WA_ID>"
            },
            {
                "wa_id": "<WA_ID>"
            }
        ],
        "join_approval_mode": "<JOIN_APPROVAL_MODE>"
    }
}

获取活跃群组（Get Active Groups）

获取商家号码下所有活跃群组的列表。

请求接口地址

GET	https://api.innopaas.com/api/whatsapp/v3//groups?limit=&after=&before=

请求参数

字段	数据类型	是否必填	描述
limit	Integer	否	每次请求返回的群组数量。最小 1，默认 25，最大 1024
after	String	否	指向某一页数据末尾的分页游标
before	String	否	指向某一页数据开头的分页游标

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
        "data": {
            "groups": [
                {
                    "id": "<GROUP_ID>",
                    "subject": "<SUBJECT>",
                    "created_at": "<TIMESTAMP>"
                },
                {
                    "id": "<GROUP_ID>",
                    "subject": "<SUBJECT>",
                    "created_at": "<TIMESTAMP>"
                }
            ]
        },
        "paging": {
            "cursors": {
                "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
                "before": "NDMyNzQyODI3OTQw"
            },
            "previous": "https://api.innopaas.com/api/whatsapp/v3/<PHONE_NUMBER_ID>/groups?limit=10&before=NDMyNzQyODI3OTQw",
            "next": "https://api.innopaas.com/api/whatsapp/v3/<PHONE_NUMBER_ID>/groups?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
        }
    }
}

响应参数

字段	数据类型	是否必填	描述
data.groups[]	Array	是	群组列表，每个元素包含 id（群组 ID）、subject（群组主题）、created_at（群组创建时间的 Unix 时间戳）
paging	Object	是	分页对象，包含 cursors（before / after 游标）及 previous / next 翻页链接

更新群组设置（Update Group Settings）

更新群组的主题、描述和头像。更新成功会触发 group_settings_update webhook。

请求接口地址

POST	https://api.innopaas.com/api/whatsapp/v3/

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
subject	String	否	新的群组主题。最长 128 字符；若提供则不能为空
description	String	否	新的群组描述。最长 2048 字符
profile_picture_file	String	否	群组头像的本地图片文件路径。仅支持 image/jpeg；最大 5MB；须为正方形（高=宽）；最小尺寸 192 x 192。文件上传遵循与 Upload Media 端点相同的请求结构

请求示例

{
    "messaging_product": "whatsapp",
    "subject": "Watch Enthusiasts",
    "description": "Join our community to discuss the latest timepieces, share watch reviews, and connect with fellow horology enthusiasts.",
    "profile_picture_file": "/local/path/file.jpg"
}

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": null
 }

群组消息（Group Messaging）

在群组中收发消息。支持的消息类型包括：文本消息、媒体消息、文本模板、媒体模板。

发送群组消息（Send Group Message）

复用现有的消息发送接口向群组发送消息。与发送普通消息相比，差异仅有两点：recipient\_type 字段取值改为 group；to 字段传入通过小组（Group）系列接口获取的群组 ID。媒体消息、模板消息的其余消息体字段与该消息发送接口的既有定义保持一致。

请求接口地址

POST	https://api.innopaas.com/api/whatsapp/v3//messages

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
recipient_type	String	是	接收方类型，群组消息固定值：group（普通消息为 individual）
to	String	是	目标群组 ID，通过小组（Group）系列接口获取
type	String	是	消息类型。群组消息支持：text（文本）；image / video / audio / document / sticker（媒体）；template（模板，含文本模板与媒体模板）
text.body	String	type=text 时必填	文本消息内容，最长 4096 字符
text.preview_url	Boolean	否	type=text 时可选。是否在消息中预览文本内的链接，链接须以 http:// 或 https:// 开头

请求示例

{
    "messaging_product": "whatsapp",
    "recipient_type": "group",
    "to": "<GROUP_ID>",
    "type": "text",
    "text": {
        "preview_url": true,
        "body": "Welcome to our group! Latest updates: https://www.example.com/updates"
    }
}

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
        "messaging_product": "whatsapp",
        "contacts": [
            {
                "input": "<GROUP_ID>",
                "wa_id": "<GROUP_ID>"
            }
        ],
        "messages": [
            {
                "id": "wamid.HBgLM..."
            }
        ]
    }
}

接收群组消息（Receive Group Messages）

群组消息事件会推送至号码 / WABA 已配置的 webhook。message 对象中包含 group\_id 字段，用于标识这是一条群组消息；message 对象的 from 字段与 contacts 对象指向同一位发送该消息的群组成员。

Webhook 示例（接收群组消息）

{
    "object": "whatsapp_business_account",
    "entry": [{
        "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
        "changes": [{
            "value": {
                "messaging_product": "whatsapp",
                "metadata": {
                    "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                    "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
                },
                "contacts": [{
                    "profile": {
                        "name": "<WHATSAPP_USER_NAME>"
                    },
                    "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>"
                }],
                "messages": [{
                    "from": "<GROUP_PARTICIPANT_PHONE_NUMBER>",
                    "group_id": "<GROUP_ID>",
                    "id": "<WHATSAPP_MESSAGE_ID>",
                    "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                    "text": {
                        "body": "<MESSAGE_BODY>"
                    },
                    "type": "text"
                }]
            },
            "field": "messages"
        }]
    }]
}

不支持的消息类型会以 type=unsupported 回调，错误码 130501（Message type is not currently supported），示例如下：

{
    "object": "whatsapp_business_account",
    "entry": [{
        "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
        "changes": [{
            "value": {
                "messaging_product": "whatsapp",
                "metadata": {
                    "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                    "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
                },
                "contacts": [{
                    "profile": {
                        "name": "<WHATSAPP_USER_NAME>"
                    },
                    "wa_id": "<WHATSAPP_USER_PHONE_NUMBER>"
                }],
                "messages": [{
                    "from": "<GROUP_PARTICIPANT_PHONE_NUMBER>",
                    "group_id": "<GROUP_ID>",
                    "id": "<WHATSAPP_MESSAGE_ID>",
                    "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                    "errors": [{
                        "code": 130501,
                        "message": "Message type is not currently supported",
                        "title": "Unsupported message type",
                        "error_data": {
                            "details": "<ERROR_DETAILS>"
                        }
                    }],
                    "type": "unsupported"
                }]
            },
            "field": "messages"
        }]
    }]
}

群组消息状态 Webhook（Group Message Status Webhooks）

向群组发送消息后，消息 delivered、read 时会收到状态 webhook。状态更新采用聚合推送：若同一消息会收到多个 read 或 delivered 状态，将合并为一条包含多个 status 对象的 webhook；每条 webhook 仅针对发送到单个群组的单条消息和单一状态类型。sent 状态示例如下：

{
    "object": "whatsapp_business_account",
    "entry": [{
        "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
        "changes": [{
            "value": {
                "messaging_product": "whatsapp",
                "metadata": {
                    "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                    "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
                },
                "statuses": [{
                    "id": "<WHATSAPP_MESSAGE_ID>",
                    "recipient_id": "<GROUP_ID>",
                    "recipient_type": "group",
                    "status": "sent",
                    "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>"
                }]
            },
            "field": "messages"
        }]
    }]
}

failed 状态示例如下（errors 结构与普通消息一致；群组专属错误码清单：<span text-color="rgb(216,57,49)">数据待补</span>，待与上游对齐后补全）：

{
    "object": "whatsapp_business_account",
    "entry": [{
        "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
        "changes": [{
            "value": {
                "messaging_product": "whatsapp",
                "metadata": {
                    "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
                    "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
                },
                "statuses": [{
                    "id": "<WHATSAPP_MESSAGE_ID>",
                    "recipient_id": "<GROUP_ID>",
                    "recipient_type": "group",
                    "status": "failed",
                    "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                    "errors": [{
                        "code": "<ERROR_CODE>",
                        "title": "<ERROR_TITLE>",
                        "message": "<ERROR_MESSAGE>",
                        "error_data": {
                            "details": "<ERROR_DETAILS>"
                        }
                    }]
                }]
            },
            "field": "messages"
        }]
    }]
}

置顶 / 取消置顶群组消息（Pin and Unpin Group Message）

置顶消息可以突出其重要性。置顶消息按所属父消息的时间顺序展示，最新在前；若已有 3 条置顶消息时发起新的置顶请求，最早置顶的消息将被自动取消置顶。

限制：一次只能置顶一条消息；仅群组管理员可以置顶或取消置顶消息；任意时刻最多存在 3 条置顶消息。

请求接口地址

POST	https://api.innopaas.com/api/whatsapp/v3//messages

请求参数

字段	数据类型	是否必填	描述
messaging_product	String	是	消息产品类型，固定值：whatsapp
recipient_type	String	是	接收方类型，固定值：group
to	String	是	目标群组 ID
type	String	是	消息类型，固定值：pin
pin.type	String	是	置顶操作类型：pin（置顶）或 unpin（取消置顶）
pin.message_id	String	是	要置顶或取消置顶的消息 ID
pin.expiration_days	Integer	pin.type=pin 时必填	置顶时长，单位天，取值范围 1~30

请求示例

{
    "messaging_product": "whatsapp",
    "recipient_type": "group",
    "to": "<GROUP_ID>",
    "type": "pin",
    "pin": {
        "type": "pin",
        "message_id": "<MESSAGE_ID>",
        "expiration_days": 4
    }
}

响应示例

{
    "code": "0",
    "success": true,
    "message": "success",
    "data": {
        "messaging_product": "whatsapp",
        "contacts": [
            {
                "input": "<GROUP_ID>",
                "wa_id": "<GROUP_ID>"
            }
        ],
        "messages": [
            {
                "id": "wamid.HBgLM..."
            }
        ]
    }
}