Super Message API mt

发送消息

通过API发起多渠道的消息发送服务（目前支持渠道：SMS,VIBER）

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

鉴权机制

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

请求参数

header参数：

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

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	pem28kje	应用appkey
phones	Array	是	['86158xxxx1795','86158xxxx1796']	消息接收方的号码，需要带国码。如86158xxxx1795(目前最多支持批量发送2000个手机号)
message	JsonObject	是	参照请求示例	消息类型，目前支持以下类型发送： 1. Text 文本消息 2. Media 媒体消息 3. Choice 按钮选择消息 4. Card 卡片消息
webhook	String	否	https://xxxx.com	客户回调地址
priority	Array	否	['SMS','VIBER']	渠道优先级，没有指定的话，默认推送所有开通的渠道。如果指定的话，按照指定的渠道逐个发送，直至发送成功。

消息类型

参数名	类型	必选	示例值	说明
message	JsonObject	是		消息对象,包含Text,Media,Choice,Card类型，必须选择其中一个

• message object参数：

参数名	类型	必选	示例值	说明
textMessage	JsonObject	否	参照Text请求示例	文本消息，包含文本内容
mediaMessage	JsonObject	否	参照Media请求示例-发送图片 参照Media请求示例-发送视频 参照Media请求示例-发送文件	媒体消息
choiceMessage	JsonObject	否	参照Choice请求示例	按钮选择消息
cardMessage	JsonObject	否	参照Card请求示例-标题.图片.按钮 参照Card请求示例-标题.图片 参照Card请求示例-标题.按钮	卡片消息

• textMessage参数：

参数名	类型	必选	示例值	说明
text	String	是	Greetings from Super API.	文本消息内容

---

• mediaMessage参数：

参数名	类型	必选	示例值	说明
image	JsonObject	否	-	图片对象
video	JsonObject	否	-	视频对象
file	JsonObject	否	-	文件对象

• image参数：

参数名	类型	必选	示例值	说明
url	String	是	-	图片链接

• video参数：

参数名	类型	必选	示例值	说明
url	String	是	-	视频链接
thumbnailUrl	String	是	-	缩略图链接
videoSize	String	是	-	视频文件大小（单位：字节，不能超过200MB）
duration	String	是	-	视频时间（单位：秒，不能超过600s）

• file参数：

参数名	类型	必选	示例值	说明
fileName	String	是	-	文件名称
url	String	是	-	文件链接
fileType	String	是	-	文件类型

---

• choiceMessage参数：

参数名	类型	必选	示例值	说明
textMessage	JsonObject	是	-	文本对象，标题名称
choices	JsonObject	是	-	Choice对象，包含按钮名称和按钮链接

• choices参数：

参数名	类型	必选	示例值	说明
textMessage	JsonObject	是	-	按钮文本对象
urlMessage	JsonObject	是	-	按钮链接对象

• urlMessage参数：

参数名	类型	必选	示例值	说明
url	String	是	-	按钮链接

---

• cardMessage参数：

参数名	类型	必选	示例值	说明
title	String	是	-	卡片标题
mediaMessage	JsonObject	否	-	图片对象
choices	JsonObject	否	-	Choice对象，包含按钮名称和按钮链接

---

请求示例

Text请求示例

body（application/json） 参数：

{
    "appkey": "bFzEXXAx",
    "phones": [
        "8529XXX7630",
        "8529XXX7631"
    ],
    "message": {
        "textMessage": {
            "text": "Greetings from Super API."
        }
    }
}

Media请求示例-发送图片

body（application/json） 参数：

{
    "appkey": "SUhYXXR1",
    "phones": [
        "7916XXXX730"
    ],
    "message": {
        "mediaMessage": {
            "image": {
                "url": "https://***.jpeg"
            }
        }
    }
}

Media请求示例-发送视频

body（application/json） 参数：

{
    "appkey": "SUXXX9R1",
    "phones": [
        "79162xxx730"
    ],
    "message": {
        "mediaMessage": {
            "video": {
                "url": "https://xxxx.com/Happy%20Cow.mp4",
                "thumbnailUrl": "https://xxxx.jpg",
                "videoSize": "10",
                "duration": "10"
            }
        }
    }
}

Media请求示例-发送文件

