Viber API mt - nxtele/http-api-document GitHub Wiki

发送消息

通过API发起Viber号码消息发送服务

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

鉴权机制

请求参数

header参数：

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

body参数：

参数名	类型	必选	示例值	说明
appkey	String	是	pem28kje	应用appkey
phone	String	是	86158xxxx1795	消息接收方的Viber号码，需要带国码。如86158xxxx1795
functionType	String	是	text	Viber消息功能类型，消息支持以下功能类型的发送： 1. `text` 文本 2. `image` 图片 3. `text_image` 文本+图片 4. `text_image_button` 文本+图片+按钮 5. `text_button` 文本+按钮 6. `file` 文件 7. `video` 视频 8. `video_text` 视频+文本9. `video_text_button` 视频+文本+按钮
messageData	JsonObject	是	参照请求示例	Viber消息体参数

消息功能类型

text：

参照text请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Transactional	可用的计费类型（`Transactional`(验证码类型)/`Session`(会话类型)/ `OtpTemplate`(otp模板类型)/`Promotional`(营销类型)）
text	String	否	Your code is 989724.	文本消息内容（当计费类型为`Transactional`/`Session`/`Promotional`时必填）
templateId	String	否	c2cdc028-a48b-4187-bbaf-3aaa137b6e23	模板id(当计费类型为`OtpTemplate`时必填) - 参照Otp模板说明
templateParams	JsonObject	否	{"code":"123456"}	模板参数(当计费类型为`OtpTemplate`时必填) - 参照Otp模板说明
templateLang	String	否	en	模板语言(当计费类型为`OtpTemplate`时必填) - 参照Otp模板语言说明

image：

参照image请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)/`Session`(会话类型)）
image	String	是	https://***.jpeg	图片链接

text_image：

参照text_image请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
text	String	是	Your code is 989724.	文本消息内容
image	String	是	https://***.jpeg	图片链接

text_image_button：

参照text_image_button请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
text	String	是	Your code is 989724.	文本消息内容
image	String	是	https://***.jpeg	图片链接
buttonText	String	是	Click me	按钮标题
buttonLink	String	是	`http://www.viber.com`	按钮链接

text_button：

参照text_button请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
text	String	是	Your code is 989724.	文本消息内容
buttonText	String	是	Click me	按钮标题
buttonLink	String	是	`http://www.viber.com`	按钮链接

file：

参照file请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Transactional	可用的计费类型（`Transactional`(验证码类型)/`Session`(会话类型)）
fileName	String	是	fileName.pdf	文件名
fileLink	String	是	https://***.pdf	文件链接
fileType	String	是	pdf	文件类型（参照支持文件类型列表）

video：

参照video请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
thumbnail	String	是	https://***.jpeg	视频缩略图
videoLink	String	是	https://***.mp4	视频链接
videoSize	Number	是	1024	视频文件大小（单位：字节，不能超过200MB）
duration	Number	是	10	视频时间（单位：秒，不能超过600s）

video_text：

参照video_text请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
thumbnail	String	是	https://***.jpeg	视频缩略图
videoLink	String	是	https://***.mp4	视频链接
videoSize	Number	是	1024	视频文件大小（单位：字节，不能超过200MB）
duration	Number	是	10	视频时间（单位：秒，不能超过600s）
text	String	是	Your code is 989724.	文本消息内容

video_text_button：

参照video_text_button请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
thumbnail	String	是	https://***.jpeg	视频缩略图
videoLink	String	是	https://***.mp4	视频链接
videoSize	Number	是	1024	视频文件大小（单位：字节，不能超过200MB）
duration	Number	是	10	视频时间（单位：秒，不能超过600s）
text	String	是	Your code is 989724.	文本消息内容
buttonText	String	是	Click me	按钮标题

list：

参照List请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Transactional	可用的计费类型（`Transactional`(验证类型)）
text	String	是	Please select a string of numbers.	问答文本（最大长度为85个字符）
surveyOptions	List	是	["123","456"]	可选回复集合（长度为2-5）

carousel：

参照carousel请求示例
messageData 参数：

