钉钉接口学习笔记

接口说明格式

请求方式：GET/POST(HTTPS)

请求地址：https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=USERID

请求包体：

​ …

SDK请求示例：

​ …

返回结果：

​ …

1）请求方式，标明接口调用的HTTP方法，区分HttpGet/HttpPost请求。所有的请求都为HTTPS协议。

2）请求地址，接口的请求地址

3）请求包体/参数说明，标明请求参数实例及说明，参数说明包括字段含义、取值范围。

4）SDK请求示例，使用SDK时，调用接口的代码示例。

5）返回结果/参数说明，标明返回参数示例及说明。所有接口的返回结果里都有errcode、errmsg。开发者需根据errcode是否为0判断是否调用成功。而errmsg仅做参考，后续可能会有变动，因此不可作为是否调用成功的判据。

接口权限申请

权限类型

根据权限作用不同，分为以下两种权限类型：

权限类型	说明	申请流程
通用权限	包含审批等权限	开发者后台提交申请，需审批通过
特殊权限	非公共的特殊接口权限申请	开发者后台提交申请，需审批通过

权限申请流程

1. 打开权限申请页面

   步骤一：打开需申请权限的应用

   登录开发者后台，点击应用开发-第三方企业应用-找到开发的应用，点击应用图标。

   步骤二：打开接口权限申请页面，并根据业务需要，申请接口权限

2. 申请权限

   在开发者后台，申请接口权限均需要审批。

   （1）申请通用权限

   ​ 开发者在申请审批等接口权限时，需尽可能详细地描述使用场景。

   （2）申请特殊权限

   ​ 开发者在申请特殊权限时，需尽可能详细地描述权限接口及使用场景

应用授权

第三方企业应用，需要企业授权开通应用后才可以使用；在企业授权后，您会收到授权开通事件，正确处理后完成企业授权流程。

企业授权应用

（1）开发测试阶段

​ 可以在开发者后台给体验组织开通第三方应用，开通后，钉钉后台会推送授权信息到第三方应用后台。

（2）发布上线后

​ 如果应用已上架到应用市场，企业管理员可以在应用市场授权开通第三方应用，开通后，钉钉后台会推送授权信息到第三方应用后台。

​ 如果应用未上架到应用市场，可以使用应用的线下部署二维码进行扫码安装。

推送授权信息

企业授权开通应用事件用于通知第三方应用“哪个组织开通了本应用”，第三方应用后台收到此事件后，需要初始化企业信息。

目前，钉钉支持两种推送方式：

（1）钉钉云推送，正式应用只支持钉钉云推送

（2）HTTP回调，只有测试应用可以选择HTTP推送

选择推送方式

应用类型不同，可选择的推送方式不同。推送方式选择后无法修改。

应用类型	测试应用	正式应用
是否可以上架	无法上架	可上架
IP白名单限制	不受限制	需填写IP白名单
推送	HTTP推送或钉钉云推送	只能使用钉钉云推送

测试应用，选择“钉钉云推送”后，可以使用企业的MySQL，也可以使用钉钉云rds作为推送源。

接口调用

获取企业凭证

企业凭证，即企业授权给第三方企业应用时，第三方企业应用获取企业的凭证access_token。第三方企业应用可以使用access_token调用接口获取企业的相关信息。

调试工具：在线调试

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/service/get_corp_token?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

{	

	"auth_corpid":"auth_corpid_value"

}

参数说明：

参数	类型	必须	说明
accessKey	URL参数	是	第三方应用的suiteKey
timestamp	URL参数	是	当前时间戳，单位是毫秒
suiteTicket	URL参数	是	钉钉推送的suiteTicket。测试应用可以随意填写
signature	URL参数	是	以timestamp+"\n"+suiteTicket为签名字符串，suiteSecret为签名密钥，使用算法HmacSHA256计算的签名值。注意：计算出签名值以后，需要进行urlencode，才能把签名参数拼接到url中
auth_corpid	Http body	是	授权企业corpid，组装为JSON结构置于http post body部分

SDK请求示例（Java）

DefaultDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_corp_token");

OapiServiceGetCorpTokenRequest req = new OapiServiceGetCorpTokenRequest();

req.setAuthCorpid("dingc365fcabbf733c3535c2f4657eb6356f");

OapiServiceGetCorpTokenResponse execute = client.execute(req,"suiteKey","suiteSecrect","suiteTicket");

返回结果：

参数	说明
access_token	授权方（企业）corp_access_token
expires_in	access_token有效时间，单位秒

返回结果示例：

{

	"access_token":"xxxxxx",

	"expires_in":7200

}

获取企业授权信息

调试工具：在线调试

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/service/get_auth_info?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体：

{

	"auth_corpid":"auth_corpid_value"

}

参数说明：

参数	类型	必须	说明
accessKey	URL参数	是	应用的suiteKey
timestamp	URL参数	是	当前时间戳，单位是毫秒
suiteTicket	URL参数	是	钉钉推送的suiteTicket，测试应用可以随便填写
signature	URL参数	是	以timestamp+"\n"+suiteTicket为签名字符串，suiteSecret为签名密钥，使用算法HmacSHA256计算的签名值。注意：计算出签名以后，需要进行urlencode，才能把签名参数拼接到url中。
auth_corpid	Http body	是	授权企业方corpid，组装为JSON结构置于http post body部分

SDK请求示例（Java）

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_auth_info");

OapiServiceGetAuthInfoRequest req = new OapiServiceGetAuthInfoRequest();

req.setAuthCorpid("dingc365fcabbf733c3535c2f4665eb6487f");

OapiServiceGetAuthInfoResponse response = client.execute(req,"suiteKey","suiteSecrect","suiteTicket");

返回结果：

参数	说明
auth_corp_info	授权方企业信息
corpid	授权方企业id
invite_code	邀请码，只有自己邀请的企业才会返回邀请码，可用该邀请码统计不同渠道的拉新，否则值为空字符串
industry	企业所属行业
corp_name	授权方企业名称
license_code	序列号
auth_channel	渠道码
auth_channel_type	渠道类型，为了避免渠道码重复，可与渠道码共同确认渠道（可能为空。非空时当前只有满天星类型，值为STAR_ACTIVITY
is_authenticated	企业是否认证
auth_level	企业认证等级，0：未认证，1：高级认证，2：中级认证，3：初级认证
invite_url	企业邀请链接
corp_province	授权企业所在省份
corp_city	授权企业所在城市
auth_user_info	授权方管理员信息
corp_logo_url	企业logo
auth_info	授权信息
agent	授权的应用信息
agentid	授权方应用id
channel_auth_info	授权的服务窗应用信息列表
agent_name	授权方应用名字
logo_url	授权方应用头像
appid	应用id
auth_info.agent.admin_list	对此微应用有管理权限的管理员userid

返回结果示例：

{
   "auth_corp_info":{
      "corp_logo_url":"http://xxxx.png",
      "corp_name":"corpid",
      "corpid":"auth_corpid_value",
      "industry":"互联网",
      "invite_code" : "1001",
      "license_code": "xxxxx",
      "auth_channel": "xxxxx",
      "auth_channel_type": "xxxxx",
      "is_authenticated":false,
      "auth_level":0,
      "invite_url":"https://yfm.dingtalk.com/invite/index?code=xxxx",
    "corp_province":"浙江",
    "corp_city":"杭州"
    },
    "auth_user_info":
    {
        "userId":""
    },
    "auth_info":{
    "agent":[{
            "agent_name":"aaaa",
            "agentid":1,
            "appid":-3,
            "logo_url":"http://aaaaaa.com",
            "admin_list":["zhangsan","lisi"]
    }
    ,{
            "agent_name":"bbbb",
            "agentid":4,
            "appid":-2,
            "logo_url":"http://vvvvvv.com",
            "admin_list":[]
    }]
    },
        "channel_auth_info": {
        "channelAgent": [
                {
                    "agent_name": "应用1",
                    "agentid": 36,
                    "appid": 6,
                    "logo_url": "http://i01.lw.test.aliimg.com/media/lALOAFWTc8zIzMg_200_200.png"
                },
                {
                    "agent_name": "应用2",
                    "agentid": 35,
                    "appid": 7,
                    "logo_url": "http://i01.lw.test.aliimg.com/media/lALOAFWTc8zIzMg_200_200.png"
                }]
        },
     "errcode":0,
    "errmsg":"ok"
}

获取授权应用信息

该API用于获取已授权开通的企业的某个应用的基本信息，包括LOGO、名称、描述等。

调试工具：在线调试

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/service/get_agent?signature=kKlP1QmmXXX&timestamp=1527130370219&suiteTicket=xxx&accessKey=suitezmpdnvsw4xxxxx

POST请求包结构体：

{

	"suite_key":"key_value",

	"auth_corpid":"auth_corpid_value",

	"agentid":541

}

请求参数说明：