body（application/json） 参数：

{
    "appkey": "SUXXX9R1",
    "phones": [
        "7916xxx9730"
    ],
    "message": {
        "mediaMessage": {
            "file": {
                "fileName": "文件名称",
                "url": "https://xxxx.pdf",
                "fileType": "pdf"
            }
        }
    },
    "priority": [
        "VIBER",
        "SMS"
    ]
}

Choice请求示例

body（application/json） 参数：

{
    "appkey": "SUXXX9R1",
    "phones": [
        "791XXX9730"
    ],
    "message": {
        "choiceMessage": {
            "textMessage": {
                "text": "按钮Title"
            },
            "choices": [
                {
                    "textMessage": {
                        "text": "按钮名称"
                    },
                    "urlMessage": {
                        "url": "http://xxxx.com"
                    }
                }
            ]
        }
    },
    "priority": [
        "VIBER",
        "SMS"
    ]
}

Card请求示例-标题_图片_按钮

body（application/json） 参数：

{
    "appkey": "SUXXX9R1",
    "phones": [
        "7916XXX9730"
    ],
    "message": {
        "cardMessage": {
            "title": "卡片",
            "mediaMessage": {
                "image": {
                    "url": "https://XXXX.jpg"
                }
            },
            "choices": [
                {
                    "textMessage": {
                        "text": "按钮"
                    },
                    "urlMessage": {
                        "url": "https://xxxx.com"
                    }
                }
            ]
        }
    },
    "priority": [
        "VIBER",
        "SMS"
    ]
}

Card请求示例-标题_图片

body（application/json） 参数：

{
    "appkey": "SUhXXXR1",
    "phones": [
        "7916XXX9730"
    ],
    "message": {
        "cardMessage": {
            "title": "卡片",
            "mediaMessage": {
                "image": {
                    "url": "https://XXXX.jpg"
                }
            }
        }
    },
    "priority": [
        "VIBER",
        "SMS"
    ]
}

Card请求示例-标题_按钮

body（application/json） 参数：

{
    "appkey": "SUhXXX9R1",
    "phones": [
        "79162XXX730"
    ],
    "message": {
        "cardMessage": {
            "title": "卡片",
            "choices": [
                {
                    "textMessage": {
                        "text": "按钮"
                    },
                    "urlMessage": {
                        "url": "https://xxxx.jpg"
                    }
                }
            ]
        }
    },
    "priority": [
        "VIBER",
        "SMS"
    ]
}

响应参数

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

• data object参数：

参数名	类型	说明
requestId	String	消息ID
channelStatus	JsonObject	渠道状态

• channelStatus object参数：

参数名	类型	说明
sms	JsonObject	短信对象
viber	JsonObject	Viber对象

• sms object参数：

参数名	类型	说明
code	Integer	SMS响应码
message	String	SMS响应信息

• viber object参数：

参数名	类型	说明
code	Integer	VIBER响应码
message	String	VIBER响应信息

响应示例

成功示例

{
    "code": 0,
    "message": "Success",
    "data": {
        "requestId": "ec6fceb05c1843bd9e4c3bc81e69ed74",
        "channelStatus": {
            "sms": {
                "code": 0,
                "message": "Success"
            },
            "viber": {
                "code": 0,
                "message": "Success"
            }
        }
    }
}

失败示例

{
    "code": -1,
    "message": "Failure"
}

响应码说明

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	参数缺失，请检查必须的参数
9002	Phone number error	非法号码，请检查号码正确性
9003	Customer APP does not exist / Status is unavailable	应用状态异常，联系业务人员处理云平台应用创建/禁用问题
9010	Rate limit exceeded	每秒超过请求限制
9999	Unknown error	请联系技术人员排除问题
14001	channel is not opened	渠道未开通
14002	Message is not supported	消息类型不支持
14003	Send error	发送失败

附录

文件类型列表

File Type	File Formats	Max File Size
Documents	.doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info	200MB
PDF	.pdf, .xps, .pdax, .eps	200MB
Spreadsheet	.xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx	200MB

说明：例如.doc格式，fileType填写doc；.xls格式，fileType填写xls

渠道支持的消息类型

渠道	Text	Media	Choice	Card
SMS	√
Viber	√	√	√	√