参数名	类型	必选	示例值	说明
rateType	String	是	Promotional	可用的计费类型（`Promotional`(营销类型)）
text	String	是	文本内容.	消息文本（最大长度为1000个字符，推荐长度200）
carouselItems	List	是	查看集合元素CarouselItem对象结构	轮播项集合（长度为2-5个）

CarouselItem参数:

参数名	类型	必选	示例值	说明
title	String	是	这是一个轮播项的标题	轮播项标题（字符长度为2-38）
imageUrl	String	是	http://deff.com/qwdqd.png	轮播项展示图片(图片必须为png/jpg/jpeg, 推荐尺寸:215x185)
primaryButton	Object	是	查看Button对象结构	主要按钮
secondaryButton	Object	是	查看Button对象结构	次要按钮

Button参数:

参数名	类型	必选	示例值	说明
label	String	是	这是一个按钮文案	按钮文案（在primaryButton中最大为10个字符，在secondaryButton中最大为12个字符）
actionUrl	Object	是	http://www.xxxx.com	按钮触发的url

请求示例

text请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "text",
    "messageData": {
        "rateType": "Transactional",
        "text": "Your code is 989724."
    }
}

image请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "image",
    "messageData": {
        "rateType": "Promotional",
        "image": "https://***.jpeg"
    }
}

text_image请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "text_image",
    "messageData": {
        "rateType": "Promotional",
        "text": "Your code is 989724.",
        "image": "https://***.jpeg"
    }
}

text_image_button请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "text_image_button",
    "messageData": {
        "rateType": "Promotional",
        "text": "Your code is 989724.",
        "image": "https://***.jpeg",
        "buttonText": "Click me",
        "buttonLink": "http://www.viber.com"
    }
}

text_button请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "text_button",
    "messageData": {
        "rateType": "Promotional",
        "text": "Your code is 989724.",
        "buttonText": "Click me",
        "buttonLink": "http://www.viber.com"
    }
}

file请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "file",
    "messageData": {
        "rateType": "Transactional",
        "fileType": "pdf",
        "fileName": "fileName.pdf",
        "fileLink": "https://***.pdf"
    }
}

video请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "video",
    "messageData": {
        "rateType": "Promotional",
        "thumbnail": "https://***.jpeg",
        "videoSize": 882472,
        "duration": 15,
        "videoLink": "https://***.mp4"
    }
}

video_text请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "video_text",
    "messageData": {
        "rateType": "Promotional",
        "thumbnail": "https://***.jpeg",
        "videoSize": 882472,
        "duration": 15,
        "videoLink": "https://***.mp4",
        "text": "Your code is 989724."
    }
}

video_text_button请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "video_text_button",
    "messageData": {
        "rateType": "Promotional",
        "thumbnail": "https://***.jpeg",
        "videoSize": 882472,
        "duration": 15,
        "videoLink": "https://***.mp4",
        "text": "Your code is 989724.",
        "buttonText": "button text"
    }
}

list请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "list",
    "messageData": {
        "rateType": "Transactional",
        "surveyOptions": ["123","456"],
        "text": "Please select a string of numbers"
    }
}

carousel请求示例

body（application/json）参数：

{
    "appkey": "TexxxP6",
    "phone": "791xxxxx730",
    "functionType": "carsoucel",
    "messageData": {
        "rateType": "Promotional",
        "text": "消息文本",
        "carouselItems": [
            {
                "title": "标题1",
                "imageUrl": "http://xxxx.png",
                "primaryButton": {
                    "label": "按钮1文案",
                    "actionUrl": "https://www.xxx.com"
                },
                "secondaryButton": {
                    "label": "按钮2文案",
                    "actionUrl": "https://www.xxx.com"
                }
            },
            {
                "title": "标题2",
                "imageUrl": "https://example.com/images/sum.jpg",
                "primaryButton": {
                    "label": "按钮1文案",
                    "actionUrl": "https://www.xxx.com"
                },
                "secondaryButton": {
                    "label": "按钮2文案",
                    "actionUrl": "https://www.xxxx.com/"
                }
            }
        ]
    }
}

