消息

我們的 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 對象而已：

暫時略。

群發消息

請參考：群發消息

消息轉發給客服系統

參見：多客服消息轉發