消息
我們的 SDK
把微信的 API
里的所有 “消息” 都按類型抽象出來了,也就是說,你不用區分它是回復消息還是主動推送消息,免去了你去手動拼裝微信的 XML
以及亂七八糟命名不統一的 JSON
了。
在閱讀以下內容時請忽略是 接收消息
還是 回復消息
,后面我會給你講它們的區別。
消息類型
消息分為以下幾種:文本
、圖片
、視頻
、聲音
、鏈接
、坐標
、圖文
、文章
和一種特殊的 原始消息
。
另外還有一種特殊的消息類型:素材消息
,用于群發或者客服時發送已有素材用。
注意:回復消息與客服消息里的圖文類型為:圖文,群發與素材中的圖文為 文章
所有的消息類都在 EasySwoole\WeChat\Kernel\Messages
這個命名空間下,下面我們來分開講解:
文本消息
屬性列表:
-
content
文本內容
<?php
use EasySwoole\WeChat\Kernel\Messages\Text;
$text = new Text('您好! EasySwoole WeChat!');
// or
$text = new Text('');
$text->setContent('您好! EasySwoole WeChat!');
// or
$text = new Text('');
$text->setAttribute('content', '您好! EasySwoole WeChat!');
圖片消息
屬性列表:
-
media_id
媒體資源ID
<?php
use EasySwoole\WeChat\Kernel\Messages\Image;
$image = new Image($mediaId);
視頻消息
屬性列表:
-
title
標題 -
description
描述 -
media_id
媒體資源ID
-
thumb_media_id
封面資源ID
<?php
use EasySwoole\WeChat\Kernel\Messages\Video;
$title = 'i am title!';
$description = 'i am description!';
$video = new Video($mediaId);
$video->setAttributes([
'title' => $title,
'description' => $description
]);
// or
$video = new Video($mediaId);
$video->setAttribute('title', $title);
$video->setAttribute('description', $description);
聲音消息
屬性列表:
-
media_id
媒體資源ID
<?php
use EasySwoole\WeChat\Kernel\Messages\Voice;
$voice = new Voice($mediaId);
鏈接消息
微信目前不支持回復鏈接消息
坐標消息
微信目前不支持回復坐標消息
圖文消息
圖文消息分為 NewsItem
與 News
,NewsItem
為圖文內容條目。
10 月 12 日起,被動回復消息 與 客服消息接口 的
圖文消息類型
中圖文數目
只能為一條。
NewsItem
屬性:
-
title
標題 -
description
描述 -
image
圖片鏈接 -
url
鏈接URL
<?php
use EasySwoole\WeChat\Kernel\Messages\News;
use EasySwoole\WeChat\Kernel\Messages\NewsItem;
$items = [
new NewsItem([
'title' => $title,
'description' => '...',
'url' => $url,
'image' => $image,
// ...
]),
];
$news = new News($items);
文章
屬性列表:
-
title
標題 -
author
作者 -
content
具體內容 -
thumb_media_id
圖文消息的封面圖片素材id
(必須是永久mediaID
) -
digest
圖文消息的摘要,僅有單圖文消息才有摘要,多圖文此處為空 -
source_url
來源URL
-
show_cover
是否顯示封面,0
為false
,即不顯示,1
為true
,即顯示
<?php
use EasySwoole\WeChat\Kernel\Messages\Article;
$article = new Article([
'title' => 'EasySwoole WeChat',
'author' => 'EasySwoole',
'content' => 'EasySwoole WeChat 是一個開源的微信 SDK!',
// ...
]);
// or
$article = new Article();
$article->setAttribute('title', 'EasySwoole WeChat');
$article->setAttribute('author', 'EasySwoole');
$article->setAttribute('content', 'EasySwoole WeChat 是一個開源的微信 SDK!');
// ...
素材消息
素材消息用于群發與客服消息時使用。
素材消息不支持被動回復,如需被動回復素材消息,首先組裝后,再
News
方法返回。
屬性就一個:media_id
。
在構造時有兩個參數:
-
$type
素材類型,目前只支持:mpnews
、mpvideo
、voice
、image
等。 -
$mediaId
素材ID
,從接口查詢或者上傳后得到。
<?php
use EasySwoole\WeChat\Kernel\Messages\Media;
$media = new Media($mediaId, 'mpnews');
以上呢,是所有微信支持的基本消息類型。
需要注意的是,你不需要關心微信的消息字段叫啥,因為這里我們使用了更標準的命名,然后最終在中間做了轉換,所以你不需要關注。
原始消息
原始消息是一種特殊的消息,它的場景是:你不想使用其它消息類型,你想自己手動拼消息。比如,回復消息時,你想自己拼 XML
,那么你就直接用它就可以了:
<?php
use EasySwoole\WeChat\Kernel\Messages\Raw;
use EasySwoole\WeChat\Kernel\Utility\XML;
$dataArr = [
'ToUserName' => 'toUser',
'FromUserName' => 'fromUser',
'CreateTime' => '12345678',
'MsgType' => 'image',
'Image' => [
'MediaId' => 'media_id'
],
];
// 即 '<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>12345678</CreateTime><MsgType><![CDATA[image]]></MsgType><Image><MediaId><![CDATA[media_id]]></MediaId></Image></xml>'
$rawXml = XML::build($dataArr);
$message = new Raw($rawXml);
// or
$message = new Raw('<xml><ToUserName><![CDATA[toUser]]></ToUserName><FromUserName><![CDATA[fromUser]]></FromUserName><CreateTime>12345678</CreateTime><MsgType><![CDATA[image]]></MsgType><Image><MediaId><![CDATA[media_id]]></MediaId></Image></xml>');
比如,你要用于客服消息 (客服消息是 JSON
結構):
<?php
use EasySwoole\WeChat\Kernel\Messages\Raw;
$dataArr1 = [
'touser' => 'OPENID',
'msgtype' => 'text',
'text' => [
'content' => 'Hello World'
]
];
$message = new Raw(json_encode($dataArr1));
// or
$message = new Raw('{"touser":"OPENID","msgtype":"text","text":{"content":"Hello World"}}');
總之,就是直接寫微信接口要求的格式內容就好,此類型消息在 SDK
中不存在轉換行為,所以請注意不要寫錯格式。
在 SDK 中使用消息
在服務端回復消息
在 服務端 章節中,我們講了回復消息的寫法:
<?php
// ... 前面部分省略
$server = $officialAccount->server;
/** 注冊消息事件回調 */
$server->push(function (\EasySwoole\WeChat\Kernel\Contracts\MessageInterface $message) {
return new \EasySwoole\WeChat\Kernel\Messages\Text("您好!歡迎使用 EasySwoole WeChat!");
});
$replyResponse = $server->forceValidate()->serve($psr7Request);
上面 return
轉換為 Text
文本類型的動作。
如果你要回復其它類型的消息,可以選擇返回一個其他具體的實例,比如回復一個圖片類型的消息:
<?php
use EasySwoole\WeChat\Kernel\Messages\Image;
// ...
$server = $officialAccount->server;
/** 注冊消息事件回調 */
$server->push(function (\EasySwoole\WeChat\Kernel\Contracts\MessageInterface $message) {
return new \EasySwoole\WeChat\Kernel\Messages\Image('media-id');
});
// ...
回復多圖文消息
10 月 12 日起,被動回復消息 與 客服消息接口 的 圖文消息類型 中 圖文數目 只能為一條。
多圖文消息其實就是單圖文消息的一個數組而已了:
<?php
use EasySwoole\WeChat\Kernel\Messages\News;
use EasySwoole\WeChat\Kernel\Messages\NewsItem;
// ...
$server = $officialAccount->server;
/** 注冊消息事件回調 */
$server->push(function (\EasySwoole\WeChat\Kernel\Contracts\MessageInterface $message) {
$items = [
new NewsItem([
'title' => $title,
'description' => '...',
'url' => $url,
'image' => $image,
// ...
]),
new NewsItem([
'title' => $title,
'description' => '...',
'url' => $url,
'image' => $image,
// ...
]),
];
return new News($items);
});
// ...
作為客服消息發送
在客服消息里的使用也一樣,都是直接傳入消息實例即可:
暫時略。
發送多圖文消息
10 月 12 日起,被動回復消息 與 客服消息接口 的 圖文消息類型 中 圖文數目 只能為一條。
多圖文消息其實就是單圖文消息組成的一個 News
對象而已:
暫時略。
群發消息
請參考:群發消息
消息轉發給客服系統
參見:多客服消息轉發