消息推送客服

填写服务配置

开发者使用账号登录开发者平台后,按提示填写相关信息,具体如下:

  • URL:开发者用来接收消息的接口 URL。开发者所填写的 URL 默认以 https:// 开头,端口为 443
  • Token:可由开发者可以任意填写,用作生成签名,长度 3 ~ 32 个字符。
  • 选择消息数据格式:JSON 格式(默认)或 XML 格式。

验证消息来自今日头条

开发者提交信息后,今日头条服务器将发送 GET 请求到填写的服务器地址 URL 上,所携带的参数如下表所示:

参数  描述
signature加密签名,signature 结合了开发者填写的 token 参数和请求中的 timestamp 参数、nonce 参数
timestamp时间戳
nonce随机数
msg消息信息
echostr随机字符串

开发者通过校验 signature 来判断请求是否来自于今日头条服务器。signature 生成方式为:

  1. 将开发者填写的 token、timestamp、nonce、msg 四个参数进行字典序排序,并拼接(不用任何符号,直接拼接)成一个字符串
  2. 将上一步得到的字符串进行 sha1 加密
    开发者将获得加密后的字符串与 signature 对比,如果相同,则可以认为请求来自于今日头条服务器,请原样返回 echostr 参数的内容(内容前后不加单引号或双引号,直接返回文本字符串),今日头条服务器收到回复之后进行对比,相同则保存客服配置信息并开启消息推送客服。

接收消息

开启消息推送之后,用户发送的所有消息,今日头条服务器将会通过 POST 请求发送到开发者配置的 URL,格式为 JSON 或者 XML,开发者将收到的消息自行验证解密。转发用户消息到开发者服务器时,如果两秒内没收到响应,将认为失败,然后 sleep 几秒再重试,总共重试三次。每条消息都包含一个 createTime 字段,当收到多条消息时,可以根据 FromUserName 和 CreateTime 两个字段进行重排序。

开发者服务器收到请求必须作出相应的回复,以便今日头条服务器判断消息发送情况,回复方式建议:

  1. 直接回复 success 或者长度为 0 的空串
  2. 其他 第一种情况,今日头条服务端才会认为消息发送成功,第二种情况认为失败并也不会重试。

文本消息

用户在客服聊天中发送文本消息时将产生如下的数据包:

XML 格式

 <xml>
   <ToUserName><![CDATA[appid]]></ToUserName>
   <FromUserName><![CDATA[openid]]></FromUserName>
   <CreateTime>1577364225</CreateTime>
   <MsgType><![CDATA[text]]></MsgType>
   <Content><![CDATA[text content]]></Content>
</xml>

JSON 格式

{
  "ToUserName": "appid",
  "FromUserName": "openid",
  "CreateTime": 1577364225,
  "MsgType": "text",
  "Content": "text content"
}

参数解释

参数  说明
ToUserName小程序的 ID
FromUserName发送消息用户的 openid
CreateTime消息创建时间
MsgType消息类型(text)
Content文本消息内容

图片消息

用户在客服聊天中发送图片消息时将产生如下的数据包: XML 格式

 <xml>
   <ToUserName><![CDATA[appid]]></ToUserName>
   <FromUserName><![CDATA[openid]]></FromUserName>
   <CreateTime>1577364225</CreateTime>
   <MsgType><![CDATA[image]]></MsgType>
   <PicUrl><![CDATA[this is image url link]]></PicUrl>
</xml>

JSON 格式

{
  "ToUserName": "appid",
  "FromUserName": "openid",
  "CreateTime": 1577364225,
  "MsgType": "image",
  "PicUrl": "this is image url link"
}

参数说明

参数  说明
ToUserName小程序的 ID
FromUserName发送消息用户的 openid
CreateTime消息创建时间
MsgType消息类型(image)
PicUrl图片链接

发送客服消息接口

收到用户发来的消息之后,开发者可以通过调用今日头条提供的接口回复客服消息给用户,当用户不在线时,会以消息通知的形式发送到用户

请求路径

https://developer.toutiao.com/api/apps/message/custom/send?access_token={accesstoken}

请求方式

POST

请求参数

参数名类型必传描述
access_token字符串access_token,获取方式,以参数形式拼接 url 后面
open_id字符串用户的 openid
msg_type字符串消息类型,文本消息为 text,图片消息为 image
content字符串msg_type 为 text 时必传文字消息
pic_url字符串msg_type 为 image 时必传图片链接

响应参数

参数名类型描述
errno整型错误码
msg字符串描述信息

错误码

说明建议解决方案
0请求成功
-1内部错误稍后重试,还是不行反馈到今日头条开发
-2消息限制根据提示操作
-3参数错误根据提示操作

Bug & Tip

  • 请求 body 的Content-Type限定为application/json
点击纠错
评价此篇文档