详解调用钉钉AI助理消息API发送钉钉消息卡片给指定单聊用户

前言

  本文针对现在钉钉提供的AI助理能力，带你学会如何调用钉钉的AI助理主动发送消息API去发送一个自己配置的钉钉消息卡片给指定钉钉用户，可以设想一下，实现了后台对接钉钉AI助理的能力，那对于你公司的行政来说，就可以实现更多更灵活的工作场景，比如定时给某些员工发送指定的钉钉消息卡片。AI助理API调用场景的文章CSDN目前鲜有介绍，看完本文读者会明白钉钉的AI助理怎么对接。

准备工作

1、在钉钉开发者后台创建一个钉钉企业内部应用；

2、创建并保存好应用的appKey和appSecret，后面用于获取调用API的请求token；

3、了解AI助理主动发送消息API：

文档地址：AI 助理预备发消息（主动发送模式）

4、应用中配置好所需权限：

4.1、权限点

  智能交互卡片写权限；

4.2、配置方式

  在应用管理的权限中搜索添加：

5、配置消息卡片

  钉钉的消息卡片模板可以配置更丰富的组件和更个性化的布局，所以实际场景中，一般发送使用消息卡片承载消息内容，先带大家把消息卡片配好。

5.1、新建卡片

  我们登录开发者后台后从“开放能力”导航栏进入“卡片平台”，并且点击新建模板：

  填写模板创建信息：包括模板名称、卡片类型（这里以普通的消息卡片举例）、模板场景（以普通卡片举例）、关联应用（你创建的企业内部应用，创建后就能选到）：

  信息填好后点创建我们就进入了模板编辑页面，我们可以从左边选择与拖拽自己想要的组件到卡片模板里，比如按钮、文本栏、甚至表格等复杂组件，像按钮这些组件还支持配置点击事件与跳转链接：

  我带大家配置一个包含卡片头、文本栏、点击按钮的简单卡片，首先从左边拖一个卡片头过来，并设置卡片头展示的内容：

  再拖一个文本栏过来放消息介绍描述：

  最后放置个按钮在最下面，并且属性中填写按钮文案，事件中配置点击后跳转的流程链接（比如审批流程）：

  配置完成点右上角保存即可使用（注意，调试期间不要点发布，点发布后模板不可编辑），然后在模板列表查看自己新建的模板可以得到模板ID信息，后面调接口会用到：

6、应用中新建AI助理

  消息是通过API控制AI助理发送的，需要在应用中创建一个AI助理，并绑定到魔法棒应用，最后发布就可以调用接口测试了：

接口调用流程

Maven依赖

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>dingtalk</artifactId>
    <version>2.0.14</version>
</dependency>

封装一个工具类

工具类包含流程所需配置的读取以及token生成方法：

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import com.aliyun.dingtalkstorage_1_0.Client;
import com.aliyun.dingtalkstorage_1_0.models.*;
import com.aliyun.teaopenapi.models.Config;
import com.remo.pms.entity.ding.FileInfoEntity;
import lombok.Data;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLConnection;
import java.util.HashMap;
import java.util.Map;

@Component
@Data
@Slf4j
public class DingDingUtils {
    @Value("${ding-ding.clientId}")
    private String appKey;

    @Value("${ding-ding.clientSecret}")
    private String appSecret;

    @Value("${ding-ding.space-id}")
    private String spaceId;

    @Value("${ding-ding.union-id}")
    private String unionId;

    public Map<String, Object> getDingDingAccessToken() {
        Map<String, Object> result = new HashMap<>();
        String url = "https://oapi.dingtalk.com/gettoken?appkey=" + appKey + "&appsecret=" + appSecret;
        String resultStr = HttpUtils.get(url, null);
        JSONObject jsonObject = JSON.parseObject(resultStr);
        result.put("access_token", jsonObject.getString("access_token"));
        result.put("expires_in", jsonObject.getLongValue("expires_in"));
        return result;
    }
}

查询用户信息

  调用AI助理发送消息接口前我们需要先获得发送用户的unionid（我以单聊场景举例）。

查看响应参数

  我们先看postman调用结果，返回值有我们需要的unionid（每个钉钉用户有个对应的）：

调用代码示例：

String accessToken = dingDingUtils.getDingDingAccessToken().get("access_token").toString();
String url = "https://oapi.dingtalk.com/topapi/v2/user/get?language=zh_CN";
url = url + "&access_token=" + accessToken ;
url = url + "&userid=" + "用户ID";

String resultStr = HttpUtils.get(url, null);
JSONObject jsonObject = JSON.parseObject(resultStr);
String unionId = jsonObject.getJSONObject("result").getString("unionid");
log.info("unionid：{}", unionId);

调用AI助理发送消息API

postman调用：

  我们先看postman调用结果，参数就只有三个，unionid、content（模板ID）、contentType（给ai_card即可），注意header中还需要传入accessToken，返回值有conversationToken就成功了：

效果：

  调用完立马能看到钉钉收到消息卡片通知：