RCS API MT

通过API发起RCS消息发送服务

• URL：https://api.nxcloud.com/v1/rcs/mt
• Method：POST
• Content-Type：application/json
• 需要鉴权：是

鉴权机制

鉴权规则请参考地址：API接口调用约定

请求参数

header参数：

参数名	类型	必选	示例值	说明
accessKey	String	是	fme2na3kdi3ki	用户身份标识
ts	String	是	1655710885431	当前请求的时间戳（单位是毫秒），牛信服务端允许用户端请求最大时间误差为60秒
bizType	String	是	11	RCS业务类型，取固定值“11”
action	String	是	send	RCS业务操作，取固定值“send”
sign	String	是	6e9506557d1f289501d333ee2c365826	API入参参数签名，签名算法

body参数：

字段	类型	必填	说明
appkey	String	是	客户应用标识
agentCode	String	是	RCS Agent 编码
phone	String	是	接收方手机号
functionType	String	是	消息类型，text：文本，file：文件，card：单卡片，carousel：轮播卡片
webhook	String	否	本次消息单独指定回调地址；不传则使用应用默认 webhook，最大 256 字符
text	Text	否	functionType=text 时必填，请求示例
file	File	否	functionType=file 时必填，请求示例
card	Card	否	functionType=card 时必填，请求示例
carousel	Carousel	否	functionType=carousel 时必填，请求示例

消息体对象

Text对象

字段	类型	必填	说明
content	String	是	文本内容，最大 2500 字符
suggestions	Array[Suggestion]	否	建议按钮列表，最多 4 个

---

File对象

字段	类型	必填	说明
url	String	是	文件媒体地址(公开可访问的文件或媒体url地址)，最大 2048个字符，文件大小最大100mb
thumbnailUrl	String	否	缩略图地址，最大 2048个字符
suggestions	Array[Suggestion]	否	建议按钮列表，最多 4 个

---

Card对象

字段	类型	必填	说明
title	String	否	卡片标题，最大 200 字符
description	String	否	卡片描述，最大 2000 字符
url	String	否	卡片媒体地址（公开可访问的文件或媒体url地址），最大 2048个字符,文件大小最大 100mb
suggestions	Array[Suggestion]	否	建议按钮列表，最多 4 个

---

Carousel对象

字段	类型	必填	说明
cards	Array[Card]	是	卡片集合，集合长度2-10

---

Suggestion对象

字段	类型	必填	说明
type	String	是	建议类型 reply：文本回复，dial：拨号，url：打开链接，calendar：添加日历，location：打开位置
text	String	是	按钮展示文本，最大 25 字符
postback	String	是	用户点击后回调给客户的透传值，最大2048个字符
url	String	否	type=url 时必填，最大 2048 字符
phoneNumber	String	否	type=dial 时必填，且必须可解析为合法号码
latitude	Number	否	type=location 时必填，范围 -90.0 ~ +90.0
longitude	Number	否	type=location 时必填，范围 -180.0 ~ +180.0
startTime	String	否	type=calendar 时必填，RFC3339 UTC 时间格式
endTime	String	否	type=calendar 时必填，RFC3339 UTC 时间格式，且不得早于开始时间
title	String	否	type=calendar 时必填， 日历标题，最大 100个字符
description	String	否	type=calendar 时必填，日历描述 最大500个字符

各种类型suggestion

reply

字段	类型	必填	说明
type	String	是	固定reply
text	String	是	按钮展示文本，最大 25 字符
postback	String	是	用户点击后回调给客户的透传值，最大2048个字符

dial

字段	类型	必填	说明
type	String	是	固定dial
text	String	是	按钮展示文本，最大 25 字符
postback	String	是	用户点击后回调给客户的透传值，最大2048个字符
phoneNumber	String	是	必须可解析为合法号码

url

字段	类型	必填	说明
type	String	是	固定url
text	String	是	按钮展示文本，最大 25 字符
postback	String	是	用户点击后回调给客户的透传值，最大2048个字符
url	String	是	最大 2048 字符

calendar

字段	类型	必填	说明
type	String	是	固定calendar
text	String	是	按钮展示文本，最大 25 字符
postback	String	是	用户点击后回调给客户的透传值，最大2048个字符
startTime	String	是	RFC3339 UTC 时间格式
endTime	String	是	RFC3339 UTC 时间格式，且不得早于开始时间
title	String	是	日历标题，最大 100个字符
description	String	是	日历描述 最大500个字符

