钉钉企业消息开发

钉钉企业通知消息功能开发笔记

一.钉钉dingtalk.corp.message.corpconversation.asyncsend (企业会话消息异步发送)

    企业可以主动发送消息给员工，此接口是/message/send的异步化版本，性能会好一点。目前支持text、image、voice、file、link、OA消息。限制：isv开发者给同一用户发消息一天不得超过50次。企业开发者每分钟最多可条用1500次，全员消息每天不得超过3次，isv每分钟最多条用200次，不允许发送全员消息。

    请求地址：https://eco.taobao.com/router/rest

     必要公共参数：

1.method    api接口名称

2.session    钉钉授权的token（isv开发者和企业开发者）

3.timestamp    时间戳

4.v    api协议版本（目前好像只支持2.0）

     必要请求参数：

1.msgtype    消息类型（如text、oa、image等）

2.agent_id    微应用的id

3.msgcontent    具体消息（json）

     非必要参数：

1.userid_list    收到信息的用户id（可以为多个人，中间以“，”隔开，最大发送人数为20）。ps：建议只是单对单用户发送时使用。

2.dept_id_list    收到信息的组织id（可以为多个组，但是最大为20组）。ps：建议对整组都发消息时使用，userid_list和dept_id_list同时存在时，会给该用户，和该组所有人都发。。。。。。

3.to_all_user    是否发送给所有人，默认值为false。ps：一般都不需要这个参数，因为一般不会给所有人发送消息通知。当需要给所有人发送时，需填值true。并且上面两个参数可以不写，写了也无效。。。

二.ISV和企业开发者

    钉钉推出的接口会因为开发者的身份有一些区别，如上面说的消息发送部分，钉钉允许isv开发者和企业开发者有不同的限制。

    在开发接口时，所需要的必要参数token也会因为开发者身份不同获取方式不同。

    isv开发者：在获取token前需要先经过整个isv的授权流程。

        1.isv创建套件，并由管理员授权

        2.获取应用套件令牌

           接口地址： https://oapi.dingtalk.com/service/get_suite_token（post方式）

//请求参数：{      "suite_key":"key_value",    //应用套件key    "suite_secret": "secret_value",     //应用套件secret    "suite_ticket": "ticket_value"      //钉钉后台推送的ticket}//返回数据：{      "suite_access_token":"61W3mEpU66027wgNZ_MhGHNQDHnFATkDa9-2llqrMBjUwxRSNPbVsMmyD-yq8wZETSoE5NQgecigDrSHkPtIYA",  //应用套件access_token    "expires_in":7200 //有效时间}

3.获取授权码

            临时授权码：用于用户对应用进行授权时使用，保证安全。

{     "SuiteKey": "suitexxxxxx",  //应用套件的key    "EventType": " tmp_auth_code",  //授权码类型    "TimeStamp": 1234456, //时间戳    "AuthCode": "adads"     //临时授权码}

   永久授权码：获得永久授权码后，可以用来获取换取授权信息等。可以存储，留着以后也可以用。

           接口地址：https://oapi.dingtalk.com/service/get_permanent_code?suite_access_token=xxxx（post方式）

//请求参数{       "tmp_auth_code": " value"   //获取的临时授权码}//返回数据{       "permanent_code": "xxxx",   //永久授权码    "ch_permanent_code":"xxxx", //企业服务窗永久授权码    "auth_corp_info":         //授权方企业信息        {            "corpid": "xxxx",   //授权方id            "corp_name": "name" //授权方名称        }}

4.获取企业授权凭证

        5.获取企业授权信息

        6.激活授权套件

        isv只能通过企业对isv的授权获取token，如上面3、4点（好麻烦。。。）。

企业开发者：对企业开发者来说，获取token需要CorpId和CorpSecret。CorpId和CorpSecret分别是公司的唯一id和凭证，可以在钉钉为企业提供的开发者后台中看到。

        接口地址：https://oapi.dingtalk.com/gettoken?corpid=id&corpsecret=secrect （get方式）

//请求参数{    "corpid": xxx,    //公司id    "corpsecret": xxxx,   //公司凭证} //得到数据（json）{       "errcode": 0, //错误码    "errmsg": "ok", //错误信息    "access_token": "fw8ef8we8f76e6f7s8df8s"    //获得的token}//得到的错误信息{      "errcode": 43003,    "errmsg": "require https"}

* dingtalk.corp.message.corpconversation.asyncsendbycode (通过用户授权码异步向企业会话发送消息)：这个接口与上述的不同在与这个接口可以让用户通过授权码异步向企业发送消息。

附一张钉钉消息的发送关系：