ymlluo/group-robot

钉钉、企业微信、飞书 自定义群组机器人。支持链式语法创建发送消息。支持文本、Markdown、图片、文件、图文、卡片等消息。

v1.1.2 2022-06-13 15:09 UTC

Requires

• php: ^7.1|^8.0
• ext-curl: *
• ext-json: *
• ext-zip: *
• guzzlehttp/guzzle: >=6.0

Requires (Dev)

• orchestra/testbench: ~5|~6
• phpunit/phpunit: ~9.0

MIT

• Ymlluo

• laravel
• wechat
• robot
• dingtalk
• GroupRobot
• Feishu

README

通用消息类型支持情况

APP	名称	文本	MD	图片	文件	图文	卡片
企业微信	wechat	√	√	√	√	√	√
钉钉	dingtalk	√	√	√	√	√	√
飞书	feishu	√	√	×	√	×	√

Table of Contents

• 群机器人
  • 通用消息类型支持情况
• Table of Contents
• 安装
• 使用说明
  • 企业微信
    • 初始化
    • 原生消息
    • 文本
    • Markdown
    • 网络图片
    • 本地图片
    • 网络文件
    • 本地文件
    • 图文
    • 通用卡片
    • 模版卡片
  • 钉钉
    • 初始化
    • 原生消息
    • 文本
    • Markdown
    • 图片
    • 文件
    • 单条图文
    • 链接消息
    • 多条图文
    • FeedCard
    • 通用卡片
    • actionCard
  • 飞书
    • 初始化
    • 原生消息
    • 文本
    • Markdown
    • 图片
    • 图文消息
    • 文件
    • 通用卡片
    • 消息卡片
    • 富文本
  • Laravel 支持
  • 进阶用法
    • 使用「队列」同时发送多条消息
    • 使用「抄送」功能向多个平台发送消息
    • 定义平台
  • Contributing
  • Security
  • License

Created by gh-md-toc

安装

Via Composer

$ composer require ymlluo/group-robot

升级 composer 版本 v2

 
sudo apt-get remove composer;
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');";
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');";
composer self-update;

使用说明

** 特别特别要注意：一定要保护好机器人的webhook地址，避免泄漏！**

企业微信

企业微信-群机器人配置说明

初始化

