====== API 开放平台 ======

----

===== 平台概述 =====

环信通过API开放平台提供对外可调用的接口。


===== 平台使用说明 =====

  * 调用平台的接口前需要根据clientID和secretID生成accessToken，clientID和secretID请联系环信获取。
  * 把accessToken放在调用接口的请求头中，字段名为:Kefu-Token，即可正确使用平台接口。

===== 平台错误码说明 =====

^错误码		^错误信息	^注释^
|API_001	|param is invalid,please check your param is correct!	|参数传递错误|
|API_002	|token is invalid       |token 不正确|
|API_003	|tenantId is incorrect,please confirm that the tenant ID belongs to you	|租户ID错误|
|API_004	|clientId or secretId is incorrect       |clientId或secretId不正确|
|API_111	|page index must be more than 0.	|分页索引必须大于0|
|API_112	|page size must be less than 50.       |分页每页的容量不能大于50|
|API_400	|api request failed       |服务间调用请求错误|

===== 获取accessToken =====

环信提供的开放接口需要权限才能访问，权限通过发送 HTTP 请求时携带 accessToken 来体现，下面描述获取 accessToken 的方式。说明：API 描述的时候使用到的 {client_id} 之类的这种参数需要替换成具体的值。

重要提醒：获取的 accessToken 在2小时之内有效，由于网络延迟等原因，系统不保证 accessToken 在此值表示的有效期内绝对有效，如果发现 accessToken 使用异常请重新获取新的 accessToken。

==== 获取accessToken ====

  * Path：http://kefu.easemob.com/api/platform/tenants/{tenantId}/accessToken
  * HTTP Method：POST
  * 接口参数：
          * Request Headers:{Cookie=${Cookie}和Content-Type=application/json}
          * Request Body体中加入租户的如下信息:
        <code json>
        {
            "tenantId":租户ID,
            "clientId":"8340a6d8-211f-4b81-9202-63ce46f27c02",
            "secretId":"ca906984-80f1-41b0-a272-6000df3f76c4"
        }
        </code>
   * 可能的错误码：API_003（租户ID错误），API_004（clientId或secretId不正确）。详见：[[#平台错误码说明|平台错误码说明]]
       
Response示例：
<code json>
{
    "status": "OK",
    "entity": {
        "accessToken": "4313913457bfd684eccbbb7405ba074f",
        "expireTime": 7200
    }
}
</code>

===== 调用平台接口 =====

获取到accessToken后，即可以正常调用平台接口。以下为平台接口：

==== 获取访客的绑定关系 ====

通过此接口，可以获取访客绑定的技能组。每次请求的访客数量不能多于10个。

  * Path：http://kefu.easemob.com/api/platform/tenants/{tenantId}/firstReceptionBindByVisitorusername
  * HTTP Method：POST
  * 接口参数：
        * Request Headers:{Cookie=${Cookie}、Content-Type=application/json和Kefu-Token=${accessToken}}
        * Request Body体中封装接口需要的参数:
        <code json>
        [
            {
                 "username": "webim-visitor-FQKXRPTF7KHPEGY2YCTF",
                 "techChannelId": "1",
                 "techChannelType": "easemob"
            },
            {
                 "username": "webim-visitor-MM8QTBKVTVPF86Q436G2",
                 "techChannelId": "1",
                 "techChannelType": "easemob"
            }
        ]
        </code>
        * 可能的错误码：API_020（请求访客绑定关系的数量不能多于10个）。

Response示例：
<code json>
{
    "status": "OK",
    "entity": [
        {
            "bindId": 47,
            "visitor": {
                "id": "16b71ffb-dfe0-4b58-9e7d-f2be894ab39c",
                "username": "webim-visitor-FQKXRPTF7KHPEGY2YCTF",
                "nickname": "webim-visitor-FQKXRPTF7KHPEGY2YCTF"
            },
            "agent": {
                "id": "6aed2d51-4d54-468a-995e-efa38f916ccd",
                "username": "pengfeima@easemob.com",
                "nickname": "Admin",
                "agent_queues": [
                    {
                        "queueId": 59929,
                        "queueName": "人工客服"
                    },
                    {
                        "queueId": 59931,
                        "queueName": "研发客服"
                    }
                ]
            },
            "createAt": "2018-08-15 10:44:44"
        },
        {
            "bindId": 46,
            "visitor": {
                "id": "a625c4fe-73c0-4321-9921-28d3e3b1f412",
                "username": "webim-visitor-MM8QTBKVTVPF86Q436G2",
                "nickname": "webim-visitor-MM8QTBKVTVPF86Q436G2"
            },
            "agent": {
                "id": "6aed2d51-4d54-468a-995e-efa38f916ccd",
                "username": "pengfeima@easemob.com",
                "nickname": "Admin",
                "agent_queues": [
                    {
                        "queueId": 59929,
                        "queueName": "人工客服"
                    },
                    {
                        "queueId": 59931,
                        "queueName": "研发客服"
                    }
                ]
            },
            "createAt": "2018-08-15 10:38:45"
        }
    ]
}
</code>

注：
  * 当请求的多组数据中，部分数据存在问题时（如username错误），将只返回部分正确的结果，存在问题的部分数据将没有返回值；
  * 当请求的多组数据中，部分访客无绑定关系时，无绑定关系的部分只返回访客信息，绑定关系返回null。