location

字段	类型	必填	说明
type	String	是	固定location
text	String	是	按钮展示文本，最大 25 字符
postback	String	是	用户点击后回调给客户的透传值，最大2048个字符
latitude	Number	是	范围 -90.0 ~ +90.0
longitude	Number	是	范围 -180.0 ~ +180.0

请求示例

text消息示例

body（application/json） 参数：

{
  "appkey": "your-appkey",
  "agentCode": "brand_agent_001",
  "phone": "8613800138000",
  "functionType": "text",
  "webhook": "https://example.com/rcs/webhook",
  "text": {
    "content": "hello from rcs",
    "suggestions": [
      {
        "type": "reply",
        "text": "查看详情",
        "postback": "detail"
      },
      {
        "type": "url",
        "text": "打开官网",
        "postback": "open_site",
        "url": "https://example.com"
      }
     ]
  }
}

file消息示例

body（application/json） 参数：

{
  "appkey": "your-appkey",
  "agentCode": "brand_agent_001",
  "phone": "8613800138000",
  "functionType": "file",
  "file": {
    "url": "https://example.com/file.jpg",
    "thumbnailUrl": "https://example.com/file-thumb.jpg",
    "suggestions": [
      {
        "type": "reply",
        "text": "继续",
        "postback": "continue"
      }
    ]
  }
}

card消息示例

body（application/json） 参数：

{
  "appkey": "your-appkey",
  "agentCode": "brand_agent_001",
  "phone": "8613800138000",
  "functionType": "card",
  "card": {
    "title": "新品推荐",
    "description": "点击查看详情",
    "url": "https://example.com/card.jpg",
    "suggestions": [
      {
        "type": "reply",
        "text": "购买",
        "postback": "buy_now"
      }
    ]
  }
}

carousel消息示例

body（application/json） 参数：

{
  "appkey": "your-appkey",
  "agentCode": "brand_agent_001",
  "phone": "8613800138000",
  "functionType": "carousel",
  "carousel": {
    "cards": [
      {
        "title": "卡片一",
        "description": "描述一",
        "url": "https://example.com/1.jpg",
        "suggestions": [
          {
            "type": "reply",
            "text": "查看1",
            "postback": "view_1"
          }
        ]
      },
      {
        "title": "卡片二",
        "description": "描述二",
        "url": "https://example.com/2.jpg",
        "suggestions": [
          {
            "type": "reply",
            "text": "查看2",
            "postback": "view_2"
          }
        ]
      }
    ]
  }
}

---

响应参数

参数名	类型	说明
code	Integer	错误码
data	Data	请求结果
message	String	错误码说明
traceId	String	链路追踪ID

Data对象：

参数名	类型	说明
sysMessageId	String	消息ID

响应示例

成功示例：

{
  "code": 0,
  "message": "Success",
  "data": {
    "sysMessageId": "rcs-demo-001"
  },
  "traceId": "202603231430001234567890"
}

失败示例：

{
    "code": -1,
    "message": "Failure",
    "traceId": "77f8709b545f4fee93fd7f098be9df04"
}

---

响应码说明

code	message	解决办法
0	Success
-1	Failure	请联系技术人员排除问题
1000~100X	Authentication failed	详情查看API鉴权部分
1100	Customer does not exist / Status is unavailable	账号状态异常，联系业务人员处理账号问题
1102	Insufficient balance	账号余额不足，请联系业务人员充值
9000	Request parameter error	参数缺失，请检查必须的参数
9001	System business error	系统业务错误，请联系技术人员排除问题
9002	Phone number error	非法号码，请检查号码正确性
9003	Customer APP does not exist / Status is unavailable	应用状态异常，联系业务人员处理云平台应用创建/禁用问题
9004	Customer APP does not have quotation	应用报价缺失，联系业务人员处理应用报价问题
9011	Customer APP quotation currency error	报价币种错误，请联系技术人员排查
9999	Unknown error	请联系技术人员排除问题
19001	Agent does not exist / Status is not approved / Agent unbind app	agent状态异常，请联系技术人员排除问题
19002	Rcs service configuration error	Rcs服务配置异常