ECJiaWiki:Ecjia后台微信公众平台常用方法使用说明

获取微信实例：

注意：每次调用微信方法前，必须先获取微信示例。

RC_Loader::load_app_class('platform_account', 'platform', false);
$uuid = platform_account::getCurrentUUID('wechat');
$wechat = with(new Ecjia\App\Wechat\WechatUUID($uuid))->getWechatInstance();

用户

用户信息的获取是微信开发中比较常用的一个功能了，以下所有的用户信息的获取与更新，都是基于微信的 openid 的，并且是已关注当前账号的，其它情况可能无法正常使用。

获取用户信息

获取单个：

$user = $wechat->user->get($openId);

获取多个：

$users = $wechat->user->batchGet([$openId1, $openId2, ...]);

获取用户列表

$wechat->user->list($nextOpenId = null);// $nextOpenId 可选

示例：

 $users = $wechat->user->list();
// result
 {
  "total": 2,
  "count": 2,
  "data": {
    "openid": [
      "OPENID1",
      "OPENID2"
    ]
  },
  "next_openid": "NEXT_OPENID"
}

修改用户备注

$wechat->user->remark($openId, $remark); // 成功返回boolean

示例：

$wechat->user->remark($openId, "僵尸粉");

获取用户所在分组

$wechat->user->group($openId);

或者：

$wechat->user->getGroup($openId);

用户标签

获取所有标签

$user = $wechat->user_tag->list();

示例：

$tags = $wechat->user_tag->list();

// {
//     "tags": [
//         {
//             "id": 0,
//             "name": "标签1",
//             "count": 72596
//         },
//         {
//             "id": 1,
//             "name": "标签2",
//             "count": 36
//         },
//         ...
//     ]
// }

创建标签

$wechat->user_tag->create($name);

示例：

$wechat->user_tag->create('测试标签');

修改标签信息

$wechat->user_tag->update($tagId, $name);

示例：

$wechat->user_tag->update(12, "新的名称");

删除标签

$wechat->user_tag->delete($tagId);

获取指定 openid 用户所属的标签

$userTags = $wechat->user_tag->userTags($openId);
//
// {
//     "tagid_list":["标签1","标签2"]
// }

获取获取标签下用户列表

$wechat->user_tag->usersOfTag($tagId, $nextOpenId = '');
// $nextOpenId：第一个拉取的OPENID，不填默认从头开始拉取

// {
//   "count":2, // 这次获取的粉丝数量
//   "data":{ // 粉丝列表
//      "openid":[
//          "ocYxcuAEy30bX0NXmGn4ypqx3tI0",
//          "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"
//      ]
//   },
//   "next_openid":"ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"//拉取列表最后一个用户的openid
// }

批量为用户添加标签

$openIds = [$openId1, $openId2, ...];
$wechat->user_tag->batchTagUsers($openIds, $tagId);

批量为用户移除标签

$openIds = [$openId1, $openId2, ...];
$wechat->user_tag->batchUntagUsers($openIds, $tagId);

JSSDK

API

$config = $wechat->js->config(array $APIs, $debug = false, $beta = false, $json = true);

获取JSSDK的配置数组，默认返回 JSON 字符串，当 $json 为 false 时返回数组，你可以直接使用到网页中。

$wechat->js->setUrl($url);

设置当前URL，如果不想用默认读取的URL，可以使用此方法手动设置，通常不需要。

示例：

我们可以生成js配置文件：

<script src="http://res.wx.qq.com/open/js/jweixin-1.0.0.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
wx.config(<?php echo $wechat->js->config(array('onMenuShareQQ', 'onMenuShareWeibo'), true) ?>);
</script>

结果如下：

