Super Message API mt - nxtele/http-api-document GitHub Wiki

发送消息

通过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 √ √ √ √