填写服务配置

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

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

验证消息来自今日头条

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

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

1. 将开发者填写的 token、timestamp、nonce 三个参数进行字典序排序，并拼接(不用任何符号，直接拼接)成一个字符串
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"
}

参数解释

图片消息

用户在客服聊天中发送图片消息时将产生如下的数据包： 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"
}

参数说明

发送客服消息接口

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

请求路径

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

请求方式

POST

请求参数

响应参数

错误码