发送群助手消息

**
接口调用量说明**钉钉标准版接口累计可调用次数为1万次/月，当前接口会消耗调用次数。若该调用量无法满足需求，你可升级钉钉专业版(Open API调用量50万次/月)或钉钉专属版(Open API调用量500万次/月)扩容调用次数。

调用本接口通过群模板定义的机器人向群内发送消息。

调用本接口，实现通过群模板定义的机器人向群内发送消息，具体示例如下图所示。

说明

支持以下场景使用：

基于群模板创建的群。

企业内部应用，详情参见创建群。

第三方企业应用，详情参见创建群。

重要

本接口只支持发送文本、图片、Markdown、ActionCard消息到群内。如果要发送互动卡片消息，请使用发送钉钉互动卡片接口。

企业内部应用，调用发送钉钉互动卡片接口。

第三方企业应用，调用发送钉钉互动卡片接口。

权限

服务端API是以应用维度授权的，在调用接口前，确保已经为应用添加了接口权限。

应用类型	是否支持调用	权限申请方式	API Explorer调试
企业内部应用	支持	chat相关接口的管理权限	API Explorer
第三方企业应用	支持	chat相关接口的管理权限	API Explorer
第三方个人应用	暂不支持	chat相关接口的管理权限	暂不支持

场景群通用消息模板

场景群发消息接口目前已支持官方通用测试模板，方便开发者接入体验。

企业内部应用

如果你的应用是企业内部应用，可以直接使用企业内部应用公共模板，可用的模板如下：

文本消息模板：msg_template_id取值为inner_app_template_text。

传参示例如下：

{
    "robot_code": "iuEkXlixxx1002",
    "target_open_conversation_id": "3mwsbxxxfe==",
    "msg_param_map": {
        "content": "测试消息~"
    },
    "msg_template_id": "inner_app_template_text"
}

图片消息模板：msg_template_id取值为inner_app_template_photo。

传参示例如下：

{
    "robot_code": "iuEkXlixxx1002",
    "target_open_conversation_id": "3mwsbxxxfe==",
    "msg_media_id_param_map": {
        "img_media_id": "@lAjPDxxx"
    },
    "msg_template_id": "inner_app_template_photo"
}

markdown模板：msg_template_id取值为inner_app_template_markdown。

传参示例如下：

{
    "robot_code": "iuEkXlixxx1002",
    "target_open_conversation_id": "3mwsbxxxfe==",
    "msg_param_map": {
        "title": "标题",
        "markdown_content": "# 测试内容"
    },
    "msg_template_id": "inner_app_template_markdown"
}

actionCard模板：msg_template_id取值为inner_app_template_action_card。

传参示例如下：

{
    "robot_code": "iuEkXlixxx1002",
    "target_open_conversation_id": "3mwsbxxxfe==",
    "msg_param_map": {
        "title": "标题",
        "markdown": "# 测试内容",
        "btn_orientation": "1",
        "btn_title_1": "btn_title_1",
        "action_url_1": "dingtalk.com",
        "btn_title_2": "btn_title_1",
        "action_url_2": "dingtalk.com",
        "btn_title_3": "btn_title_1",
        "action_url_3": "dingtalk.com",
        "btn_title_4": "btn_title_1",
        "action_url_4": "dingtalk.com"
    },
    "msg_template_id": "inner_app_template_action_card"
}

第三方企业应用

如果你的应用是三方企业应用，需要先使用官方测试消息模板进行测试，测试通过后，找钉钉小二定制专属群模板，流程请参考概述和准备基础消息内容。

官方测试消息模板**：msg_template_id**取值为offical_template_test_action_card。

传参示例如下：

{
    "robot_code": "iuEkXlixxx1002",
    "target_open_conversation_id": "3mwsbxxxfe==",
    "msg_param_map": {
        "title": "会话列表显示",
        "markdown": "# 测试内容",
        "btn_orientation": "1",
        "btn_title_1": "btn_title_1",
        "action_url_1": "dingtalk.com",
        "btn_title_2": "btn_title_2",
        "action_url_2": "dingtalk.com",
        "btn_title_3": "btn_title_3",
        "action_url_3": "dingtalk.com",
        "btn_title_4": "btn_title_4",
        "action_url_4": "dingtalk.com"
    },
    "msg_template_id": "offical_template_test_action_card"
}