响应示例

成功示例

{
    "code": 0,
    "message": "Success",
    "data": {
        "requestId": "b81e8e9fcbbb422a813863e903de94bd"
    },
    "traceId": "77f8709b545f4fee93fd7f098be9df04"
}

失败示例

{
    "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	应用报价缺失，联系业务人员处理应用报价问题
9005	Missing customer APP routes	应用路由缺失，请联系技术人员排查路由
9011	Customer APP quotation currency error	报价币种错误，请联系技术人员排查
9999	Unknown 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

模板说明

强制模板发送国家：俄罗斯(RU)，乌克兰(UK)，白俄罗斯(BY)
计费规则：对于text类型消息，必须匹配Viber注册审核成功的模板，匹配成功，Transactional计费；匹配失败，Promotional计费。

会话说明

会话开启

当终端用户主动发起对话，此时您发送会话类型的消息，将触发一个24小时的会话窗口

会话限制

在终端用户没有回应的情况下，最多连续发送5条会话类型消息。
单个会话限于向用户发送60条信息。
在达到60条信息的限制后，会话结束；如果用户回应，此时再发会话消息，一个新的会话将开始。

会话计费

开启会话，第一条会话消息按Session计费，后续会话期内Session消息不计费。
没有开启会话的情况下，发会话消息统一都按Promotional计费。

Otp模板说明

模板id	模板参数,括号后面是类型	模板英文示例
1	pin(String)	Your code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.
2	pin(String)	Your code is {{pin}}. It's valid for 5 minutes. Please don't share your code with ANYONE. We'll never call or message you and ask for it
3	pin(String)、 businessPlatformName(String)	{{business_platform_name}}: Your code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it
4	pin(String)、codeValidityTime(int)	Your code is {{pin}}. It's valid for {{code_validity_time}} minutes. Please don't share your code with ANYONE. We'll never call or message you and ask for it.
5	pin(String)、pinType(String)、codeValidityTime(int)	Your {{pin_type}} code is {{pin}}. It's valid for {{code_validity_time}} minutes. Please don't share your code with ANYONE. We'll never call or message you and ask for it.
6	pin(String)、businessPlatformName(String)、codeValidityTime(int)	Your {{business_platform_name}} code is {{pin}}. It's valid for {{code_validity_time}} hours. Please don't share your code with ANYONE. We'll never call or message you and ask for it
7	pin(String)、pinType(String)	Your {{pin_type}} code is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it
8	pin(String)、businessPlatformActionName(String)	Your one-time password for {{business_platform_action_name}} is {{pin}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.
9	pin(String)、businessPlatformName(String)、codeReason(String)	{{business_platform_name}}: Your code is {{pin}}. You got this code because {{code_reason}}. Please don't share your code with ANYONE. We'll never call or message you and ask for it.

Otp模板语言说明

语言	模板语言参数值
Englis	en
Arabic	ar
Bulgarian	bg
Croatian	hr
Czech	cs
Danish	da
German	de
Greek	el
Spanish	es
Finnish	fi
French	fr
Hebrew	he
Burmese	my
Hungarian	hu
Indonesian	id
Italian	it
Norwegian	nb
Dutch	nl
Polish	pl
Portuguese(Portugal)	pt
Portuguese (Brazil)	br
Romanian	ro
Russian	ru
Slovak	sk
Serbian	sr
Swedish	sv
Thai	th
Turkish	tr
Ukrainian	uk
Vietnamese	vi
Persian	fa
Belarusian	be
Japanese	ja

Viber API mt - nxtele/http-api-document GitHub Wiki

发送消息

鉴权机制

请求参数

header参数：

body参数：

消息功能类型

CarouselItem参数:

Button参数:

请求示例

text请求示例

image请求示例

text_image请求示例

text_image_button请求示例

text_button请求示例

file请求示例

video请求示例

video_text请求示例

video_text_button请求示例

list请求示例

carousel请求示例

响应示例

成功示例

失败示例

响应码说明

附录

文件类型列表

模板说明

会话说明

Otp模板说明

Otp模板语言说明