WeChatPHP-SDK
SDK to admin.wechat.com for php
TODO
API update: 高级群发接口 Request:
- Update WeChatServer.php
- Update WeChatClient.php
- Update Test
- Update Documents
Logs
- 2014-04-16 json_encode unicode escape fix
- 2014-03-27 Fix WeChatServer Response media
- 2014-02-18 add bnner & zh_CN setting for WeChatClient
- 2014-01-23 Upload
links
###WeChatServer.php
About
WeChatServer is used to start an api for admin.wechat.com to connect.
Getting start with Hook
Hook mark the position in process and you can handle data/process there.
Wiki
Hook List
# ============================================================
# Hook Name || Handle Function
# ============================================================
# All the event name you can use.
#
# ============================================================
# receiveAllStart => function( $postObj ){ ... }
# receiveMsg::text => /\
# receiveMsg::location => ||
# receiveMsg::image => ||
# receiveMsg::video => ||
# receiveMsg::link => /\
# receiveMsg::voice => ||
# receiveEvent::subscribe => ||
# receiveEvent::unsubscribe => ||
# receiveEvent::scan => ||
# receiveEvent::location => /\
# receiveEvent::click => ||
# receiveAllEnd => ||
# accessCheckSuccess => ||
# 404 => /\
# ============================================================
How to use hook?
<?PHP
include('WeChatServer.php');
function handle( $postData ){
// your code here...
}
$svr = new WeChatServer(
'your-token',
array( /* Hook here */
'HookName' => 'Handle Function Name OR Function'
/* demo */
'receiveMsg::text' => 'handle',
'receiveMsg::location' => handle,
'receiveMsg::image' => function( $postData ){ /* your code here */ }
)
);
Hooks detail:
- receiveAllStart [1st Hook before all]
$postData = array(
# Base Keys:
'id' => /* message id */ ,
'from' => /* follower open id */ ,
'to' => /* admin OA account id */ ,
'time' => /* msg timestamp */ ,
'type' => /* message type */
) + receiveMsg OR receiveEvent
- receiveMsg::text [type = text]
$postData = array(
/* ... base ... */
'content' => /* text content */
)
- receiveMsg::location [type = location]
$postData = array(
/* ... base ... */
'X' => /* latitude */ ,
'Y' => /* longitude */ ,
'S' => /* scale */ ,
'I' => /* label info */
)
- receiveMsg::image [type = image]
$postData = array(
/* ... base ... */
'url' => /* image url */ ,
'mid' => /* image media id (can download or sent to other) */
)
- receiveMsg::video [type = video]
$postData = array(
/* ... base ... */
'mid => /* video media id */ ,
'thumbmid' => /* thumb image media id */
)
- receiveMsg::link [type = link]
$postData = array(
/* ... base ... */
'title' => /* title */ ,
'desc' => /* description */ ,
'url' => /* link url */
)
- receiveMsg::voice [type = voice]
$postData = array(
/* ... base ... */
'mid' => /* voice media id */ ,
'format' => /* voice format for exp : amr, speex ... */
[ , 'txt' => /* voice recognition result */ ]
)
- receiveEvent::subscribe [type = event & event = subscribe]
$postData = array(
/* ... base ... */
'event' => /* event name */ ,
[ , 'key' => /* qrcode option value */
, 'ticket' => /* qrcode ticket */
]
)
- receiveEvent::unsubscribe [type = event & event = unsubscribe]
$postData = array(
/* ... base ... */
'event' => /* event name */
)
- receiveEvent::scan [type = event & event = scan]
$postData = array(
/* ... base ... */
'event' => /* event name */ ,
[ , 'key' => /* qrcode option value */
, 'ticket' => /* qrcode ticket */
]
)
- receiveEvent::location [type = event & event = location]
$postData = array(
/* ... base ... */
'event' => /* event name */ ,
'la' => /* Latitude */ ,
'lo' => /* Longitude */ ,
'p' => /* Precision */
)
- receiveEvent::click [type = event & event = click]
$postData = array(
/* ... base ...*/
'event' => /* event name */ ,
'key' => /* custom key */
)
- receiveAllEnd [Last Hook]
$postData = array(
'id' => /* message id */ ,
'from' => /* follower open id */ ,
'to' => /* admin OA account id */ ,
'time' => /* msg timestamp */ ,
'type' => /* message type */
) + receiveMsg OR receiveEvent
- accessCheckSuccess (without params)
- 404 (without params)
#####get xml In hook you can send response by use
echo WeChatServer::getXml4* # ...
-
Text
{String} WeChatServer::getXml4Txt( $text ); -
Image
{String} WeChatServer::getXml4ImgByMid( $mediaid ); -
Voice
{String} WeChatServer::getXml4VoiceByMid( $mediaid ); -
Video
{String} WeChatServer::getXml4VideoByMid( $mediaid, $title [, $description=$title as Default ] ); -
Music
{String} WeChatServer::getXml4MusicByUrl( $music_url, $mediaid_thumb, $title [, $description = $title as Default , $high_quailty_music_url = $music_url as Default ] ); -
Rich Message
{String} WeChatServer::getXml4RichMsgByArray( array( array( 'title' => # title 'desc' => # description 'pic' => # picture url 'url' => # article url ) [, ... ] ) );
DEMO CODE
<?PHP
include('WeChatServer.php');
function responseTxt( $postObj ){
$content = $postObj['content'];
echo WeChatServer::getXml4Txt( "You say : [$content]." );
}
$svr = new WeChatServer(
'token_in_admin.wechat.com',
array(
'receiveAllStart' => function( $postObj ){
log( $postObj['from'] );
// log who sent this msg
// if u want to send response here,
// please exit
// echo WeChatServer::getXml4Txt( 'Hey' );
// exit();
},
'receiveMsg::text' => 'responseTxt'
)
);
###WeChatClient.php
About
WeChatClient is used to set/get user-defined menu in chat, manage followers group, upload/download media file and send customer server messages.
getting start
<?PHP
include( 'WeChatClient.php' );
# If you are the user of mp.weixin.qq.com, please include WeChatClient.zh_CN.php
# include( 'WeChatClient.zh_CN.php' );
$client = new WeChatClient( 'your-appid', 'your-appsecret' );
Access Token
<?PHP
# If you need access token, you can use following:
$client->getAccessToken();
# If you need access token with expire time, use:
$tokenOnly = 0;
$client->getAccessToken( $tokenOnly );
# @return array(
# 'token' => /* access token */,
# 'expire' => /* timestamp */
# )
# access token info will be cached
# once $client->getAccessToken is called
$client->setAccessToken( $tokenInfo );
# Cached accesstoken, $tokenInfo = $client->getAccessToken( 0 );
User-defined Menu
<?PHP
# Get Menu Array or null for empty;
$client->getMenu();
# Delete Menu as you see
$client->deleteMenu();
#
$client->setMenu( $menu )
# @param $menu {Array|String}
# When use String: $menu should be Json String
# When use Array: Make sure
# 1) Your PHP Version support json_encode JSON_UNESCAPED_UNICODE
# OR 2) Don't use Unicode Chars.
Manage Followers & Group
<?PHP
$client->getUserInfoById( $userid [, $lang='en' ] );
# @return {Array} For detail
# @see http://admin.wechat.com/wiki/index.php?title=User_Profile
$client->getFollowersList( [ $next_id = '' ] );
# @return {Array} array(
# 'total' => {int},
# 'list' => array( userid1, userid2 ... )
# 'next_id' => {string}
# )
# if total length > list length, you can use
$client->getFollowersList( $next_id );
$client->createGroup( $name );
# @return {int|null} group id OR null for failure
$client->renameGroup( $groupid, $name);
# @return {boolen}
$client->moveUserById( $userid, $groupid )
# @return {boolen}
$client->getAllGroups();
# @return {Array|Null}
$client->getGroupidByUserid( $userid );
# @return {int}
Media File
<?PHP
$client->upload( $type, $file_path [, $mediaidOnly = true ] );
# @param $type {string} image | voice | video | thumb
# @return {string} When $mediaidOnly = true, return media id
# @return {Array} When $mediaidOnly = false,
# return array( 'type' =>, 'media_id' =>, 'create_at' => /* timestamp */)
$client->download( $media_id );
# @return media file binary data
Customer Server Message
<?PHP
# all the following will return {boolen}
$client->sendTextMsg( $user_id, $txt );
$client->sendImgMsg( $user_id, $media_id );
$client->sendVoice( $user_id, $media_id );
$client->sendVideo( $user_id, $media_id, $title, $description );
$client->sendMusic(
$user_id, $music_url, $thumb_media_id, $title
[, $description = $title, $high_quality_music_url = $music_url ]
);
$client->sendRichMsg(
$user_id,
array(
array(
'title' => /* article title */,
'desc' => /* description */,
'url' => /* article url */,
'thumb_url' => /* thumb url */,
)
[ , ... ]
)
);
Qrcode
<?PHP
$client->getQrcodeTicket( [ $options ] );
# @param $options {Array}
# array(
# 'scene_id' => /* default = 1*/
# 'expire' => /* default = 0 mean no limit */
# 'ticketOnly' => /* default = true */
# )
# @return {string|null} when ticketOnly = true, return ticket string
# @return {array|null} when ticketOnly = false,
# return array(
# 'ticket' => /* ... */,
# 'expire' => /* ... */
# )
WeChatClient::getQrcodeImgUrlByTicket( $ticket )
# @return {string}
WeChatClient::getQrcodeImgByTicket( $ticket )
# @return Image Binary