参数	类型	必须	说明
accessKey	URL参数	是	应用的suiteKey
timestamp	URL参数	是	当前时间戳，单位是毫秒
suiteTicket	URL参数	是	钉钉给应用推送的ticket，测试应用可以随便填写
signature	URL参数	是	以timestamp+"\n"+suiteTicket为签名字符串，suiteSecret为签名密钥，使用算法HmacSHA256计算的签名值。注意：计算出签名以后，需要进行urlencode，才能把签名参数拼接到url中

POST参数说明：

参数	说明
suite_key	应用套件key
auth_corpid	授权企业方corpid
agentid	授权企业方应用id

SDK请求示例（Java）：

DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.com/service/get_agent");

OapiServiceGetAgentRequest request = new OapiServiceGetAgentRequest();

request.setAuthCorpid("dingd610f0141e19fa4d35c2f4657eb637fxxxx");

request.setSuiteKey("suitezmpdnvsw4syq53g6xxx");

request.setAgentid("211164860xxxx");

OapiServiceGetAgentResponse response = client.execute(request,"suiteKey","suiteSecret","suiteTicket");

返回结果：

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
agentid	授权方企业应用id
name	授权方企业应用名称
logo_url	授权方企业应用头像
description	授权方企业应用详情
close	授权方企业应用是否被禁用（0：禁用 1：正常 2：待激活）

返回结果示例：

{

	"agentid":541,

	"name":"公告",

	"logo_url":"http://xxxxxxxxx/png",

	"description":"企业重要消息",

	"close":1,

	"errcode":0,

	"errmsg":"ok"

}

HTTP回调

使用HTTP回调方式时，钉钉会向应用推送回调事件数据包。使用应用创建后开发者填写的应用加解密key来进行加密，使用开发者填写的应用Token进行签名，应用在收到推送后需要进行验证签名和解密，并且返回包含经过加密的字符串的json数据。

HTTP回调方式包括以下主要场景：

1. 应用创建后设置回调URL并验证有效性：

   a.验证回调URL有效性事件

   b.应用回调地址更新事件

2. 定期推送suite_ticket：

   a.接收应用的suite_ticket

3. 企业管理员在管理应用时：

   a.企业授权开通应用事件

   b.通讯录授权范围变更事件

   c.应用逻辑停用事件

   d.应用逻辑启用事件

   e.解除企业授权事件

4. 企业下单购买您的收费商品后，可以通过回调事件拿到用户购买的商品规格对应的规格参数，以及企业购买的服务时长。对应的回调事件为：

   ​ a.用户购买下单时间、

验证回调有效性

开发者在创建完应用后，在开发者后台-应用首页点击“设置回调-设置”，填写回调地址并验证回调地址有效性（若验证不成功，正式应用将不能进行开通，而测试应用可以开通）

开发者点击“验证有效性”时，钉钉服务器对回调地址推送“验证回调URL有效性事件”，应用收到推送后需要返回“success”的加密值。

回调事件处理步骤

角色	ACTION
钉钉	向ISV的回调URL推送加密消息
应用	解密消息并解析事件类型
应用	针对不同的事件类型处理业务逻辑（例如验证回调事件：check_create_suite_url）
应用	返回“success”的加密值【JSON数据格式】

回调URL说明：

字段	属性
回调URL	以http://或https://开头，系统将会把此应用的suiteTicket，临时授权码以及授权变更等事件等推送给此URL

开发者需要将开发者后台中设置的token、suiteKey、数据加密密钥配置到实例demo中的配置文件中，再点击“验证回调URL有效性”方可验证生效。

回调的URL参数：

开发者点击“验证URL的有效性”后，钉钉服务器将如下参数追加到回调URL上：

字段	属性
signature	加密签名
timestamp	时间戳
nonce	随机数

回调数据参数说明：

参数	说明
Random	随机字符串
EventType	check_create_suite_url

应用返回参数说明：

应用收到消息后返回给钉钉服务器的数据参数说明

参数	说明
msg_signature	消息体签名
timeStamp	时间戳
nonce	随机字符串
encrypt	“success”字段的加密字符串

接收回调消息

在接收回调消息之前首先要拿到创建应用时填写的“回调URL”，“Token”，“数据加密密钥（ENCODING_AES_KEY）”，点击您创建的应用，选择“应用信息”-“查看详情”

参数说明：

参数	说明
回调URL	ISV接收钉钉推送数据的地址
Token	ISV在注册时任意填写的（建议3~32位英文字母+数字组合），用来生成signature，并和回调参数中的signature比对，校验消息的合法性
数据加密密钥（ENCODING_AES_KEY）	用于消息体的加解密
suiteKey	应用key

推送suite_ticket

钉钉开放平台会向应用的回调URL不定期（约20分钟）推送suite_ticket，注意：开发者需要持久化TICKET，不要设置20分钟失效的缓存时间，新的ticket推送会使之前的ticket失效。

应用在收到ticket推送后务必返回经过加密的字符串“success”的json数据。

如果不返回，钉钉服务器将连续推送，直到推送次数超过100次，就不再推送。倘若您希望钉钉服务器重新推送，需要进入开发者后台，点击您创建的应用，进入应用信息列表，再点击查看详情，点击“重新推送”按钮，即可重新推送。

POST数据解密后示例：

{

	"SuiteKey":"xxxxxx",

	"EventType":"suite_ticket",

	"TimeStamp":123456,

	"SuiteTicket":"xxxxxx"

}

参数	说明
SuiteKey	应用的SuiteKey
EventType	suite_ticket
TimeStamp	时间戳
SuiteTicket	Ticket内容

返回说明：

服务提供商在收到此事件推送后务必返回包含经过加密的字符串“success”的json数据。

{

	"msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",

	"timestamp":1783284283",

	"nonce":"123456",

"encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"

}

参数	说明
msg_signature	消息体签名
timestamp	时间戳
nonce	随机字符串
encrypt	“success”加密字符串

授权开通事件

当企业开通授权第三方企业应用后，钉钉服务器会向创建应用时填写的回调URL推送临时授权码。

推送数据解密后示例：

{

"TimeStamp":1553709079062,

"AuthCode":"xxxxxx",

"AuthCorpId":"xxxxxx",

"EventType":"tmp_auth_code",

"SuiteKey":"xxxxxx"

}

字段说明：

参数	说明
SuiteKey	应用的SuiteKey
EventType	推送类型，临时授权码的类型是tmp_auth_code
TimeStamp	时间戳
AuthCorpId	授权开通应用企业的corpId
AuthCode	临时授权码

返回说明：

服务提供商在收到“开通授权事件”后务必返回包含经过加密的字符串“success”的json数据。只有返回了对应的json数据，钉钉才会判断此事件推送成功。

参数	说明
msg_signature	消息体签名
timestamp	时间戳
nonce	随机字符串
encrypt	“success”的加密字符串

获取第三方应用凭证

该API用于获取第三方应用凭证（suite_access_token）

API中除了合法来源IP校验之外，还增加了suite_ticket作为安全凭证。钉钉开放平台会向应用的HTTP回调URL不定期（约20分钟）推送suite_ticket。

注意：需要持久化TICKET，不要设置20分钟失效的缓存时间，新的ticket推送会使之前的ticket失效。

请求方式：POST（HTTPS）

请求地址：https://oapi.dingtalk.com/service/get_suite_token

POST请求包结构体：

{

"suite_key":"xxx",

"suite_secret":"xxx",

"suite_ticket":"xxx"

}

请求说明：

参数	类型	必须	说明
suite_key	String	是	套件key，开发者后台创建套件后获取
suite_secret	String	是	套件secret，开发者后台创建套件后获取
suiteTicket	String	是	钉钉推送的suiteTicket。测试应用可以随意填写

返回结果：

参数	说明
suite_access_token	应用套件access_token
expires_in	有效期7200秒，过期之前要主动更新（建议ISV服务端做定时器主动更新，而不是依赖钉钉的定时推送）

获取企业永久授权码

该API用于使用临时授权码换取企业的永久授权码，并可通过该永久授权码换取该企业授权信息、企业access_token。

注意：临时授权码只能使用一次

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/service/get_permanent_code?suite_access_token=SUITE_ACCESS_TOKEN

POST请求包结构体：

{

"tmp_auth_code":"xxx"

}

请求说明：

参数	类型	必须	说明
suite_access_token	String	是	套件令牌Token
tmp_auth_code	String	是	临时授权码

返回结果：

参数	说明
permanent_code	永久授权码
auth_corp_info	授权方企业信息
corpid	授权方企业id
corp_name	授权方企业名称

激活应用

该API用于在企业开通授权应用后，激活企业授权的应用。

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/service/activate_suite?suite_access_token=SUITE_ACCESS_TOKEN

POST请求包结构体：

{

"suite_key":"xxxxxx",

"auth_corpid":"xxxxxx",

"permanent_code":"xxxxxx"

}

请求说明：

参数	类型	必须	说明
suite_access_token	String	是	套件令牌Token
suite_key	String	是	套件key
auth_corpid	String	是	授权企业corpid
permanent_code	String	是	企业的永久授权码

返回结果：

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容

停用应用

服务提供商在收到“企业停用应用”事件推送后务必返回包含经过加密的字符串“success”的json数据。