<script src="http://res.wx.qq.com/open/js/jweixin-1.0.0.js" type="text/javascript" charset="utf-8"></script>
<script type="text/javascript" charset="utf-8">
wx.config({
    debug: true,
    appId: 'wx3cf0f39249eb0e60',
    timestamp: 1430009304,
    nonceStr: 'qey94m021ik',
    signature: '4F76593A4245644FAE4E1BC940F6422A0C3EC03E',
    jsApiList: ['onMenuShareQQ', 'onMenuShareWeibo']
});

临时素材

上传的临时多媒体文件有格式和大小限制，如下：

• 图片（image）: 1M，支持 JPG 格式
• 语音（voice）：2M，播放长度不超过 60s，支持 AMR\MP3 格式
• 视频（video）：10MB，支持 MP4 格式
• 缩略图（thumb）：64KB，支持 JPG 格式

上传临时素材

$wechat->material_temporary->upload($type, $path);

上传图片

注意：微信图片上传服务有敏感检测系统，图片内容如果含有敏感内容，如色情，商品推广，虚假信息等，上传可能失败。

$wechat->material_temporary->uploadImage($path);

上传声音

$wechat->material_temporary->uploadVoice($path);

上传视频

$wechat->material_temporary->uploadVideo($path, $title, $description);

上传缩略图

$wechat->material_temporary->uploadThumb($path);

获取临时素材内容

$wechat->material_temporary->download($mediaId, $directory, $filename = '');

二维码

目前有 2 种类型的二维码：

• 临时二维码，是有过期时间的，最长可以设置为在二维码生成后的 30天后过期，但能够生成较多数量。临时二维码主要用于帐号绑定等不要求二维码永久保存的业务场景
• 永久二维码，是无过期时间的，但数量较少（目前为最多10万个）。永久二维码主要用于适用于帐号绑定、用户来源统计等场景。

创建临时二维码

$result = $wechat->qrcode->temporary('foo', 6 * 24 * 3600);
// Array
// (
//     [ticket] => gQFD8TwAAAAAAAAAAS5odHRwOi8vd2VpeGluLnFxLmNvbS9xLzAyTmFjVTRWU3ViUE8xR1N4ajFwMWsAAgS2uItZAwQA6QcA
//     [expire_seconds] => 518400
//     [url] => http://weixin.qq.com/q/02NacU4VSubPO1GSxj1p1k
// )

创建永久二维码

$result = $wechat->qrcode->forever(56);// 或者 $wechat->qrcode->forever("foo");
// Array
// (
//     [ticket] => gQFD8TwAAAAAAAAAAS5odHRwOi8vd2VpeGluLnFxLmNvbS9xLzAyTmFjVTRWU3ViUE8xR1N4ajFwMWsAAgS2uItZAwQA6QcA
//     [url] => http://weixin.qq.com/q/02NacU4VSubPO1GSxj1p1k
// )

获取二维码网址

$url = $wechat->qrcode->url($ticket);
// https://api.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET

获取二维码内容

$url = $wechat->qrcode->url($ticket);
$content = file_get_contents($url); // 得到二进制图片内容
file_put_contents(__DIR__ . '/code.jpg', $content); // 写入文件

短网址

主要使用场景： 开发者用于生成二维码的原链接（商品、支付二维码等）太长导致扫码速度和成功率下降，将原长链接通过此接口转成短链接再生成二维码将大大提升扫码速度和成功率。

长链接转短链接

$shortUrl = $wechat->url->shorten('https://easywechat.com');
//Array
//(
//    [errcode] => 0
//    [errmsg] => ok
//    [short_url] => https://w.url.cn/s/Aq7jWrd
//)

素材管理

在微信里的图片，音乐，视频等等都需要先上传到微信服务器作为素材才可以在消息中使用。

上传图片

注意：微信图片上传服务有敏感检测系统，图片内容如果含有敏感内容，如色情，商品推广，虚假信息等，上传可能失败。

$result = $wechat->material->uploadImage("/path/to/your/image.jpg");
// {
//    "media_id":MEDIA_ID,
//    "url":URL
// }

url 只有上传图片素材有返回值。

上传语音