```php 
//初始化
$webhook = 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa';

/**
 * GroupRobot constructor.
 * @param string $platform 发送平台，wechat:企业微信,dingtalk:钉钉,feishu:飞书
 * @param string $webhook webhook 地址
 * @param string $secret 秘钥,加密方式加签时必填，企业微信不支持这个参数
 * @param string $alias 别名，多渠道发送时方便区分结果
 */
$robot = new GroupRobot('wechat', $webhook, '', 'robot_wx_1');

原生消息

$robot->raw(['msgtype'=>'text','text'=>['content'=>'hello world!']])->send();

文本

• 支持 @全部、@用户、@手机号
• 文本内容，单条最多2048个字节。
• 发送内容超过 2048 个字节，会分成多条发送（使用 \n 分割）

$robot->text('hello world')->send();

//@全部
$robot->text('hello world')->atAll()->send();

//@用户
$robot->text('hello world')->atUsers(["wangqing"])->send();

//@手机号
$robot->text('hello world')->atMobiles(["13800001111"])->send();

Markdown

• 仅支持 @用户
• markdown内容，最长不超过 4096 个字节。
• 发送内容超过 4096 个字节，会拆分成多条发送（使用 \n 分割）

 $robot->markdown("实时新增用户反馈<font color=\"warning\">132例</font>，请相关同事注意。")->send();

 $robot->markdown("### 用户反馈，请相关同事注意。")->atUsers(["wangqing"])->send();

网络图片

• 程序会下载图片到本地后再上传到微信服务器

$robot->image('http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png')->send();

本地图片

$robot->image('/tmp/images/test_pic_msg1.png')->send();

网络文件

• 程序会下载文件到本地后再上传到微信服务器

$robot->file('http://www.gov.cn/zhengce/pdfFile/2021_PDF.pdf','政府信息公开目录.pdf')->send();

本地文件

$robot->file('/tmp/pdfFile/2021_PDF.pdf','政府信息公开目录.pdf')->send();

图文

//单条图文
$robot->news([
  'title' => '中秋节礼品领取',
  'description' => '今年中秋节公司有豪礼相送',
  'url' => 'www.qq.com',
  'picurl' => 'http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png'
  ])->send();
  

//多条图文  
$robot->news([
  [
    'title' => '胡彦斌，不再为爱情燃烧',
    'description' => '胡彦斌最被大众好奇的问题是：他现在会如何看待感情？',
    'url' => 'https://new.qq.com/omn/20211028/20211028A07EDT00.html',
    'picurl' => 'https://inews.gtimg.com/newsapp_bt/0/14116849898/1000'
  ], 
  [
    'title' => '中秋节礼品领取',
    'description' => '今年中秋节公司有豪礼相送',
    'url' => 'www.qq.com',
    'picurl' => 'http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png'
  ]
])->send();

通用卡片

• 基于模板卡片 - news_notice 构建

$robot->card(
  "Apple Store 的前身",//一级标题，建议不超过26个字
  "乔布斯 20 年前想打造的苹果咖啡厅 \nApple Store 的设计正从原来满满的科技感走向生活化，而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划",//标题辅助信息，建议不超过30个字
  "https://gw.alicdn.com/tfs/TB1ut3xxbsrBKNjSZFpXXcXhFXa-846-786.png",//封面图片
  "https://www.qq.com/",//链接跳转的url
  [['title' => '钉钉', 'url' => 'https://www.dingtalk.com/'], ['title' => '百度', 'url' => 'https://www.baidu.com/']]
)->send();

模版卡片

//文本通知模版卡片
$robot->template_card([
            'card_type' => 'text_notice',
            'source' => [
                'icon_url' => 'https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0',
                'desc' => '企业微信',
            ],
            'main_title' => [
              [
                'title' => '欢迎使用企业微信',
                'desc' => '您的好友正在邀请您加入企业微信',
              ]
            ],
            'emphasis_content' => [
                'title' => '100',
                'desc' => '数据含义',
            ],
            'sub_title_text' => '下载企业微信还能抢红包！',
            'horizontal_content_list' => [
                0 => [
                    'keyname' => '邀请人',
                    'value' => '张三',
                ],
                1 => [
                    'keyname' => '企微官网',
                    'value' => '点击访问',
                    'type' => 1,
                    'url' => 'https://work.weixin.qq.com/?from=openApi',
                ]
            ],
            'jump_list' => [
                0 => [
                    'type' => 1,
                    'url' => 'https://work.weixin.qq.com/?from=openApi',
                    'title' => '企业微信官网',
                ]
            ],
            'card_action' => [
                'type' => 1,
                'url' => 'https://work.weixin.qq.com/?from=openApi',
                'appid' => 'APPID',
                'pagepath' => 'PAGEPATH',
            ],
        ])->send();

//图文展示模版卡片
$robot->template_card([
            'card_type' => 'news_notice',
            'source' => [
                'icon_url' => 'https://wework.qpic.cn/wwpic/252813_jOfDHtcISzuodLa_1629280209/0',
                'desc' => '企业微信',
            ],
            'main_title' => [
                'title' => '欢迎使用企业微信',
                'desc' => '您的好友正在邀请您加入企业微信',
            ],
            'card_image' => [
                'url' => 'https://wework.qpic.cn/wwpic/354393_4zpkKXd7SrGMvfg_1629280616/0',
                'aspect_ratio' => 2.25,
            ],
            'vertical_content_list' =>[
              'title'=>'惊喜红包等你来拿',
              'desc'=>'下载企业微信还能抢红包！'
            ],
            'horizontal_content_list' => [
                0 => [
                    'keyname' => '邀请人',
                    'value' => '张三',
                ],
                1 => [
                    'keyname' => '企微官网',
                    'value' => '点击访问',
                    'type' => 1,
                    'url' => 'https://work.weixin.qq.com/?from=openApi',
                ]
            ],
            'jump_list' => [
                0 => [
                    'type' => 1,
                    'url' => 'https://work.weixin.qq.com/?from=openApi',
                    'title' => '企业微信官网',
                ]
            ],
            'card_action' => [
                'type' => 1,
                'url' => 'https://work.weixin.qq.com/?from=openApi',
                'appid' => 'APPID',
                'pagepath' => 'PAGEPATH',
            ],
        ])->send();

钉钉

钉钉-自定义机器人接入

初始化

//初始化并设置webhook
$webhook = 'https://oapi.dingtalk.com/robot/send?access_token=XXXXXX';
$token = 'xxx';

/**
 * @param string $platform 发送平台，wechat:企业微信,dingtalk:钉钉,feishu:飞书
 * @param string $webhook webhook 地址
 * @param string $secret 秘钥,加密方式加签时必填，企业微信不支持这个参数
 * @param string $alias 别名，多渠道发送时方便区分结果
 */
$robot = new GroupRobot('dingtalk',$webhook,$token,'d1');

原生消息

$robot->raw(['msgtype'=>'text','text'=>['content'=>'hello world!']])->send();

文本

• 支持 @全部、@用户、@手机号

$robot->text('hello world')->send();

//@全部
$robot->text('hello world')->atAll()->send();

//@用户 
$robot->text('hello world')->atUsers(["user123"])->send();

//@手机号
$robot->text('hello world')->atMobiles(["13800001111"])->send();

Markdown

• 支持 @全部、@用户、@手机号
• 目前只支持markdown语法的子集
• 参考文档： markdown语法

$robot->markdown("#### 杭州天气 \n > 9度，西北风1级，空气良89，相对温度73%\n > ![screenshot](https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png) \n", '杭州天气')->send();

$robot->markdown("at 全部用户 \n", 'at')->atAll()->send();

$robot->markdown("at 用户 \n", 'at')->atUsers(["user123"])->send();

$robot->markdown("at 手机 \n", 'at')->atMobiles(["13800001111"])->send();

图片

• 基于 Markdown 构建
• 仅支持网络图片
• 不支持本地图片

$robot->image("https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png")->send();

文件

• 基于 Markdown 构建
• 仅支持网络文件
• 不支持本地文件

$robot->file("http://h10032.www1.hp.com/ctg/Manual/c05440029.pdf", "HP 2600打印机说明书.pdf")->send();

单条图文

• 基于链接消息 link 构建

//单条图文
$robot->news([
  'title' => '中秋节礼品领取',
  'description' => '今年中秋节公司有豪礼相送',
  'url' => 'https://developers.dingtalk.com/document/robots/robot-overview',
  'picurl' => 'http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png'
])->send();

链接消息

//等同于
$robot->link([
  'title' => '中秋节礼品领取',
  'text' => '今年中秋节公司有豪礼相送',
  'messageUrl' => 'https://developers.dingtalk.com/document/robots/robot-overview',
  'picUrl' => 'http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png'
])->send();

多条图文

• 基于 FeedCard 构建

$robot->news([
  [
  'title' => '中秋节礼品领取',
  'url' => 'https://developers.dingtalk.com/document/robots/robot-overview',
  'picurl' => 'http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png'
  ],
  [
  'title' => '杭州天气',
  'url' => 'https://developers.dingtalk.com/document/robots/robot-overview',
  'picurl' => 'https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png'
  ],
])->send();

FeedCard

$robot->feedCard([
  [
  'title' => '中秋节礼品领取',
  'description' => '今年中秋节公司有豪礼相送',
  'messageURL' => 'https://developers.dingtalk.com/document/robots/robot-overview',
  'picURL' => 'http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png'
  ],
  [
  'title' => '杭州天气',
  'messageURL' => 'https://developers.dingtalk.com/document/robots/robot-overview',//注意是messageURL 不是messageUrl
  'picURL' => 'https://img.alicdn.com/tfs/TB1NwmBEL9TBuNjy1zbXXXpepXa-2400-1218.png' //注意是picURL 不是picUrl
  ],
])->send();

通用卡片

• 基于 ActionCard 构建

//Card 单个按钮
  $robot->card(
   "乔布斯 20 年前想打造一间苹果咖啡厅，而它正是 Apple Store 的前身",
   "### 乔布斯 20 年前想打造的苹果咖啡厅 \nApple Store 的设计正从原来满满的科技感走向生活化，而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划",
   "https://gw.alicdn.com/tfs/TB1ut3xxbsrBKNjSZFpXXcXhFXa-846-786.png",
   "https://www.dingtalk.com/",
   ['title'=>'阅读全文','url'=>'https://www.dingtalk.com/']
 )->send();

//Card 多个按钮
  $robot->card(
    "乔布斯 20 年前想打造一间苹果咖啡厅，而它正是 Apple Store 的前身",//标题
    "### 乔布斯 20 年前想打造的苹果咖啡厅",//描述
    "https://gw.alicdn.com/tfs/TB1ut3xxbsrBKNjSZFpXXcXhFXa-846-786.png",//封面图
    "https://www.dingtalk.com/",//跳转地址
    [['title' => '内容不错', 'url' => 'https://www.dingtalk.com/'], ['title' => '不感兴趣', 'url' => 'https://www.dingtalk.com/']],//按钮
    ['btnOrientation' => "1"] //非必填，按钮排列
)->send();

actionCard

//单个按钮
  $robot->actionCard([
   'title'=>'乔布斯 20 年前想打造一间苹果咖啡厅，而它正是 Apple Store 的前身',
   'text'=>"![screenshot](https://gw.alicdn.com/tfs/TB1ut3xxbsrBKNjSZFpXXcXhFXa-846-786.png) \n### 乔布斯 20 年前想打造的苹果咖啡厅 \nApple Store 的设计正从原来满满的科技感走向生活化，而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划",
   'btnOrientation'=>'0',
   'singleTitle'=>'阅读全文',
   'singleURL'=>'https://www.dingtalk.com/'
 ])->send();

//多个按钮
  $robot->actionCard([
    'title'=>'乔布斯 20 年前想打造一间苹果咖啡厅，而它正是 Apple Store 的前身',
    'text'=>"![screenshot](https://gw.alicdn.com/tfs/TB1ut3xxbsrBKNjSZFpXXcXhFXa-846-786.png) \n### 乔布斯 20 年前想打造的苹果咖啡厅 \nApple Store 的设计正从原来满满的科技感走向生活化，而其生活化的走向其实可以追溯到 20 年前苹果一个建立咖啡馆的计划",
     'btnOrientation'=>'0',
     'btns'=>[
       [
         'title'=>'内容不错',
         'actionURL'=>'https://www.dingtalk.com/'
       ],
       [
         'title'=>'不感兴趣',
         'actionURL'=>'https://www.dingtalk.com/'
       ]
     ]
 ])->send();

飞书

飞书-自定义机器人指南

初始化

//初始化并设置webhook
$webhook = 'https://open.feishu.cn/open-apis/bot/v2/hook/XXXXXX';
$token = 'xxx';
/**
 * @param string $platform 发送平台，wechat:企业微信,dingtalk:钉钉,feishu:飞书
 * @param string $webhook webhook 地址
 * @param string $secret 秘钥,加密方式加签时必填
 * @param string $alias 别名，多渠道发送时方便区分结果
 */
$robot = new GroupRobot('feishu',$webhook,$token,'feishu-1');

原生消息

$robot->raw(['msg_type'=>'text','content'=>['text'=>'hello world!']])->send();

文本

• 仅支持 @全部

$robot->text('hello world')->atAll()->send();

Markdown

• 基于卡片消息构建
• 无法使用与文本格式无关的markdown标签（比如图片、分割线）
• 目前只支持 markdown 语法的子集，支持的有限元素。
• 文档参考： 消息卡片构造卡片内容Markdown模块
• 仅支持 @全部

$robot->markdown("#### 杭州天气 \n > 9度，西北风1级，空气良89，相对温度73%\n", '杭州天气')->atAll()->send();

图片

不支持

图文消息

不支持

文件

• 基于卡片消息 Markdown 构建
• 仅支持网络文件，不支持本地文件

$robot->file("http://h10032.www1.hp.com/ctg/Manual/c05440029.pdf", "HP 2600打印机说明书.pdf")->send();

通用卡片

• card 方法基于 interactive 构建
• 不支持设置图片
• 模板样式参考：卡片支持的模板

//Card 单个按钮
  $robot->card(
   "乔布斯 20 年前想打造一间苹果咖啡厅，而它正是 Apple Store 的前身",//title
   "### 乔布斯 20 年前想打造的苹果咖啡厅",//描述
   "",//封面图片，不支持
   "https://www.dingtalk.com/",//跳转地址
   ['title'=>'阅读全文','url'=>'https://www.dingtalk.com/'],//选填，按钮
   ['template'=>'red'] //模板样式，
 )->send();

消息卡片

$robot->interactive([
            'header' => [
                'title' => [
                    'content' => '今日旅游推荐',
                    'tag' => 'plain_text'
                ]
            ],
            'elements' => [
                [
                    'tag' => 'div',
                    'text' => [
                        'content' => '**西湖**，位于浙江省杭州市西湖区龙井路1号',
                        'tag' => 'lark_md'
                    ]
                ],
                [
                    'tag' => 'markdown',
                    'content' => "*西湖美景二月天*"
                ],
                [
                    'tag' => 'action',
                    'actions' => [
                        [
                            'tag' => 'button',
                            'text' => [
                                'content' => '更多景点介绍 :玫瑰:',
                                'tag' => 'lark_md'
                            ],
                            'url' => 'https://feishu.cn',
                            'type' => 'default'
                        ]
                    ]
                ]
            ]
        ])->send();

富文本

• 仅支持 @全部

$robot->rich([
  'title' => '项目更新',
    'content' => [
    [
      [
        'tag' => 'text',
        'text' => '项目有更新:'
      ], 
      [
        'tag' => 'a',
        'text' => '请查看',
        'href' => 'https://feishu.cn'
      ],
      [
        'tag' => 'at',
        'user_id' => 'all'
      ]
    ]
  ]
])->send();

Laravel 支持

如果在Laravel 中使用，添加下面一行到 config/app.php 中 providers 部分：

Laravel > 5.5 支持 Package Auto-Discovery 无需手动添加配置

  Ymlluo\\GroupRobot\\GroupRobotServiceProvider::class

使用

$webhook = 'https://oapi.dingtalk.com/robot/send?access_token=xxxx';
$secret = 'xxx';
$results = app('grouprobot')->queue()->text("Hello ")->text('Laravel')->cc('dingtalk',$webhook, $secret, 'ding_1')->send();
dd($result);

进阶用法

使用「队列」同时发送多条消息

• 使用 queue() 方法可以把消息放到队列中，分别发送

$robot->queue()
  ->text("文本消息1")
  ->text("文本消息2")
  ->markdown("**Markdown**")
  ->file("http://h10032.www1.hp.com/ctg/Manual/c05440029.pdf", "HP 2600打印机说明书.pdf")
  ->send();

使用「抄送」功能向多个平台发送消息

$robot = new GroupRobot();
$robot->text("开始@".date('Y-m-d H:i:s',time()))
      ->text("结束@".date('Y-m-d H:i:s',time()))
      ->queue()
      ->cc('dingtalk','https://oapi.dingtalk.com/robot/send?access_token==xxxx','xxx','ding1')
      ->cc('wechat','https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxx','','wx_1')
      ->cc('feishu','https://open.feishu.cn/open-apis/bot/v2/hook/xxxx','xxx','feishu1')
      ->send();

定义平台

可以实现 src/Contracts/Platform.php 接口，通过自定义平台发送消息

<?php

namespace App;

use Ymlluo\GroupRobot\Contracts\Platform;
use Ymlluo\GroupRobot\Notify\BaseNotify;

class CustomerPlatform extends BaseNotify implements Platform
{
    // todo
}

$webhook = 'https://xxx.com/webhook/xxx';
$robot = new GroupRobot();
$custom = new CustomerPlatform(); 
$robot->extendPlatform($custom,$webhook,$secret='',$alias='c1')->text("hello !")->send();

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

MIT. Please see the license file for more information.