POST数据解密后示例：

 {

 "AgentId":123,

 "AppId":123,

 "AuthCorpId":"xxxxxx",

 "EventType":"org_micro_app_stop",

 "SuiteKey":"xxxxxx",

 "TimeStamp":1481173967075

 }

启用应用

POST数据解密后示例：

{
    "AgentId":123,
    "AppId":123,
    "AuthCorpId":"xxxxxx",
    "EventType":"org_micro_app_restore",
    "SuiteKey":"xxxxxx",
    "TimeStamp":1481173967075
}

通讯录授权范围变更事件

当授权方（即授权企业）在钉钉手机客户端-微应用管理中，修改了对应用的授权企业通讯录范围后，钉钉服务器会向服务提供商创建应用时填写的回调URL推送授权变更消息。注意：推送的授权变更信息并不包括企业用户具体做了什么修改，所以收到推送之后，ISV需要通过调用“获取通讯录权限接口”查询新的授权范围。

POST数据解密后示例：

{
    "SuiteKey":"xxxxxx",
    "EventType":"change_auth",
    "TimeStamp":123456,
    "AuthCorpId":"xxxxxx"
}

字段说明：

参数	说明
SuiteKey	应用的SuiteKey
EventType	change_auth
TimeStamp	时间戳
AuthCorpId	授权方企业的corpid

返回说明：

服务提供商在收到此事件推送后务必返回包含经过加密的字符串“success”的json数据。

{
    "msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",
    "timestamp":"178364422409",
    "nonce":"123456",
    "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
}

参数	说明
msg_signature	消息体签名
timeStamp	时间戳
nonce	随机字符串
encrypt	“success”加密字符串

解除授权事件

此事件的推送会发生在企业解除应用授权的时候，发生了“解除授权”事件之后，假设企业用户又重新发起授权，应用将重新收到授权开通事件。

POST数据解密后示例：

{
    "EventType":"suite_relieve",
    "SuiteKey":"xxxxxx",
    "TimeStamp":"1223434678",
    "AuthCorpId":"xxxxxx"
}

参数	说明
SuiteKey	应用的SuiteKey
EventType	推送类型suite_relieve
TimeStamp	时间戳
AuthCorpId	授权方企业的corpid

返回说明:

服务提供商在收到“解除授权”事件推送后务必返回包含经过加密的字符串“success”的json数据。只有返回了对应的json数据，钉钉才会判断此事件推送成功。

{
    "msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",
    "timestamp":"1783810395",
    "nonce":"123456",
    "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
}

参数	说明
msg_signature	消息体签名
timestamp	时间戳
nonce	随机字符串
encrypt	“success”的加密字符串

用户购买下单事件

此事件的推送会发生在企业在钉钉应用市场下单购买应用后，向ISV应用回调地址POST数据。

POST数据解密后示例：

{
    "EventType":"market_buy",
    "SuiteKey":"xxxxxx",
    "buyCorpId":"xxxxxx",
    "goodsCode":"FW_GOODS-xxxxxxxx",
    "itemCode":"1c5f70cf04c437fb9aa1b20xxxxxxxx",
    "itemName":"按照范围收费规格0-300",
    "subQuantity":1,
    "maxOfProple":300,
    "minOfPeople":0,
    "orderId"308356401xxxxxxxx,
    "paidtime":1474535702000,
    "serviceStopTime":1477065600000,
    "payFee":147600,
    "orderCreateSource":"DRP",
    "nominalPayFee":147600,
    "discountFee":600,
    "discount":0.06,
    "distributorCorpId":"xxxxxx",
    "distributorCorpName":"测试企业"
}

参数说明：

参数	说明
EventType	market_buy
SuiteKey	用户购买应用的SuiteKey
buyCorpId	购买该应用企业的corpid
goodsCode	购买的商品码
itemCode	购买的商品规格码
itemName	购买的商品规格名称
maxOfPeople	购买的商品规格能服务的最多企业人数
minOfPeople	购买的商品规格能服务的最少企业人数
orderId	订单id
paidtime	下单时间
serviceStopTime	该订单的服务到期时间
payFee	订单支付费用，以分为单位
orderCreateSource	订单创建来源，如果来自钉钉分销系统，则值为“DRP”
nominalPayFee	钉钉分销系统提单价，以分为单位
dicountFee	折扣减免费用
discount	订单折扣
distributorCorpId	钉钉分销系统提单的代理商的企业corpid
distributorCorpName	钉钉分销系统提单的代理商的企业名称

返回说明：

服务提供商在收到“用户下单购买”时间推送后务必返回包含经过加密的字符串“success”的json数据。

{
    "msg_signature":"111108bb8e6dbce3c9671d6fdb69d15066227608",
    "timestamp":"1783610513",
    "nonce":"123456",
    "encrypt":"1ojQf0NSvw2WPvW7LijxS8UvISr8pdDP+rXpPbcLGOmIBNbWetRg7IP0vdhVgkVwSoZBJeQwY2zhROsJq/HJ+q6tp1qhl9L1+ccC9ZjKs1wV5bmA9NoAWQiZ+7MpzQVq+j74rJQljdVyBdI/dGOvsnBSCxCVW0ISWX0vn9lYTuuHSoaxwCGylH9xRhYHL9bRDskBc7bO0FseHQQasdfghjkl"
}

参数	说明
msg_signature	消息体签名
timestamp	时间戳
nonce	随机字符串
encrypt	“success”加密字符串

身份验证

身份验证“免登”是指用户进入应用后，无需输入钉钉用户名和密码，应用程序可自动获取当前用户身份，进而登录系统的流程。

第三方企业应用免登

当您以ISV的身份开发一款第三方企业应用，作为公开的云端Saas服务给任何潜在的企业客户安装使用，企业员工在钉钉内使用该ISV应用时，只要直接点应用，便可免输入账户密码实现自动登录您的系统。

获取免登授权码

PC端暂不支持小程序开发，如果要开发PC端应用，需使用微应用开发方式。

1. 小程序获取免登授权码

   企业应用和个人应用的免登授权码均可通过该JSAPI获取。

   dd.getAuthCode({
   	success:function(res){
   		/*{
   			authCode:'hYLK98jkf0m'
   		}*/
   	},
   	fail:function(err){
   	}
   });
   

   返回说明：

   参数	说明
   authCode	授权码。有效期5分钟，且只能使用一次，使用后会失效

2. 微应用获取免登授权码

   使用以下代码获取免登授权码（调用此api不需要进行鉴权，即不需要进行dd.config）。获取的免登授权码有效期5分钟，且只能使用一次。

   dd.ready(function(){
       dd.runtime.permission.requestAuthCode({
           corpId:_config.corpId,
           onSuccess:function(info) {
               code = info.code
           }
       });
   });
   

获取access_token

获取企业凭证access_token，请参考获取企业凭证。

获取用户userid

通过免登授权码和access_token，获取用户的userid。

调试工具：在线调试

请求方式：GET(HTTPS)

请求地址：https://oapi.dingtalk.com/user/getuserinfo?access_token=access_token&code=code

参数说明：

参数	类型	必须	说明
access_token	Stirng	是	调用接口凭证
code	String	是	免登授权码

返回结果：

