[TOC]
## 简介
钉钉提供了自定义的webhook机器人和企业机器人，钉钉消息转接器就是通过这两个功能实现的。
> 请确保你已经了解钉钉机器人相关事项！群机器人文档 [https://ding-doc.dingtalk.com/doc#/serverapi2/krgddi](https://ding-doc.dingtalk.com/doc#/serverapi2/krgddi)
> 确保你的web服务可以被外网访问！
## 配置钉钉机器人
钉钉消息转接器有两种模式：
1. 通过钉钉将消息发送给消息转接器，经过脚本处理后返回的消息通过webhook发送给用户，此为默认模式。
2. 通过钉钉将消息发送给消息转接器，经过脚本处理后返回的消息通过API响应返回，需要开发者手动注释代码。
### 模式1
在这个模式开发者需要配置两种机器人，`webhook机器人`和`企业机器人`
**配置企业机器人**
创建机器人后获取 `AppSecret` 。
在群聊中添加智能群助手，获得webhook机器人的`access_token`，安全设置请选择 `加签` ，获取到秘钥。
相关配置如下：
```env
# 聊天转接器
ROBOT_ADAPTER=dingtalk
...
# 钉钉机器人秘钥
DING_ROBOT_SECRET=AppSecret
# 钉钉webhook机器人access_token
DING_ROBOT_HOOK_ACCESS_TOKEN=access_token
# 钉钉webhook机器人秘钥
DING_ROBOT_HOOK_SECRET=加签秘钥
```
### 模式2
第二种模式下开发者只需要配置企业机器人的 `AppSecret` 即可。
## 传入消息（Incoming）
监听钉钉用户消息需要为企业机器人设置`消息接收地址`，转接器提供了相应的API，URI为 `ding`
比如你的部署地址为 `https://baidu.com:7856`，对应消息接收地址为 `https://baidu.com:7856/ding`
当钉钉将消息或事件推送给转接器时，转接器做了以下操作：
- 验证传入的 `timestamp`和`sign`以确保消息合法性
- 记录`发送这ID`(msg.Sender)和`发送者昵称`(msg.Header["sender"])
> 因为钉钉只支持 `text` 类型发送消息，所以记录原始数据没有意义
## 传出消息（Outgoing）
消息通过脚本解析执行后会将处理结果发送给用户，脚本可以发送转接器支持的消息类型到客户端。
钉钉支持五种消息类型：
- `text` 文本消息
- `markdown` markdown消息
- `link` link类型
- `actionCard` ActionCard类型
- `feedCard` FeedCard类型
> 消息类型请查看钉钉开发文档 [消息类型及数据格式](https://ding-doc.dingtalk.com/doc#/serverapi2/qf2nxq/e9d991e2)
> 需要在 `Header`中设置消息类型 `msgtype`
> 在不指定时默认为 `markdown` 类型消息