语音 大小不超过 5M，长度不超过 60 秒，支持 mp3/wma/wav/amr 格式。

$result = $wechat->material->uploadVoice("/path/to/your/voice.mp3");
// {
//    "media_id":MEDIA_ID,
// }

上传视频

$result = $wechat->material->uploadVideo("/path/to/your/video.mp4", "视频标题", "视频描述");
// {
//    "media_id":MEDIA_ID,
// }

上传缩略图

用于视频封面或者音乐封面。

$result = $wechat->material->uploadThumb("/path/to/your/thumb.jpg");
// {
//    "media_id":MEDIA_ID,
// }

上传图文消息

// 上传单篇图文
$article = new Article([
    'title' => 'xxx',
    'thumb_media_id' => $mediaId,
    //...
  ]);
$wechat->material->uploadArticle($article);

// 或者多篇图文
$wechat->material->uploadArticle([$article, $article2, ...]);

修改图文消息

有三个参数：

• $mediaId 要更新的文章的 mediaId
• $article 文章内容，Article 实例或者 全字段数组
• $index 要更新的文章在图文消息中的位置（多图文消息时，此字段才有意义，单图片忽略此参数），第一篇为 0；

$result = $wechat->material->updateArticle($mediaId, new Article(...));

// or

$result = $wechat->material->updateArticle($mediaId, [
   'title' => 'test',
    'thumb_media_id' => 'qQFxUQGO21Li4YrSn3MhnrqtRp9Zi3cbM9uBsepvDmE', // 封面图片 mediaId
    'author' => 'overtrue', // 作者
    'show_cover' => 1, // 是否在文章内容显示封面图片
    'digest' => '这里是文章摘要',
    'content' => '这里是文章内容，你可以放很长的内容',
    'source_url' => 'https://ecjia.com',
  ]);

// 指定更新多图文中的第 2 篇
$result = $wechat->material->updateArticle($mediaId, new Article(...), 1); // 第 2 篇

修改图文消息图片

返回值中 url 就是上传图片的 URL，可用于后续群发中，放置到图文消息中。

$result = $wechat->material->uploadArticleImage($path);
//{
//    "url":  "http://mmbiz.qpic.cn/mmbiz/gLO17UPS6FS2xsypf378iaNhWacZ1G1UplZYWEYfwvuU6Ont96b1roYsCNFwaRrSaKTPCUdBK9DgEHicsKwWCBRQ/0"
//}

获取永久素材

$resource = $wechat->material->get($mediaId);

如果请求的素材为图文消息，则响应如下：

{
 "news_item": [
       {
       "title":TITLE,
       "thumb_media_id"::THUMB_MEDIA_ID,
       "show_cover_pic":SHOW_COVER_PIC(0/1),
       "author":AUTHOR,
       "digest":DIGEST,
       "content":CONTENT,
       "url":URL,
       "content_source_url":CONTENT_SOURCE_URL
       },
       //多图文消息有多篇文章
    ]
  }

如果返回的是视频消息素材，则内容如下：

{
  "title":TITLE,
  "description":DESCRIPTION,
  "down_url":DOWN_URL,
}

获取永久素材列表

• $type 素材的类型，图片（image）、视频（video）、语音 （voice）、图文（news）
• $offset 从全部素材的该偏移位置开始返回，可选，默认 0，0 表示从第一个素材 返回
• $count 返回素材的数量，可选，默认 20, 取值在 1 到 20 之间

$wechat->material->list($type, $offset, $count);

示例：

$list = $wechat->material->list('image', 0, 10);

图片、语音、视频 等类型的返回如下

{
   "total_count": TOTAL_COUNT,
   "item_count": ITEM_COUNT,
   "item": [{
       "media_id": MEDIA_ID,
       "name": NAME,
       "update_time": UPDATE_TIME,
       "url":URL
   },
   //可能会有多个素材
   ]
}

永久图文消息素材列表的响应如下：