{
    "userid":"****",
    "sys_level":1,
    "errmsg":"ok",
    "is_sys":true,
    "errcode":0
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	员工在当前企业内的唯一标识，也称staffid
is_sys	是否是管理员，true：是，false：不是
sys_level	级别，1：主管理员，2：子管理员，100：老板，0：其他（如普通员工）

获取用户详情

调用该接口，可以获取用户的详细信息，如员工名字、职位信息等，不支持获取手机号。

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=USERID

参数说明：

参数	类型	必须	说明
access_token	Stirng	是	调用接口凭证
userid	String	是	员工id
lang	String	否	通讯录语言（默认zh_CN，未来会支持en_US）

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "name":"张三",
    "unionid":"PiiipyQqBNBii0HnCJ3zljcxxxxxx",
    "userid":"zhangsan",
    "isLeaderInDepts":false,
    "isBoss":false,
    "hiredDate":1520265600000,
    "isSenior":false,
    "department":[1,2],
    "orderInDepts":"{1:71738366882504}",
    "active":false,
    "avatar":"xxx",
    "isAdmin":false,
    "isHide":false,
    "jobnumber":"001",
    "position":"manager",
    "roles":[
        {
            "id":149507744,
            "name":"总监",
            "groupName":"职务"
        }
    ]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	员工在当前企业内的唯一标识，也称staffId
unionid	员工在当前开发者企业账号范围内的唯一标识，系统生成，固定值，不会改变
name	员工名字
active	是否已经激活，true表示已激活，false表示未激活
orderInDepts	在对应的部门中的排序，Map结构的json字符串，key是部门的id，value是人员在这个部门的排序值
isAdmin	是否为企业的管理员，true表示是，false表示不是
isBoss	是否为企业的老板，true表示是，false表示不是
isLeaderInDepts	在对应的部门中是否为主管：Map结构的字符串，key是部门的id，value是人员在这个部门中是否为主管，true表示是，false表示不是
isHide	是否号码隐藏，true表示隐藏，false表示不隐藏
department	成员所属部门id列表
position	职位信息
avatar	头像url
hiredDate	入职时间。Unix时间戳（在OA后台通讯录中的员工基础信息中维护过入职时间才会返回）
jobnumber	员工工号
isSenior	是否是高管
roles	用户所在角色列表
id	角色id
name	角色名称
groupName	角色组名称
realAuthed	是否实名认证

应用管理后台免登

当某个应用需要进行一些配置管理的时候，需要在创建应用的时候，输入【后台地址】，当管理员登录OA管理后台，在选择这个应用并点击时，无需管理员再次输入账户密码，直接进入到这个应用的管理后台。

配置微应用管理后台地址

在钉钉开发者后台上编辑开发的应用，设置管理后台地址。

当管理员登入OA管理后台，选择菜单工作台，点击某个应用，进入应用的管理后台。

获取免登过程中密钥（SSOSecret）

重要说明：通过开发者后台获取，使用开发者企业的SSOSecret。

登录钉钉开发者平台获取SSOSecret。

管理后台免登流程开发

第一步：获取免登授权码

当企业管理员登录OA管理后台后，并点击工作台中的应用，会自动跳转到应用的后台地址，钉钉会把code参数追加到此URL地址中。请保存code参数值，在后面的步骤会用到

第二步：获取应用后台免登的accessToken

本接口获取的access_token只在微应用后台管理免登服务中使用。

注意：ISV开发的应用后台免登用的accessToken，需使用ISV自己的corpId和SSOsecret来换取，不是管理员所在的企业的

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/sso/gettoken?corpid=id&corpsecret=ssosecret

参数说明：

参数	类型	必须	说明
corpid	String	是	企业id
corpsecret	String	是	这里必须填写专属的SSOsecret

返回结果：

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
access_token	获取到的凭证

第三步：获取应用管理员的身份信息

使用步骤一获取到的code和步骤二获取到的access_token换取微应用管理员的身份信息。

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/sso/getuserinfo?access_token=ACCESS_TOKEN&code=CODE

参数说明：

参数	类型	必须	说明
access_token	String	是	再次强调，此token不同于一般的accessToken，需要调用获取微应用管理员免登需要的AccessToken
code	String	是	通过Oauth认证给URL带上的CODE

返回结果：

参数	说明
corp_name	公司名字
corpid	公司corpid
is_sys	是否是管理员（在这里是true）
avatar	头像地址
email	email地址
name	用户名字
userid	员工在企业内的唯一id

扫码登录第三方网站

使用钉钉客户端扫码并确认登录您的web系统，在您的系统内获得正在访问用户的钉钉身份，而用户无需输入账号密码。

注意：此功能与企业自建应用/第三方企业应用无关，只能用扫码登录打开第三方网站，并且不是钉钉内的应用免登，此流程只能做到获取到用户身份（无手机号和企业相关信息）

获取appId及appSecret

点击进入钉钉开发者后台的页面，选择“应用开发”-“登录”，点击“创建扫码登录应用授权”。创建用于免登过程中验证身份的appId及appSecret，创建后即可看到appId和appSecret。

需提交字段	是否必填	说明
名称	必填	授权应用的名称
描述	必填	应用使用的场景
授权页面LOGO地址	必填	这个会显示在授权页面的中间页中，以http或https开头
回调域名	必填	应用回调的URL，以http或https开头。需和本文“构造扫码登录页面”填写的redirect_url域名保持一致，否则会提示无权限访问

构造扫码登录页面

Web系统可以通过两种方式实现钉钉扫码登录，如下：

方式一 使用钉钉提供的扫码登录页面

在企业Web系统里，用户点击使用钉钉扫描登录，第三方Web系统跳转到如下地址：

https://oapi.dingtalk.com/connect/qrconnect?appid=APPID&response_type=code&scope=snsapi_login&state=STATE&redirect_uri=REDIRECT_URI

url里的参数需要换成第三方Web系统对应的参数。在钉钉用户扫码登录并确认后，会302到你指定的redirect_uri，并向url参数中追加临时授权码code及state两个参数。

注意事项：参数redirect_uri=REDIRECT_URI涉及的域名，需和创建扫码登录应用授权时填写的回调域名一致，否则会提示无权限访问。

方式二 支持网站将钉钉登录二维码内嵌到自己页面中

用户使用钉钉扫码登录后JS会将loginTmpCode返回给网站。JS钉钉登录主要用途：网站希望用户在网站内就能完成登录，无需跳转到钉钉域下登录后再返回，提升钉钉登录的流畅性与成功率。

网站内嵌二维码钉钉登录JS的实现方法：

1. 在页面中先引入如下JS文件（支持https）

   <script src="https://g.alicdn.com/dingding/dinglogin/0.0.5/ddLogin.js"></script>
   

2. 在需要使用钉钉登录的地方实例化以下JS对象

   /*
   * 解释一下goto参数，参考以下例子：
   * var url = encodeURIComponent('http://localhost.me/index.php?test=1&aa=2');
   * var goto = encodeURIComponent('https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=appid&response_type=code&scope=snsapi_login&state=STATE&redirect_uri='+url)
   */
   var obj = DDLogin({
       id:"login_container",//这里需要你在自己的页面定义一个HTML标签并设置id
       goto:"",//参考注释里的方式
       style:"border:none;background-color:#FFFFFF;",
       width:"365",
       height:"400"
   })
   

   参数说明：

   参数	说明
   goto	goto参数结构：https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=APPID&response_type=code&scope=snsapi_login&state=STATE&redirect_uri=REDIRECT_URI,并且要将goto参数urlencode编码
   style	渲染二维码的区域的样式，可以自定义去除背景颜色和边框
   width	表示显示二维码的区域的宽。不代表二维码的大小，二维码大小是固定的210px*210px
   height	表示显示二维码的区域的高。不代表二维码的大小，二维码大小是固定的210px*210px

   您引入的js会在获取用户扫描之后将获取的loginTmpCode通过window.parent.postMessage(loginTmpCode,’*’);返回给您的网站。

   您可以通过以下代码获取这个loginTmpCode：

   var handleMessage = function(event) {
       var origin = event.origin;
       console.log("origin",event.origin);
       if(origin == "https://login.dingtalk.com") {
           var loginTmpCode = event.data;
           
           console.log("loginTmpCode",loginTmpCode);
       }
   };
   if(typeof window.addEventListener != 'undefined') {
       window.addEventListener('message',handleMessage,false);
   } else if(typeof window.attachEvent != 'undefined') {
       window.attachEvent('onmessage',handleMessage);
   }
   

   通过JS获取到loginCode后，需要由你构造并跳转到如下链接：

   https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=APPID&response_type=code&scope=snsapi_login&state=STATE&redirect_uri=REDIRECT_URI&loginTmpCode=loginTmpCode

   此链接处理成功后，会302跳转到你goto参数指定的redirect_uri，并向url参数中追加临时授权码code及state两个参数。

   参数	必须	说明
   appid	是	参看第1步获取，代表了你提供的服务
   redirect_uri	是	重定向地址（如果是第一种方式需要urlencode编码，如果是第二种方式则需要将JS goto参数整体urlencode编码，不要单独对redirect_uri编码），该地址使用域名需配置为appId对应的回调域名，回调域名是在获取appId及appSecret时填写
   state	是	用于防止重放攻击，开发者可以根据此信息来判断redirect_uri只能执行一次来避免重放攻击
   response_type	是	固定为code
   scope	是	固定为snsapi_login
   loginTmpCode	是	通过js获取到的loginTmpCode

服务端通过临时授权码获取授权用户的个人信息

通过临时授权码Code获取用户信息，临时授权码只能使用一次。

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/sns/getuserinfo_bycode?accessKey=xxx&timestamp=xxx&signature=xxx

请求包结构体：

{
    "tmp_auth_code":"23152698ea18304da4d0ce1xxxxx"
}

URL签名参数说明：

参数	说明
accessKey	应用的appId
timestamp	当前时间戳，单位是毫秒
signature	通过appSecret计算出来的签名值

参数说明：

参数	类型	必须	说明
tmp_auth_code	String	是	用户授权的临时授权码code，只能使用一次；在前面步骤中跳转到redirect_uri时会追加code参数

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "user_info":{
        "nick":"张三",
        "openid":"liSii8KCxxxxx",
        "unionid":"7Huu46kk"
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
user_info
nick	用户在钉钉上面的昵称
openid	用户在当前开放应用内的唯一标识
unionid	用户在当前开放应用所属企业的唯一标识

钉钉内免登第三方网站

当开发的系统（H5页面）只是在钉钉客户端打开，但并不是一个钉钉应用时，系统可以自动获得正在访问用户的钉钉身份信息，而无需用户再次输入账号密码。

注意：此功能与企业应用/第三方企业应用无关，只能用于钉钉客户端内打开的网站，并且不是钉钉内的应用免登，此流程只能做到获取到用户身份。

获取appId及appSecret

点击进入钉钉开发者平台的页面，选择“应用开发”-“移动接入应用”-“登录”，点击“创建扫码登录应用授权”创建用于免登过程中验证身份的appId及appSecret，创建后即可看到appId和appSecret。

需提交字段	说明
名称	授权微应用的名称，必填
描述	扫码登录用于，主要是说明使用的场景，必填
授权页面LOGO地址	这个会显示在授权页面的中间页中，以http或https开头，必填
回调域名	微应用回调的URL，以http或https开头，必填

构造要跳转的链接

构造如下跳转链接，此链接处理成功后，会重定向跳转到指定的redirect_uri，并向url追加临时授权码code及state两个参数。

https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=APPID&response_type=code&scope=snsapi_auth&state=STATE&redirect_uri=REDIRECT_URI

参数	说明
appid	参看第1步获取，代表了你提供的服务，必填
redirect_uri	重定向地址（需要urlencode编码），该地址所在域名需要配置为appid对应的安全域名，必填
state	用于防止重放攻击，开发者可以根据此信息来判断redirect_uri只能执行一次来避免重放攻击，必填
response_type	固定值为code，必填
scope	取值为snsapi_auth，必填（snsapi_auth用于钉钉容器内获取用户授权）

服务端通过临时授权码获取授权用户的个人信息

通过临时授权码Code获取用户信息，临时授权码只能使用一次。

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/sns/getuserinfo_bycode?accessKey=xxx&timestamp=xxx&signature=xxx

请求包结构体：

{
    "tmp_auth_code":"23152698ea18304da4d0ce1xxxxx"
}

URL签名参数说明：

参数	说明
accessKey	应用的appId
timestamp	当前时间戳，单位是毫秒
signature	通过appSecret计算出来的签名值

参数说明：

参数	类型	必须	说明
tmp_auth_code	String	是	用户授权的临时授权码code，只能使用一次；在前面步骤中跳转到redirect_uri时会追加code参数

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "user_info":{
        "nick":"张三",
        "openid":"liSii8KCxxxxx",
        "unionid":"7Huu46kk"
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
user_info
nick	用户在钉钉上面的昵称
openid	用户在当前开放应用内的唯一标识
unionid	用户在当前开放应用所属企业的唯一标识

密码登录第三方网站

获取appId及appSecret

点击进入钉钉开发者平台的页面，选择“应用开发”-“移动接入应用”-“登录”，点击“创建扫码登录应用授权”。创建用于免登过程中验证身份的appId及appSecret，创建后即可看到appId和appSecret。

需提交字段	说明
名称	授权微应用的名称，必填
描述	扫码登录使用 ，主要是说明使用的场景，必填
授权页面LOGO地址	这个会显示在授权页面的中间页中，以http或https开头，必填
回调域名	微应用回调的URL，以http或https开头，必填

构造要跳转的链接

构造如下跳转链接，此链接处理成功后，会重定向跳转到指定的redirect_uri，并向url追加临时授权码code及state两个参数。

https://oapi.dingtalk.com/connect/oauth2/sns_authorize?appid=APPID&response_type=code&scope=snsapi_auth&state=STATE&redirect_uri=REDIRECT_URI

参数	说明
appid	参看第1步获取，代表了你提供的服务，必填
redirect_uri	重定向地址（需要urlencode编码），该地址所在域名需要配置为appid对应的安全域名，必填
state	用于防止重放攻击，开发者可以根据此信息来判断redirect_uri只能执行一次来避免重放攻击，必填
response_type	固定值为code，必填
scope	取值为snsapi_auth，必填（snsapi_auth用于钉钉容器内获取用户授权）

服务端通过临时授权码获取授权用户的个人信息

通过临时授权码Code获取用户信息，临时授权码只能使用一次。

请求方式：POST(HTTPS)

请求地址：https://oapi.dingtalk.com/sns/getuserinfo_bycode?accessKey=xxx&timestamp=xxx&signature=xxx

请求包结构体：

{
    "tmp_auth_code":"23152698ea18304da4d0ce1xxxxx"
}

URL签名参数说明：

参数	说明
accessKey	应用的appId
timestamp	当前时间戳，单位是毫秒
signature	通过appSecret计算出来的签名值

参数说明：

参数	类型	必须	说明
tmp_auth_code	String	是	用户授权的临时授权码code，只能使用一次；在前面步骤中跳转到redirect_uri时会追加code参数

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "user_info":{
        "nick":"张三",
        "openid":"liSii8KCxxxxx",
        "unionid":"7Huu46kk"
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
user_info
nick	用户在钉钉上面的昵称
openid	用户在当前开放应用内的唯一标识
unionid	用户在当前开放应用所属企业的唯一标识

通讯录管理

第三方企业应用调用通讯录相关接口前，需要进行申请。申请流程如下：

1. 登录开发者后台，单击目标应用。
2. 单机权限管理。
   • 如果应用接入钉钉云，直接添加对应的接口权限：
     • 单击添加接口权限。
     • 选择要添加的接口权限，然后单击确认。
   • 如果应用未接入钉钉云，需要先申请接口权限，待审批通过后再添加。
     • 单击添加接口权限。
     • 单击开通新接口，然后选择要申请的接口，单击申请提交。
     • 输入申请理由，开发者在申请特殊权限时，需尽可能详细地描述权限接口及使用场景，然后单击提交。
     • 申请通过后，在添加接口权限页面，再添加要使用的接口。

通讯录权限范围

调用通讯录接口能获取哪些部门和员工的数据是受通讯录权限范围控制的。对于ISV开发者，取决于授权企业选择的授权范围（可见范围）。

可以调用“获取通讯录权限范围”接口来查询可获取到的通讯录范围。

在开发者获取到可以访问企业通讯录接口的token后，正式获取通讯录数据前，应该先调用本接口，获取当前token的权限范围，再依次遍历本接口返回的部门id列表，调用通讯录相应接口。

对于企业开通的第三方ISV应用，企业管理员可以在如下位置进行授权范围的调整：钉钉客户端->工作TAB->管理->选择应用->设置->授权使用范围。

**请求方式：**GET

**请求地址：**https://oapi.dingtalk.com/auth/scopes?access_token=ACCESS_TOKEN

返回结果：

{
    "errcode":0,
    "errmsg":"created",
    "auth_user_field":["name","email"],
    "condition_field":["contact_call"],
    "auth_org_scopes":{
        "authed_dept":[1,2,3],
        "authed_user":["user1","user"]
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
auth_user_field	可以得到的企业用户字段。name：员工名称，email：员工邮箱，具体参见user/get接口字段描述
condition_field	ISV可以直接使用企业的功能字段。contact_call：isv是否可以电话联系企业管理员
authed_dept	企业授权的部门id列表。返回值为授权部门id的并集。（设置“全部员工”时，返回授权的部门id为根部门ID，员工userid列表为空）
authed_user	企业授权的员工userid列表。返回值为授权人员id的并集（设置“仅为管理员可见”时，返回所有的管理员id。授权的部门id列表为空）

用户管理

获取用户详情

调用该接口，可以获取用户的详情信息，如员工名字、职位信息等，不支持获取手机号。

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/get?access_token=ACCESS_TOKEN&userid=zhangsan

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
userid	String	是	员工id
lang	String	否	通讯录语言（默认为zh_CN，未来会支持en_US）

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "name":"张三",
    "unionid":"PiiiPyQqBNBii0HnCJ3zljcxxxxxx",
    "userid":"zhangsan",
    "isLeaderInDepts":"{1:false}",
    "isBoss":false,
    "hiredDate":1520265600000,
    "isSenior":false,
    "department":[1,2],
    "orderInDepts":"{1:71738366882504}",
    "active":false,
    "avatar":"xxx",
    "isAdmin":false,
    "isHide":false,
    "jobnumber":"001",
    "position":"manager",
    "roles":[
        {
            "id":149507744,
            "name":"总监",
            "groupName":"职务"
        }
    ]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userid	员工在当前企业内的唯一标识，也称staffId
unionid	员工在当前开发者企业账号范围内的唯一标识，系统生成，固定值，不会改变
name	员工名字
active	是否已经激活，true表示已激活，false表示未激活
orderInDepts	在对应的部门中的排序，Map结构的json字符串，key是部门的id，value是人员在这个部门的排序值
isAdmin	是否为企业的管理员，true表示是，false表示不是
isBoss	是否为企业的老板，true表示是，false表示不是
isLeaderInDepts	在对应的部门中是否为主管：Map结构的json字符串，key是部门的id，value是人员在这个部门中是否为主管，true表示是，false表示不是
isHide	是否号码隐藏，true表示隐藏，false表示不隐藏
department	成员所属部门id列表
position	职位信息
avatar	头像url
hiredDate	入职时间。Unix时间戳（在OA后台通讯录中的员工基础信息中维护过入职时间才会返回）
jobnumber	员工工号
isSenior	是否是高管
roles	用户所在角色列表
id	角色id
name	角色名称
groupName	角色组名称
realAuthed	是否实名认证

获取部门用户userid列表

通过该接口，可以获取当前部门下的userid列表。**目前暂不支持一次性获取企业下所有员工userid值，**如果开发者希望获取企业下所有员工userid值，可以通过以下方法：

​ （1）步骤一，调用“获取部门列表”接口，参数id值传1，可以获取该企业下所有部门id

​ （2）步骤二，调用此接口“获取部门用户userid列表”，分别获取每个部门下的员工userid

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/getDeptMember?access_token=ACCESS_TOKEN&deptId=1

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
deptId	String	是	部门id

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "userIds":["1","2"]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
userIds	userid列表

获取部门用户

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/simplelist?access_token=ACCESS_TOKEN&department_id=1

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
lang	String	否	通讯录语言（默认zh_CN另外支持en_US）
department_id	long	是	获取的部门id
offset	long	是	支持分页查询，与size参数同时设置才生效，此参数代表偏移量
size	long	是	支持分页查询，与offset参数同时设置才生效，此参数代表分页大小，最大100
order	String	否	支持分页查询，部门成员的排序规则，默认不传是按自定义排序； entry_asc：代表按照进入部门的时间升序， entry_desc：代表按照进入部门的时间降序， modify_asc：代表按照部门信息修改时间升序， modify_desc：代表按照部门信息修改时间降序， custom：代表用户定义（未定义时按照拼音）排序

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "hasMore":false,
    "userlist":[
        {
            "userid":"zhangsan",
            "name":"张三"
        }
    ]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
hasMore	在分页查询时返回，代表是否还有下一页更多数据
userlist	员工列表
userid	员工id
name	员工名称

获取部门用户详情

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/listbypage?access_token=ACCESS_TOKEN&department_id=1

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
lang	String	否	通讯录语言（默认zh_CN另外支持en_US）
department_id	long	是	获取的部门id，1表示根部门
offset	long	是	支持分页查询，与size参数同时设置时才生效，此参数代表偏移量，偏移量从0开始
size	long	是	支持分页查询，与offset参数同时设置才生效，此参数代表分页大小，最大100
order	String	否	支持分页查询，部门成员的排序规则，默认 是按自定义排序； entry_asc：代表按照进入部门的时间升序， entry_desc：代表按照进入部门的时间降序， modify_asc：代表按照部门信息修改时间升序， modify_desc：代表按照部门信息修改时间降序， custom：代表用户定义（未定义时按照拼音）排序

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "hasMore":false,
    "userlist":[
        {
            "userid":"zhangsan",
            "unionid":"PiiiPyQqBNBii0HnCJ3zljcxxxxxx",
            "order":1,
            "isAdmin":true,
            "isBoss":false,
            "isHide":true,
            "isLeader":true,
            "name":"张三",
            "active":true,
            "department":[1,2],
            "position":"工程师",
            "avatar":"xxx",
            "jobnumber":"xxx"
        }
    ]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
hasMore	在分页查询时返回，代表是否还有下一页更多数据
userlist	成员列表
userid	员工在当前企业内的唯一标识，也称staffId
unionid	员工在当前开发者企业账号范围内的唯一标识，系统生成，固定值，不会改变
order	表示人员在此部门中的排序，列表是按order的倒序排列输出的，即从大到小排列输出的（钉钉管理后台里面调整了顺序的话order才有值）
isAdmin	是否是企业的管理员，true表示是，false表示不是
isBoss	是否为企业的老板，true表示是，false表示不是
isHide	是否隐藏号码，true表示是，false表示不是
isLeader	是否是部门的主管，true表示是，false表示不是
name	成员名称
active	表示该用户是否激活了钉钉
department	成员所属部门id列表
position	职位信息
avatar	头像url
jobnumber	员工工号
hiredDate	入职时间

获取管理员列表

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/get_admin?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "admin_list":[
        {"sys_level":2,"userid":"userid2"},
        {"sys_level":1,"userid":"userid1"}
    ]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
sys_level	管理员角色，1表示主管理员，2表示子管理员
userid	员工id

获取管理员通讯录权限范围

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/user/get_admin_scope?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
userid	String	是	员工id

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "dept_ids":[1,2]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
dept_ids	可管理的部门id列表

查询管理员是否具备管理某个应用的权限

应用必须是应用服务商所开发，且管理员所在组织开通了此应用。

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/can_access_microapp?access_token=ACCESS_TOKEN&appId=APPID&userId=USERID

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
appId	String	是	微应用id
userId	String	是	员工id

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "canAccess":true
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
canAccess	表示是否能管理该微应用

根据unionid获取userid

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/getUseridByUnionid?access_token=ACCESS_TOKEN&unionid=xxx

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
unionid	String	是	员工在当前开发者企业账号范围内的唯一标识，系统生成，固定值，不会改变

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "contactType":0,
    "userid":"userid1"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
contactType	联系类型，0表示企业内部员工，1表示企业外部联系人
userid	员工id

获取企业员工人数

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/user/get_org_user_count?access_token=ACCESS_TOKEN&onlyActive=0

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
onlyActive	Number	是	0表示包含未激活钉钉的人员数量 1表示不包含未激活钉钉的人员数量

返回结果：

{
    "count":6,
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
count	企业员工数量

部门管理

获取子部门ID列表

注意：该接口能获取到企业部门下的所有直属子部门列表，不受授权范围限制，ISV可以根据该接口完成企业部门的遍历

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/department/list_ids?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
id	String	是	父部门id。根部门的话传1

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "sub_dept_id_list":[2,3,4,5]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
sub_dept_id_list	子部门ID列表数据

获取部门列表

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/department/list?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
lang	String	否	通讯录语言（默认为zh_CN，未来会支持en_US）
fetch_child	Boolean	否	是否递归部门的全部子部门，ISV微应用固定传递false
id	String	否	父部门id（如果不传，默认部门为根部门，根部门ID为1）

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "department":[
        {
            "id":2,
            "name":"xxx",
            "parentid":1,
            "createDeptGroup":true,
            "autoAddUser":true
        },
        {
            "id":3,
            "name":"服务端开发组",
            "parentid":2,
            "createDeptGroup":false,
            "autoAddUser":false
        }
    ]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
department	部门列表数据，以部门的order字段从小到大排列
id	部门id
name	部门名称
parentid	父部门id，根部门为1
createDeptGroup	是否同步创建一个关联此部门的企业群，true表示是，false表示不是
autoAddUser	当群已经创建后，是否有新人加入部门会自动加入该群，true表示是，false表示不是

获取部门详情

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/department/get?access_token=ACCESS_TOKEN&id=123

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
id	String	是	部门id
lang	String	否	通讯录语言（默认zh_CN，未来会支持en_US）

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "id":2,
    "name":"xxx",
    "order":10,
    "parentid":1,
    "createDeptGroup":true,
    "autoAddUser":true,
    "deptHiding":true,
    "deptPermits":"3|4",
    "userPermits":"userid1|userid2",
    "outerDept":true,
    "outerPermitDepts:"1|2",
    "outerPermitUsers":"userid3|userid4",
    "orgDeptOwner":"manager1122",
    "deptManagerUseridList":"manager1122|manager3211",
    "sourceIdentifier":"source"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
id	部门id
name	部门名称
parentid	父部门id，根部门为1
order	当前部门在父部门下的所有子部门中的排序值
createDeptGroup	是否同步创建一个关联此部门的企业群，true表示是，false表示不是
autoAddUser	当部门群已经创建后，是否有新人加入部门会自动加入该群，true表示是，false表示不是
deptHiding	是否隐藏部门，true表示隐藏，false表示显示
deptPermits	可以查看指定隐藏部门的其他部门列表，如果部门隐藏，则此值生效，取值为其他的部门id组成的字符串，使用“|”符号进行分割
userPermits	可以查看指定隐藏部门的其他人员列表，如果部门隐藏，则此值生效，取值为其他的人员userid组成的字符串，使用“|"符号进行分割
outerDept	是否本部门的员工仅可见员工自己，为true时，本部门员工默认只能看到员工自己
outerPermitDepts	本部门的员工仅可见员工自己为true时，可以配置额外可见部门，值为部门id组成的字符串，使用"|"符号进行分割
outerPermitUsers	本部门的员工仅可见员工自己为true时，可以配置额外可见人员，值为userid组成的的字符串，使用“\
orgDeptOwner	企业群群主
deptManagerUseridList	部门的主管列表，取值为由主管的userid组成的字符串，不同的userid使用"|"符号进行分割
sourceIdentifier	部门标识字段，开发者可用该字段来唯一标识一个部门，并与钉钉外部通讯录里的部门做映射
groupContainSubDept	部门群是否包含子部门

查询部门的所有上级父部门路径

注意：此接口不受授权范围的限制。

假设部门的组织结构如下：

1

​ |-> 123

​ |-> 456

​ |-> 789

当传入部门id为789时，返回的结果按顺序依次为当前部门id及其所有父部门的ID，直到根部门，如[789,456,123,1]。

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/department/list_parent_depts_by_dept?access_token=ACCESS_TOKEN&id=ID

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
id	String	是	希望查询的部门的id，包含查询的部门本身

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "parentIds":[789,456,123,1]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
parentIds	该部门的所有父部门id列表

查询指定用户的所有上级父部门路径

注意：此接口不受授权范围的限制。

假设用户所属部门的组织结构如下：

1

​ |-> 123

​ |->456 ->员工A

​ |-> 789 -> 员工A

当传入员工A的userId时，返回的结果按顺序依次为其所有父部门的ID，直到根部门，如[456,123,1],[789,1]。

调试工具：在线调试

**请求方式：**GET(HTTPS)

**请求地址：**https://oapi.dingtalk.com/department/list_parent_depts?access_token=ACCESS_TOKEN&userId=USERID

参数说明：

参数	类型	必须	说明
access_token	String	是	调用接口凭证
userId	String	是	希望查询的用户的id

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "department":[[456,123,1],[789,1]]
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
department	该部门的所有父部门id列表

角色管理

获取角色列表

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/role/list?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
size	Number	否	20	分页大小，默认值：20，最大值200
offset	Number	否	0	分页偏移，默认值：0

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "result":{
        "hasMore":false,
        "list":[
            {
                "name":"默认",
                "groupId":1,
                "roles":[
                    {
                        "name":"管理员",
                        "id":1
                    }
                ]
            }
        ]
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
result
hasMore	是否还有更多数据
list
name	角色组名称
groupId	角色组id
roles
name	角色名称
id	角色id

获取角色下的员工列表

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/role/simplelist?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
role_id	Number	是	1203141	角色ID
size	Number	否	20	分页大小，默认值：20，最大值200
offset	Number	否	0	分页偏移，默认值：0

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "result":{
        "hasMore":false,
        "list":[
            {
                "userid":"manager7978",
                "name":"小钉",
                "manageScopes":[
                    {
                        "dept_id":11,
                        "name":"test"
                    }
                ]
            }
        ]
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
result
hasMore	是否还有更多数据
list
userid	员工id
name	员工姓名
manageScopes	管理范围
dept_id	部门id
name	部门名称

获取角色组

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/role/gettolegroup?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
group_id	Number	是	1	角色组的id

返回结果：

{
    "role_group":{
        "roles":[
            {
                "role_id":1,
                "role_name":"出纳"
            }
        ],
        "group_name":"财务"
    },
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
role_group	角色组信息
roles	角色列表信息
role_id	角色id
role_name	角色名
group_name	角色组名

获取角色详情

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/role/getrole?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
roleId	Number	是	1	角色id

返回结果：

{
    "role":{
        "name":"财务",
        "groupId":1002
    },
    "errcode":0,
    "errmsg":"成功"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
role	角色信息
groupId	角色组id
name	角色名

外部联系人管理

获取外部联系人标签列表

调用此接口可获取企业外部联系人标签列表，例如这个外部联系人是公司的客户，那么标签可能就是客户。

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/extcontact/listlabelgroups?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
size	Number	是	20	分页大小，最大100
offset	Number	是	0	偏移位置

返回结果：

{
    "results":[
        {
            "name":"类型",
            "color":-15220075,
            "labels":[
                {
                    "name":"客户",
                    "id":1026002
                }
            ]
        }
    ],
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
results	标签组列表
name	标签组名字
color	标签组颜色
labels	标签列表
name	标签名字
id	标签id

获取外部联系人列表

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/extcontact/list?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
size	Number	是	20	分页大小，最大100
offset	Number	是	0	偏移位置

返回结果：

{
    "results":[
        {
            "title":"开发工程师",
            "share_dept_ids":[],
            "label_ids":[1,2,3],
            "remark":"备注内容",
            "address":"地址内容",
            "name":"张三",
            "follower_user_id":"userid2",
            "state_code":"86",
            "company_name":"钉钉",
            "share_user_ids":["userid2"],
            "userid":"userid1"
        }
    ],
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
results	外部联系人列表
title	职位
share_dept_ids	共享部门ID列表
label_ids	标签
remark	备注
address	地址
name	姓名
follower_user_id	负责人UserID
state_code	国家码
company_name	公司名
share_user_ids	共享员工UserID列表
userid	外部联系人UserID

获取外部联系人详情

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/extcontact/get?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
user_id	String	是	manager1	用户id

返回结果：

{
    "result":{
        "title":"开发工程师",
        "share_dept_ids":[],
        "label_ids":[1,2,3],
        "remark":"备注内容",
        "address":"地址内容",
        "name":"张三",
        "follower_user_id":"userid2",
        "state_code":"86",
        "company_name":"钉钉",
        "share_user_ids":["userid3"],
        "userid":"userid1"
    },
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
results	外部联系人列表
title	职位
share_dept_ids	共享部门ID列表
label_ids	标签
remark	备注
address	地址
name	姓名
follower_user_id	负责人UserID
state_code	国家码
company_name	公司名
share_user_ids	共享员工UserID列表
userid	外部联系人UserID

消息通知

钉钉消息通知：

1. **工作通知消息：**是以企业工作通知会话中某个微应用的名义推送到员工的通知消息，例如生日祝福、入职提醒等。
2. **普通消息：**是指员工个人在使用应用时，可以通过界面操作的方式往群或其他人的会话里推送消息，例如发送日志的场景。
3. 任务类通知：是指需要发送一条任务提醒给员工，比如审批任务等。

工作通知消息

工作通知消息是以企业工作通知会话中某个微应用的名义推送到员工的通知消息，例如生日祝福、入职提醒等。

注意事项

发送工作通知消息需要注意以下事项：

• 同一个应用相同消息的内容同一个用户一天只能接收一次。
• 同一个应用给同一个用户发送消息，ISV应用开发方式一天不得超过50次。
• 超出以上限制次数后，接口返回成功，但用户无法接收到。
• 该接口是异步发送消息，接口返回成功并不表示用户一定会收到消息，需要通过本文介绍的“查询工作通知消息的发送结果”接口查询是否给用户发送成功。

调试工具：在线调试

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
agent_id	Number	是	1234	企业内部应用是应用agentId，第三方企业应用是获取授权信息接口中返回的agentId
userid_list	String	否(userid_list，dept_id_list，to_all_user必须有一个不为空)	zhangsan,lisi	接收者的用户userid列表，最大用户列表长度：100
dept_id_list	String	否	123,456	接收者的部门id列表，最大列表长度：20，接收者是部门id下（包括子部门下）的所有用户
to_all_user	Boolean	否	false	是否发送给企业全部用户（ISV不能设置true）
msg	json对象	是	{“msgtype”:“text”,“text”:{“content”:“消息内容”}}	消息内容，最长不超过2048个字节

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "task_id":123
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
task_id	创建的发送任务id

查询工作通知消息的发送进度

调试工具：在线调试

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/message/corpconversation/getsendprogress?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
agent_id	Number	是	123	应用的agentid
task_id	Number	是	456	钉钉返回的任务id。仅支持查询24小时内的任务id

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "progress":{
        "progress_in_percent":100,
        "status":2
    }
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
progress
progress_in_percent	取值0-100，表示处理的百分比
status	任务执行状态，0=未开始，1=处理中，2=处理完毕

查询工作通知消息的发送结果

调试工具：在线调试

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/message/corpconversation/getsendresult?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
agent_id	Number	是	123	应用的agentid
task_id	Number	是	456	钉钉返回的任务id。仅支持查询24小时内的任务id

返回结果：

{
    "send_result":{
        "invalid_user_id_list":"zhangsan,lisi",
        "forbidden_user_id_list":"zhangsan,lisi",
        "failed_user_id_list":"zhangsan,lisi",
        "read_user_id_list":"zhangsan,lisi",
        "unread_user_id_list":"zhangsan,lisi",
        "invalid_dept_id_list":"1,2,3"
    },
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
send_result
invalid_user_id_list	无效的用户id
forbidden_user_id_list	因发送消息超过上限而被流控过滤后实际未发送的userid。未被限流的接收者仍会收到消息。限流规则包括： 1. 同一个微应用相同消息的内容同一个用户一天只能接收一次 2. 同一个微应用给同一个用户发送消息： 如果是第三方企业应用开发，一天最多为50次； 如果是企业内部开发方式，一天最多为500次
forbidden_list	推送被禁止的具体原因列表
code	流控code。包括以下code： 143205表示第三方企业应用每日推送给用户的消息超过上限 143206表示第三方企业应用推送给用户的消息重复
count	流控阈值
userid	被流控员工userid
failed_user_id_list	发送失败的用户id
read_user_id_list	已读消息的用户id
unread_user_id_list	未读消息的用户id
invalid_dept_id_list	无效的部门id

工作通知消息撤回

调试工具：在线调试

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/topapi/message/corpconversation/recall?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	示例值	说明
agent_id	Number	是	123	应用的agentid
msg_task_id	Number	是	456	钉钉返回的任务id。仅支持查询24小时内的任务id

返回结果：

{
    "errcode":0,
    "errmsg":"ok"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容

发送普通消息

普通会话消息是指员工个人在使用应用时，可以通过界面操作的方式往群或者其他人的会话里推送消息，例如发送日志的场景。发送普通消息，需要在前端页面调用JSAPI唤起联系人会话选择页面，选中后会返回会话cid，然后再调用服务端接口向会话里发送一条消息。

注意事项

发送普通消息需要注意以下事项：

1. 不在当前接口调用所使用的企业的接收者（单聊接收者或者群聊会话里的接收者）不能收到消息。
2. 获取到的会话cid只能使用一次，且有效期为24小时。
3. 接收说明
   1. 接收者可以是单聊接收者或者群聊会话里的接收者，如果接收者是当前接口调用所使用的企业的员工，则是有效接收者
   2. 接口返回所有有效接收者的userId
   3. 非有效接收者是收不到消息的

接口调用

调试工具：在线调试

**请求方式：**POST(HTTPS)

**请求地址：**https://oapi.dingtalk.com/message/send_to_conversation?access_token=ACCESS_TOKEN

参数说明：

参数	类型	必须	说明
sender	String	是	消息发送者userId
cid	String	是	群会话或者个人会话的id，通过JSAPI接口唤起联系人界面选择会话获取会话id
msg	json	是	消息内容。最长不超过2048个字节

返回结果：

{
    "errcode":0,
    "errmsg":"ok",
    "receiver":"UserId1|UserID2"
}

参数	说明
errcode	返回码
errmsg	对返回码的文本描述内容
receiver	有效接收消息的员工的userid

消息类型与数据格式

文本消息

{
    "msgtype":"text",
    "text":{
        "content":"张三的请假申请"
    }
}

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：text
content	String	是	消息内容，建议500字符以内

图片消息

{
    "msgtype":"image",
    "image":{
        "media_id":"MEDIA_ID"
    }
}

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：image
media_id	String	是	媒体文件id。可以通过媒体文件接口上传图片获取，建议宽600像素×400像素，宽高比3:2

语音消息

{
    "msgtype":"voice",
    "voice":{
        "media_id":"MEDIA_ID",
        "duration":"10"
    }
}

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：voice
media_id	String	是	媒体文件id，2MB，播放长度不超过60s，AMR格式。
duration	String	是	正整数，小于60，表示音频时长

文件消息

注意，文件消息类型只支持文件下载，不支持在线预览。

{
    "msgtype":"file",
    "file":{
        "media_id":"MEDIA_ID"
    }
}

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：file
media_id	String	是	媒体文件id，引用的媒体文件最大10MB。

链接消息

{
    "msgtype":"link",
    "link":{
        "messageUrl":"http://s.dingtalk.com/market/dingtalk/error_code.php",
        "picUrl":"@lALOACZwe2Rk",
        "title":"测试",
        "text":"测试"
    }
}

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：link

消息体参数说明

参数	参数类型	必须	说明
link.messageUrl	String	是	消息点击链接地址，当发送消息为小程序时支持小程序跳转链接
link.picUrl	String	是	图片地址，可以通过媒体文件接口上传图片获取
link.title	String	是	消息标题，建议100字符以内
link.text	String	是	消息描述，建议500字符以内

OA消息

{
    "msgtype":"oa",
    "oa":{
        "message_url":"http://dingtalk.com",
        "head":{
            "bgcolor":"FFBBBBBB",
            "text":"头部标题"
        },
        "body":{
            "title":"正文标题",
            "form":[
                {
                    "key":"姓名：",
                    "value":"张三"
                },
                {
                    "key":"年龄：",
                    "value":"20"
                },
                {
                    "key":"身高",
                    "value":"1.8米"
                },
                {
                    "key":"体重：",
                    "value":"130斤"
                },
                {
                    "key":"学历：",
                    "value":"本科"
                },
                {
                    "key":"爱好：",
                    "value":"打球、听音乐"
                }
            ],
            "rich":{
                "num":"15.6",
                "unit":"元"
            },
            "content":"大段文本大段文本大段文本大段文本大段文本大段文本",
            "image":"@1ADOADmaWMzazQKA",
            "file_count":"3",
            "author":"李四"
        }
    }
}

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：oa

消息体参数说明

参数	参数类型	必须	说明
oa.message_url	String	是	消息点击链接地址，当发送消息为小程序时支持小程序跳转链接
oa.pc_message_url	String	否	PC端点击消息时跳转到的地址
oa.head	String	是	消息头部内容
oa.head.bgcolor	String	是	消息头部的背景颜色。长度限制为8个英文字符，其中前2位表示透明度，后6位表示颜色值。不要添加0x
oa.head.text	String	是	消息的头部标题（向普通会话发送时有效，向企业会话发送时会被替换为微应用的名字），长度限制为最多10个字符
oa.body	JSON Object	是	消息体
oa.body.title	String	否	消息体的标题，建议50个字符以内
oa.body.form	Array[JSON Object]	否	消息体的表单，最多显示6个，超过会被隐藏
oa.body.form.key	String	否	消息体的关键字
oa.body.form.value	String	否	消息体的关键字对应的值
oa.body.rich	JSON Object	否	单行富文本信息
oa.body.rich.num	String	否	单行富文本信息的数目
oa.body.rich.unit	String	否	单行富文本信息的单位
oa.body.content	String	否	消息体的内容，最多显示3行
oa.body.image	String	否	消息体中的图片，支持图片资源@mediaId
oa.body.file_count	String	否	自定义的附件数目。此数字仅供显示，钉钉不做验证
oa.body.author	String	否	自定义的作者名字

markdown消息

{
    "msgtype":"markdown",
    "markdown":{
        "title":"首屏会话透出的展示内容",
        "text":"这是支持markdown的文本"
    }
}

说明：目前仅支持一下md语法：

标题
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

引用
> A man who stands for nothing will fall for anything.

文字加粗、斜体
**加粗**
*斜体*

链接
[链接](http://xxxx.com)

图片
![](http://xxxx/xx.jpg)

无序列表
- item1
- item2

有序列表
1. item1
2. item2

换行
  \n  (建议\n前后都加2个空格)

参数说明

参数	参数类型	必须	说明
msgtype	String	是	消息类型，此时固定为：markdown
title	String	是	收评会话透出的展示内容
text	String	是	markdown格式的消息，建议500字符以内

卡片消息

卡片消息支持整体跳转ActionCard样式和独立跳转ActionCard样式：

(1) 整体跳转ActionCard样式，支持一个点击Action，需要传入参数single_title和single_url；

(2) 独立跳转ActionCard样式，支持多个点击Action，需要传入参数btn_orientation和btn_json_list；

整体跳转ActionCard样式参数示例

{
    "msgtype": "action_card",
    "action_card": {
        "title": "是透出到会话列表和通知的文案",
        "markdown": "支持markdown格式的正文内容",
        "single_title": "查看详情",
        "single_url": "https://open.dingtalk.com"
    }
}

独立跳转ActionCard样式参数示例

{
    "msgtype": "action_card",
    "action_card": {
        "title": "是透出到会话列表和通知的文案",
        "markdown": "支持markdown格式的正文内容",
        "btn_orientation": "1",
        "btn_json_list": [
            {
                "title": "一个按钮",
                "action_url": "https://www.taobao.com"
            },
            {
                "title": "两个按钮",
                "action_url": "https://www.tmall.com"
            }
        ]
    }
}

消息体参数说明

参数	参数类型	必须	说明
action_card.title	String	是	透出到会话列表和通知的文案，最长64个字符
action_card.markdown	String	是	消息内容，支持markdown，语法参考标准markdown语法。建议1000个字符以内
action_card.single_title	String	否	使用整体跳转ActionCard样式时的标题，必须与single_url同时设置，最长20个字符
action_card.single_url	String	否	消息点击链接地址，当发送消息为小程序时支持小程序跳转链接，最长500个字符
action_card.btn_orientation	String	否	使用独立跳转ActionCard样式时的按钮排列方式，竖直排列(0)，横向排列(1)；必须与btn_json_list同时设置
action_card.btn_json_list	JSONArray	否	使用独立跳转ActionCard样式时的按钮列表；必须与btn_orientation同时设置
action_card.btn_json_list.title	String	否	使用独立跳转ActionCard样式时的按钮的标题，最长20个字符
action_card.btn_json_list.action_url	String	否	消息点击链接地址，当发送消息为小程序时支持小程序跳转链接，最长500个字符

消息链接说明

消息链接在PC端侧边栏打开

在PC客户端点击消息中的URL链接时，希望在PC客户端打开而不是外跳到浏览器，可以使用以下方式：

dingtalk://dingtalkclient/page/link?url=http%3A%2F%2Fwww.dingtalk.com&pc_slide=true

参数说明

参数	说明
url	表示要打开的链接，必须urlEncode
pc_slide	true表示在PC客户端侧边栏打开，false表示在浏览器打开

消息链接在PC端工作台打开（只支持打开第三方应用）

当消息中的URL链接是某个微应用链接，希望在PC端工作台打开，可以使用下面方式：

dingtalk://dingtalkclient/action/openapp?corpid=免登企业corpId&container_type=work_platform&app_id=应用id&redirect_type=jump&redirect_url=跳转url

参数说明

参数	说明
corpid	表示免登微应用用户的所属企业
container_type	表示使用哪种方式打开链接，work_platform表示用工作台打开
app_id	第三方企业应用的appId
redirect_type	只能填写jump
redirect_url	表示要跳转的地址，必须urlEncode