API渠道接入

接入小多机器人API,第三方需要按步骤获取基本信息:

  1. 注册账号
  2. 登录系统,添加API渠道 (登录系统-->设置-->渠道设置-->创建API渠道)
  3. 获取创建的渠道信息。企业ID、渠道ID、APPSecret

开始接入


接口列表  

1、创建api对话
2、api渠道发送消息
3、第三方消息回调
4、获取未读消息


服务地址: https://cvd.xiaoduoai.com

创建api对话

/v1/api/open_api_dialog

请求方式:

post body (utf8 json)

请求参数:

{
     "unit_id":1001,
     "channel_id": 1001,
     "ts": 1529800000,
     "state":"",
     "sign":"",
     "customer":{
          "id":"unique_id",             
          "name":"",        
          "sex":1,    
          "age":25,  
          "phone" :"",
          "faceurl":"",                
          "third_params":
          {
             "key1":"val1",
             "key2":"val2",
             ......
          }
      }
}
字段 类型 必填 描述
unit_id int 企业id
channel_id int 渠道id
ts int unix时间戳
sign string 签名,生成方式如下
state string 第三方传入的状态信息,晓多会原样回传给第三方,长度限制1024字节
customer obj 顾客信息
customer.sex 性别 -1女 0 未知 1男
customer.third_params obj 第三方自定义参数

sign生成:

1)将unit_id、channel_id、ts、state、customer.id 5个参数进行字典序排序 
2)将三个参数字符串以&拼接成一个字符串
3)将第2步得到的字符串拼接上APPSecret得到的字符串进行MD5签名,得到一个16进制大写表示的字符串。

请求参数举例:

注册账号,获取到企业ID:5,渠道ID:157,APPSecret:"98f756ac5f938904fed5b6543f1af9b6"

参与签名的字段值如下:
unit_id=5 channel_id=157 ts=1529800000 state="test" customer.id="12345"

sign计算过程:
1)将参与签名的参数进行字典序排序,以&拼接得到"channel_id=157&customer.id=12345&state=test&ts=15298000000&unit_id=5"
2)再拼接APPSecret得到"channel_id=157&customer.id=12345&state=test&ts=15298000000&unit_id=598f756ac5f938904fed5b6543f1af9b6RRONkNKn"
3) 再计算MD5,upper(hex(MD5("channel_id=157&customer.id=12345&state=test&ts=15298000000&unit_id=598f756ac5f938904fed5b6543f1af9b6RRONkNKn")))
4)得到sign="FF9BEB2B5BB29062651B22DF1579D65D"

返回值json:

{
     "error_code":0,
     "info":"",
}

返回值说明:

参数 类型 描述
error_code int 错误码
info string 描述

api渠道发送消息

/v1/api/send_api_msg

请求方式:

post body (utf8 json)

请求参数:

{
     "unit_id":1001,
     "channel_id": 1001,
     "ts": 1529800000,
     "state":"",
     "sign":"",
     "customer_id":"",
     "msgs":[
         {
             "type":"TIMTextElem", // 文本
             "content":{
                 "Text":"hello!"
             },
             "random":1529874653389
         },
         {
             "type":"TIMImageElem", // 图片
             "content":{
                 "ImageInfoArray":[ // 使用数组的原因是很多其实一个图片包含大图、中图、小图。如果只有一副,填一个即可
                     {
                         "Size":1024,
                         "Width":50,
                         "Hight":60,
                         "URL":""
                     }
                 ]
             },
             "random":1529874653301000
         }

     ]
}
字段 类型 必填 描述
unit_id int 企业id
channel_id int 渠道id
ts int unix时间戳
sign string 签名 unit_id、channel_id、ts、state、customer_id 5个参数(规则同上)
state string 第三方传入的状态信息,晓多会原样回传给第三方,长度限制1024字节
customer_id string 顾客ID
msgs obj arry 消息 消息定义

返回值json:

{
     "error_code":0,
     "info":"",
}

返回值说明:

参数 类型 描述
error_code int 错误码
info string 描述

第三方消息回调

对调地址为:晓得后台渠道管理页面配置的地址

请求方式:

post body (utf8 json)

请求参数:

{
     "op":1,
     "ts": 1529800000,
     "state":"",
     "sign":"",
     "customer_id":"",
     "msg": {
             "type":"TIMTextElem", // 文本
             "content":{
                 "Text":"hello!"
             },
             "random":1529874653389001
     }
}
字段 类型 必填 描述
op int 1正常回复 2结束对话 3 请求转人工
ts int unix时间戳
sign string 签名op、ts、state、customer_id 4个参数参与签名 (规则同上)
state string 第三方传入的状态信息,晓多会原样回传给第三方,长度限制1024字节
customer_id string 顾客ID
msg obj 消息 消息定义

返回值json:

{
     "error_code":0,
     "info":"",
}

返回值说明:

参数 类型 描述
error_code int 错误码
info string 描述

获取未读消息

/v1/api/get_unread_msgs

请求方式:

post body (utf8 json)

请求参数:

{
     "unit_id":1001,
     "channel_id": 1001,
     "ts": 1529800000,
     "sign":"",
     "customer_id":"tid"
}
字段 类型 必填 描述
unit_id int 企业id
channel_id int 渠道id
ts int unix时间戳
customer_id string 顾客ID
sign string 签名 unit_id、channel_id、ts、customer_id 4个参数(规则同上)
msgs obj arry 消息 消息定义

返回值json:

{
     "error_code":0,
     "info":"",
     "unread_num": 3,
     "new_msgs":[
         {
             "type":"TIMTextElem", // 文本
             "content":{
                 "Text":"hello!"
             },
             "random":1529874653389
         },
         {
             "type":"TIMImageElem", // 图片
             "content":{
                 "ImageInfoArray":[ // 使用数组的原因是很多其实一个图片包含大图、中图、小图。如果只有一副,填一个即可
                     {
                         "Size":1024,
                         "Width":50,
                         "Hight":60,
                         "URL":""
                     }
                 ]
             },
             "random":1529874653301000
         }

     ]

}

返回值说明:

参数 类型 描述
error_code int 错误码
info string 描述
unread_num int 未读消息数
new_msgs array obj 未读消息

错误码:

错误码 描述
0 成功
1 参数错误
2 系统错误
100025 系统繁忙
100027 签名错误
100028 参数错误

results matching ""

    No results matching ""