5G消息协议发送
1、概述
本接口用于发送5G消息下行消息，无需制作模板，协议中的素材需要先审核通过，接口中涉及到的平台参数，请在平台上获取（所有的请求参数名称都是区分大小写的）。
发送消息的两种方式：1.素材上传+新增5G消息模板+5G消息模板消息下发；2.素材上传+协议发送5G消息。
协议发送5G消息
2、接口地址
POST https://rcsapi.hanwg.com/rcs/protocol/outbound/{{chatbotId}}
3、请求参数
3.1、请求路径参数
见全局参数
3.2、请求头参数
请求体参数
| 名称 | 数据类型 | 是否必有 | 描述 |
|---|---|---|---|
| phone | array[string] | 是 | 手机号码 默认最大支持200个号码 |
| messageId | string | 是 | 消息编号 本条消息的唯一标识，建议用UUID，与contributionId一样都是对于一条消息的标识，区别在于messageId用于状态报告回调 字符串长度限制范围：10-36 |
| conversationId | string | 是 | 唯一标识【主被叫】用户间的一次会话，建议用UUID，触发上行消息携带的conversationId将填写该下行消息的conversationId值 字符串长度限制范围：10-36 |
| contributionId | string | 是 | 唯一标识一条消息，建议用UUID，对上行消息回复时携带该字段作为inReplyTo的值 字符串长度限制范围：10-36 |
| inReplyTo | string | 否 | 标识此条消息是对【某条上行消息】的回复，值为对方某条上行消息的contributionId，既可以是终端对客户的回复，也可以是客户对终端的回复。比如上行事件、场景发送等。 |
| storeSupported | bool | 否 | 是否离线存储 |
| smsSupported | int | 否 | 回落类型 |
| smsContent | string | 条件 | 回落的内容 当：smsSupported = 注意：为避免短链连着文字字符，到达终端后导致该短链无法解析，变量${xx_rcs_h5_url}前后如有文字字符，自动添加空格隔开； 示例： 添加空格前： 给您发送一条消息：${xx_rcs_h5_url}点击即可查看 添加空格后： 给您发送一条消息： ${xx_rcs_h5_url} 点击即可查看 到达手机终端: 给您发送一条消息： xxx.xxx.xxx 点击即可查看. 请勿在该字段中添加签名，因为系统将会自动添加Chatbot签名。计费时，总字符数将包括自动添加的签名字符及该字段的字符数，请务必注意计费细节。 |
| message | object | 是 | 消息内容对象 有5种类型：文本，文件，单卡片，多卡片，地理位置信息 |
| variables | map(string,string) | 条件 | 替换智能消息模板中的变量，只是智能消息中的变量，形式为map(key,value)，key为变量名，value为变量值 |
| showTimes | int | 条件 | 智能消息短链允许解析次数 平台现目前【发送接口】只支持生成个性化短链，展示次数默认且只为1 必需：smsSupported = 4（智能消息回落） |
| expireTime | int | 条件 | 智能消息短链有效期（单位：天） 平台现目前【发送接口】只支持生成个性化短链，有效期默认为7，取值范围[1, 7] 必需：smsSupported = 4（智能消息回落） |
| taskId | string | 条件 | 发送任务编号 必需：smsSupported = 4（5G消息模板回落为智能消息回落）且 智能消息模板没有变量 一批发送填写同一个任务编号，可以更快触达终端 |
| aimSmsContent | string | 条件 | 智能消息短信内容（短信中的短链在终端可解析则展示为智能消息，不可解析则依然展示为短信） 必需：smsSupported = 4（智能消息回落） 注意：此字段内容不可添加签名 注意：为避免短链连着文字字符，到达终端后导致该短链无法解析，变量${xx_rcs_aim}前后如有文字字符，自动添加空格隔开； 示例： 添加空格前： 给您发送一条消息：${xx_rcs_aim}点击即可查看 添加空格后： 给您发送一条消息： ${xx_rcs_aim} 点击即可查看 到达手机终端: 给您发送一条消息： xxx.xxx.xxx 点击即可查看。 请勿在该字段中添加签名，因为系统将会自动添加Chatbot签名。计费时，总字符数将包括自动添加的签名字符及该字段的字符数，请务必注意计费细节。 |
| aimNoParseType | int | 条件 | 若智能消息短信不可解析为智能消息，是否需要发送其它消息类型 必需：smsSupported = 4（智能消息回落） |
| aimNoParseSms | string | 条件 | 普通短信内容（若智能消息短信不可解析为智能消息，需要发送其它消息） 必需：aimNoParseType = 1（发送短信） 请勿在该字段中添加签名，因为系统将会自动添加Chatbot签名。计费时，总字符数将包括自动添加的签名字符及该字段的字符数，请务必注意计费细节。 |
4、请求示例
4.1、发送文本消息
POST /rcs/protocol/outbound/a92e43085a0049ba8928b61fa04eeee HTTP/1.1
Content-Type: application/json
Accept: application/json
Date: 2023-02-16 17:10:49
Authorization: ZGgxODUyODo1OTUzZmNiM2JmZGZiYzVmYzVmMWU5OTY1MTk2MjQ1Mg==
User-Agent: PostmanRuntime/7.31.0
Postman-Token: c5f533b7-4a42-46f9-8b8c-7081907b0ae1
Host: 172.18.1.104:31205
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 1687
{
"phone": [
"15766666666"
],
"messageId": "{{uuid}}",
"conversationId": "{{uuid}}",
"contributionId": "{{uuid}}",
"inReplyTo": "",
"storeSupported": false,
"smsSupported": 4,
"smsContent": "70c7811c2ac84bc6b737b85763a92a00",
"message": {
"contentType": "text/plain",
"contentEncoding": "utf8",
"contentText": "回复Y确认订阅",
"suggestion": [
{
"reply": {
"displayText": "Y",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"displayText": "打开浏览器",
"postback": {
"data": "回执操作"
},
"urlAction": {
"openUrl": {
"url": "https://www.baidu.com"
}
}
}
},
{
"action": {
"displayText": "拨打电话",
"postback": {
"data": "回执操作"
},
"dialerAction": {
"dialPhoneNumber": {
"phoneNumber": "15766666666"
}
}
}
}
]
},
"variables": {
"param1": "智能消息中的参数1"
},
"showTimes": 1,
"expireTime": 3,
"taskId": "",
"aimSmsContent": "给您发送了一条消息，官方信息，谨防失效，点击即可查看：${dh_rcs_aim}",
"aimNoParseType": 1,
"aimNoParseSms": "此为普通短信"
}4.2、发送文件消息
POST /rcs/protocol/outbound/a92e43085a0049ba8928b61fa04eeee HTTP/1.1
Content-Type: application/json
Accept: application/json
Date: 2023-02-16 17:12:02
Authorization: ZGgxODUyODowMGIwZTQ2MzAxZGZlYjcwMzYxY2E3MDgxMTkzODUzZQ==
User-Agent: PostmanRuntime/7.31.0
Postman-Token: a5f7ea06-bc8e-430e-aacc-2762261a3f4e
Host: 172.18.1.104:31205
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 1878
{
"phone": [
"13594083007"
],
"messageId": "{{uuid}}",
"conversationId": "{{uuid}}",
"contributionId": "{{uuid}}",
"message": {
"contentType": "application/vnd.gsma.rcs-ft-http",
"contentEncoding": "utf8",
"contentText": {
"fileId": "443ce2050acf43b49459adf49d9fdbd9"
},
"suggestion": [
{
"action": {
"displayText": "短信草稿",
"postback": {
"data": "回执操作"
},
"composeAction": {
"composeTextMessage": {
"phoneNumber": "15766666666",
"text": "消息内容"
}
}
}
},
{
"action": {
"displayText": "地理位置/展示位置",
"postback": {
"data": "回执操作"
},
"mapAction": {
"showLocation": {
"location": {
"longitude": "116.403978",
"latitude": "39.915031",
"label": "标签"
}
}
}
}
}
]
}
}4.3、发送单卡片消息
POST /rcs/protocol/outbound/a92e43085a0049ba8928b61fa04eeee HTTP/1.1
Content-Type: application/json
Accept: application/json
Date: 2023-02-16 17:16:16
Authorization: ZGgxODUyODo0OWM2NDI4NDM5ZmI5Y2E1ZThlMjNmYjkwYzgxNmRjYg==
User-Agent: PostmanRuntime/7.31.0
Postman-Token: 908111ce-8ba3-4f1a-bda8-c2e5800aa947
Host: 172.18.1.104:31205
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 3781
{
"phone": [
"15766666666"
],
"messageId": "{{uuid}}",
"conversationId": "{{uuid}}",
"contributionId": "{{uuid}}",
"message": {
"contentType": "application/vnd.gsma.botmessage.v1.0+json",
"contentEncoding": "utf8",
"contentText": {
"generalPurposeCard": {
"layout": {
"cardOrientation": "VERTICAL",
"titleFontStyle": [
"underline",
"bold"
],
"descriptionFontStyle": [
"underline"
]
},
"content": {
"media": {
"mediaId": "material_001",
"height": "MEDIUM_HEIGHT"
},
"title": "卡片的标题",
"description": "卡片的描述",
"suggestions": [
{
"reply": {
"displayText": "是",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"urlAction": {
"openUrl": {
"url": "https://www.baidu.cn",
"application": "webview",
"viewMode": "half"
}
},
"displayText": "打开链接",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"dialerAction": {
"dialPhoneNumber": {
"phoneNumber": "15766666666"
}
},
"displayText": "拨打电话",
"postback": {
"data": "回执操作"
}
}
}
]
}
}
},
"suggestion": [
{
"reply": {
"displayText": "否",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"displayText": "打开链接",
"postback": {
"data": "回执操作"
},
"urlAction": {
"openUrl": {
"url": "https://www.baidu.com"
}
}
}
},
{
"action": {
"displayText": "拨打电话",
"postback": {
"data": "回执操作"
},
"dialerAction": {
"dialPhoneNumber": {
"phoneNumber": "15766666666"
}
}
}
}
]
}
}4.4、发送多卡片消息
{
"phone": [
"15766666666"
],
"messageId": "{{uuid}}",
"conversationId": "{{uuid}}",
"contributionId": "{{uuid}}",
"message": {
"contentType": "application/vnd.gsma.botmessage.v1.0+json",
"contentEncoding": "utf8",
"contentText": {
"generalPurposeCardCarousel": {
"layout": {
"cardWidth": "MEDIUM_WIDTH"
},
"content": [
{
"media": {
"mediaId": "material_000001",
"height": "SHORT_HEIGHT"
},
"title": "卡片1的标题",
"description": "卡片1的描述",
"suggestions": [
{
"action": {
"mapAction": {
"showLocation": {
"location": {
"longitude": 116.403978,
"latitude": 39.915031,
"label": "地图"
}
}
},
"displayText": "查询地理位置",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"calendarAction": {
"createCalendarEvent": {
"startTime": "2022-12-08 00:00:00",
"endTime": "2022-12-09 00:00:00",
"title": "结婚纪念日",
"description": "5201314"
}
},
"displayText": "设置日历",
"postback": {
"data": "回执操作"
}
}
}
]
},
{
"title": "卡片2的标题",
"description": "卡片2的描述",
"media": {
"mediaId": "material_000003",
"height": "SHORT_HEIGHT"
},
"suggestions": [
{
"action": {
"mapAction": {
"showLocation": {
"location": {
"longitude": 116.403978,
"latitude": 39.915031,
"label": "地图"
}
}
},
"displayText": "查询地理位置",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"calendarAction": {
"createCalendarEvent": {
"startTime": "2023-07-08 00:00:00",
"endTime": "2023-07-09 00:00:00",
"title": "会议日期",
"description": "董事会议"
}
},
"displayText": "设置日历",
"postback": {
"data": "回执操作"
}
}
}
]
}
]
}
},
"suggestion": [
{
"reply": {
"displayText": "是",
"postback": {
"data": "回执操作"
}
}
},
{
"action": {
"displayText": "打开链接",
"postback": {
"data": "回执操作"
},
"urlAction": {
"openUrl": {
"url": "https://www.baidu.com"
}
}
}
},
{
"action": {
"displayText": "拨打电话",
"postback": {
"data": "回执操作"
},
"dialerAction": {
"dialPhoneNumber": {
"phoneNumber": "157366630192"
}
}
}
}
]
}
}4.5、发送地理位置消息
!
{
"phone": [
"15766666666"
],
"messageId": "{{uuid}}",
"conversationId": "{{uuid}}",
"contributionId": "{{uuid}}",
"message": {
"contentType": "text/plain",
"contentEncoding": "utf8",
"contentText": "geo:39.915031,116.403978;crs=gcj02;u=10;rcs-l=天安门",
"suggestion": [
{
"action": {
"displayText": "分享设备信息",
"postback": {
"data": "上行消息"
},
"deviceAction": {
"requestDeviceSpecifics": {}
}
}
}
]
}
}5、响应参数
| 名称 | 数据类型 | 是否必有 | 描述 | |
|---|---|---|---|---|
| code | int | 是 | 响应状态码 | |
| desc | string | 是 | 请求响应描述 | |
| result | object | 条件 | 请求响应内容 必需： code = 0（请求成功） |
|
| messageId | string | 是 | 消息编号 请求成功时返回本条消息在平台的唯一标识 |
|
| time | date | 是 | 请求成功返回时的时间 时间格式：yyyy-MM-dd HH:mm:ss |
|
| failPhones | array[string] | 是 | 提交失败号码，请求成功且有失败号码 | |
6、响应示例
HTTP/1.1 200 OK
Content-Type: application/json
Transfer-Encoding: chunked
Date: Thu, 16 Feb 2023 09:12:00 GMT
Connection: close
{
"code": 0,
"desc": "请求成功",
"result": {
"messageId": "0111b2cb46d04454b01fe0ceaad890aa",
"time": "2023-02-16 17:10:47",
"failPhones": []
}
}文档更新时间: 2025-12-17 09:34 作者：王超