{
   "total_count": TOTAL_COUNT,
   "item_count": ITEM_COUNT,
   "item": [{
       "media_id": MEDIA_ID,
       "content": {
           "news_item": [{
               "title": TITLE,
               "thumb_media_id": THUMB_MEDIA_ID,
               "show_cover_pic": SHOW_COVER_PIC(0 / 1),
               "author": AUTHOR,
               "digest": DIGEST,
               "content": CONTENT,
               "url": URL,
               "content_source_url": CONTETN_SOURCE_URL
           },
           //多图文消息会在此处有多篇文章
           ]
        },
        "update_time": UPDATE_TIME
    },
    //可能有多个图文消息item结构
  ]
}

获取素材数量

$stats = $wechat->material->stats();

// {
//   "voice_count":COUNT,
//   "video_count":COUNT,
//   "image_count":COUNT,
//   "news_count":COUNT
// }

删除永久素材

$wechat->material->delete($mediaId);

自定义菜单

读取（查询）已设置菜单

$list = $wechat->menu->all();

获取当前菜单

$current = $wechat->menu->current();

添加菜单

添加普通菜单

$buttons = [
    [
        "type" => "click",
        "name" => "今日歌曲",
        "key"  => "V1001_TODAY_MUSIC"
    ],
    [
        "name"       => "菜单",
        "sub_button" => [
            [
                "type" => "view",
                "name" => "搜索",
                "url"  => "http://www.soso.com/"
            ],
            [
                "type" => "view",
                "name" => "视频",
                "url"  => "http://v.qq.com/"
            ],
            [
                "type" => "click",
                "name" => "赞一下我们",
                "key" => "V1001_GOOD"
            ],
        ],
    ],
];
$wechat->menu->add($buttons);

以上将会创建一个普通菜单。

添加个性化菜单

与创建普通菜单不同的是，需要在 create() 方法中将个性化匹配规则作为第二个参数传进去：

$buttons = [
    // ...
];
$matchRule = [
    "tag_id" => "2",
    "sex" => "1",
    "country" => "中国",
    "province" => "广东",
    "city" => "广州",
    "client_platform_type" => "2",
    "language" => "zh_CN"
];
$wechat->menu->add($buttons, $matchRule);

删除菜单

有两种删除方式，一种是全部删除，另外一种是根据菜单 ID 来删除(删除个性化菜单时用，ID 从查询接口获取)：

$wechat->menu->destroy(); // 全部
$wechat->menu->destroy($menuId);

测试个性化菜单

$wechat->menu->test($userId);

$userId 可以是粉丝的 OpenID，也可以是粉丝的微信号。

返回 $menu 与指定的 $userId 匹配的菜单项。

客服

客服管理

获取所有客服

$wechat->staff->list();

获取所有在线的客服

$wechat->staff->onlines();

添加客服

$wechat->staff->create('foo@test', '客服1');

修改客服

$wechat->staff->update('foo@test', '客服1');

删除账号

$wechat->staff->delete('foo@test');

设置客服头像

$wechat->staff->avatar('foo@test', $avatarPath); // $avatarPath 为本地图片路径，非 URL

获取客服与客户聊天记录

$wechat->staff->records($startTime, $endTime, $msgId = 1, $number = 10000);

示例:

$wechat= $wechat->staff->records('2015-06-07', '2015-06-21', 1, 20000);

邀请微信用户加入客服

以账号 foo@test 邀请 openid 为 openidxxxx 的微信用户加入客服。

$wechat->staff->invite('foo@test', 'openidxxxx');

客服会话控制

获取客服会话列表

$wechat->staff_session->list('test1@test');

获取未接入会话列表

$wechat->staff_session->waiters();

创建会话

$wechat->staff_session->create('test1@test', 'OPENID');

关闭会话

$wechat->staff_session->close('test1@test', 'OPENID');

获取客户会话状态

$wechat->staff_session->get('OPENID');