钉钉企业工作通知

工作通知由企业内部应用发出，可按员工或部门触达。本文依据钉钉开放平台资料整理，核验日期为 2026-09-08；未执行真实组织发送验证。

准备条件

• 已创建企业内部应用并获得应用管理权限。
• 应用可见范围覆盖测试员工或部门。
• 已记录 AppKey、AppSecret 和 AgentId。

配置步骤

1. 在钉钉开发者后台创建企业内部应用。
2. 配置应用权限和可见范围，发布应用版本。
3. 使用 AppKey 与 AppSecret 获取 access_token。
4. 调用企业会话消息异步发送接口，传入 AgentId、接收员工或部门与消息体。
5. 保存返回的任务标识，用于后续排查或查询结果。

凭据说明

字段	必需	说明
APP_KEY	是	企业内部应用标识
APP_SECRET	是	获取访问令牌的敏感凭据
AGENT_ID	是	应用的 AgentId
USER_ID_LIST	二选一	接收员工 ID 列表
DEPT_ID_LIST	二选一	接收部门 ID 列表

最小请求

JavaScript 示例需要 Node.js 20 或更新版本；Python 示例需要安装 requests。

curl

curl 'https://oapi.dingtalk.com/gettoken?appkey=APP_KEY&appsecret=APP_SECRET'

curl -X POST 'https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":AGENT_ID,"userid_list":"USER_ID","msg":{"msgtype":"text","text":{"content":"通知渠道连通性测试"}}}'

JavaScript

const tokenUrl = new URL('https://oapi.dingtalk.com/gettoken');
tokenUrl.searchParams.set('appkey', process.env.APP_KEY);
tokenUrl.searchParams.set('appsecret', process.env.APP_SECRET);
const tokenResult = await fetch(tokenUrl).then((response) => response.json());
if (tokenResult.errcode !== 0) throw new Error(JSON.stringify(tokenResult));

const response = await fetch(
  `https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=${encodeURIComponent(tokenResult.access_token)}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent_id: Number(process.env.AGENT_ID),
      userid_list: process.env.USER_ID,
      msg: { msgtype: 'text', text: { content: '通知渠道连通性测试' } },
    }),
  },
);
console.log(await response.json());

Python

import os
import requests

token_response = requests.get(
    "https://oapi.dingtalk.com/gettoken",
    params={"appkey": os.environ["APP_KEY"], "appsecret": os.environ["APP_SECRET"]},
    timeout=15,
)
token_response.raise_for_status()
token_result = token_response.json()
if token_result.get("errcode") != 0:
    raise RuntimeError(token_result)

response = requests.post(
    "https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2",
    params={"access_token": token_result["access_token"]},
    json={
        "agent_id": int(os.environ["AGENT_ID"]),
        "userid_list": os.environ["USER_ID"],
        "msg": {"msgtype": "text", "text": {"content": "通知渠道连通性测试"}},
    },
    timeout=15,
)
response.raise_for_status()
print(response.json())

验证结果

接口受理成功后确认返回任务标识，并由目标员工确认收到工作通知。异步受理不代表每个接收人都已成功送达。

安全建议

• AppSecret 和访问令牌只在服务端使用。
• 应用可见范围和消息权限保持最小化。
• 大批量发送前先用单一测试员工验证，避免误触达。

常见问题

员工不在可见范围：调整应用可见范围并确认发布生效。

AgentId 不匹配：AgentId 必须属于用于换取 Token 的同一应用。

异步接口成功但未收到：根据任务标识查询发送结果和失败原因。

官方资料

• 钉钉开放平台：发送企业会话消息