模板占位符Key值如下。

参数	说明
title	会话列表显示标题。
markdown	消息内容，支持markdown语法。
btn_orientation	按钮排列方向，仅2个按钮时有效，传值为2时水平排列。
btn_title_1 ~ btn_title_4	按钮文案，支持最多4个按钮，传空或不传则按钮不显示。
action_url_1 ~ action_url_4	按钮跳转地址，支持最多4个按钮，传空或不传则按钮不显示。

以下为官方通用测试模板原文，后续可参考下附原文的格式提供定制需求，包括自定义模板内容和占位符key。

{
    "msgtype": "actionCard",
    "actionCard": {
        "title": "${title}",
        "text": "${markdown}     # 该消息仅用于场景群开发者测试",
        "btnOrientation": "${btn_orientation}",
        "btns": [
            {
                "title": "${btn_title_1}",
                "actionURL": "${action_url_1}"
            },
            {
                "title": "${btn_title_2}",
                "actionURL": "${action_url_2}"
            },
            {
                "title": "${btn_title_3}",
                "actionURL": "${action_url_3}"
            },
            {
                "title": "${btn_title_4}",
                "actionURL": "${action_url_4}"
            }
        ]
    }
}

消息效果如下图。

错误码

错误码（errorcode）	错误码描述（errmsg）	解决方案
40036	入参为空	根据接口要求，传入必要参数。
660001	群编码为空	请传入正确的群ID，可通过创建群接口获取。
660002	机器人编码为空	请传入正确的机器人code。
660012	不允许往该群发送卡片	请检查该群是否正确启用了群模板，可通过启用群模板接口启用群模板。
660014	查无此机器人	请检查传入的群机器人编码是否正确。
660015	查无此场景群	请检查传入的openConversationId是否正确，可通过创建群接口获取。
660016	机器人不可用	对应机器人已不可用（可能已被群管理员删除），请重新绑定群助手机器人。
660018	查询图片文件地址失败	请检查指定的图片mediaId是否正确，可通过上传媒体文件接口获取。
660020	重复的占位符KEY	文本和多媒体占位符不能包含同名占位符，请修改消息内容中的占位符。
660022	接收人识别失败	请检查接收人参数是否错误，可通过查询群成员接口获取。
660023	群编码解码失败	请检查群编码是否填写正确。
660024	查无此消息模板	请检查消息模板是否正确。
660025	消息模板渲染失败	请检查消息模板动参的入参是否合法。
660026	机器人发送消息失败	请重试。
660027	消息模板ID为空	请传入消息模板。
-1	系统异常	重试后如果还是出现此错误，请在开发者后台提交工单。

curl --location --request POST 'https://oapi.dingtalk.com/topapi/im/chat/scencegroup/message/send_v2' \ --header 'Content-Type: application/json' \ --data-raw '{ "robot_code": "fTv5O*****", "receiver_union_ids": "jHs*****,atc*****", "is_at_all": "false", "receiver_user_ids": "072*****,manager422*****", "at_mobiles": "137*****000", "at_users":"072*****", "target_open_conversation_id": "cid9FTRQSLo+sK*****==", "msg_param_map": "{\"title\":\"测试\",\"markdown_content\":\"# 测试内容 \n @180xxxx3120\"}", "msg_media_id_param_map": "{\"pic1\":\"@123\",\"pic2\":\"@456\"}", "msg_template_id": "inner_app_template_markdown" }'

发送群助手消息

权限

场景群通用消息模板

企业内部应用

第三方企业应用

错误码

请求参数

返回响应

发送群助手消息

权限#

场景群通用消息模板#

企业内部应用#

第三方企业应用#

错误码#

请求参数

返回响应

权限

场景群通用消息模板

企业内部应用

第三方企业应用

错误码