API.md · sjdy521/Mojo-Weixin

本文档包含的API是针对单帐号的，如果需要多账号统一管理API，请移步到Controller-API

API列表汇总

API地址	可用状态	API说明
微信基础信息获取相关
/openwx/get_user_info	running	获取登录用户数据
/openwx/get_friend_info	running	获取好友数据
/openwx/get_group_info	running	获取群组数据
/openwx/get_group_basic_info	running	获取群组基本数据
/openwx/get_avatar	running	获取用户或群组头像
数据搜索相关
/openwx/search_friend	running	搜索好友对象
/openwx/search_group	running	搜索群组对象
聊天控制相关
/openwx/create_group	running	创建群组
/openwx/invite_friend	running	邀请好友加入群组
/openwx/make_friend	running	向指定的群成员发送好友请求
/openwx/set_group_displayname	running	设置群组的显示名称
/openwx/kick_group_member	running	移除群组成员
/openwx/set_markname	running	修改好友或群成员备注名称
/openwx/stick	running	设置或取消群组、好友置顶
/openwx/accept_friend_request	running	接受好友验证申请
发送消息相关
/openwx/send_friend_message	running	发送好友消息
/openwx/send_group_message	running	发送群组消息
/openwx/revoke_message	running	撤回消息
/openwx/upload_media	running	上传媒体文件，获取media_id, 用于稍后发送
/openwx/consult	running	发送消息给好友并返回好友的回复主要用途是转发微软小冰的智能回复
事件（消息）获取相关
自定义事件（消息）上报地址	scaning updating running	将产生的事件通过HTTP POST请求发送到指定的地址可用于上报扫描二维码事件、新增好友事件、接收消息事件等
/openwx/check_event	running	采用HTTP GET请求长轮询机制获取事件（消息） API只能工作在非阻塞模式下，功能受限不如POST上报的方式获取的信息全面
客户端控制相关
/openwx/get_client_info	running	获取程序运行信息
/openwx/stop_client	running	终止程序运行

首先启动一个API Server：

可以直接把如下代码保存成一个源码文件(必须使用UTF8编码)，使用 perl 解释器来运行

    #!/usr/bin/env perl
    use Mojo::Weixin;
    my ($host,$port,$post_api,$poll_api);
    
    $host = "0.0.0.0"; #发送消息接口监听地址，没有特殊需要请不要修改
    $port = 3000;      #发送消息接口监听端口，修改为自己希望监听的端口
    #$post_api = 'http://xxxx';  #接收到的消息上报接口，如果不需要接收消息上报，可以删除或注释此行
    #$poll_api = 'http://xxxx';  #心跳请求地址，默认注释或删掉此行，更多说明参见下文 心跳请求 相关文档
    
    my $client = Mojo::Weixin->new(log_level=>"info",http_debug=>0);
    $client->load("ShowMsg");
    $client->load("Openwx",data=>{
        listen => [{host=>$host,port=>$port}],       #可选，发送消息api监听端口
        post_api=> $post_api,                        #可选，接收消息或事件的上报地址
        post_event => 1,                             #可选，是否上报事件，为了向后兼容性，默认值为0
        post_media_data => 0,                        #可选，是否上报经过base64编码的图片原始数据，默认值为1
        post_event_list => ['login','stop','state_change','input_qrcode'], #可选，上报事件列表，更多说明参考下文 事件上报 相关文档
        poll_api  => $poll_api,                      #可选，心跳请求地址，默认不启用
        poll_interval   => 5,                        #可选，长轮询请求间隔，默认5s
    });
    $client->run();

API是通过加载Openwx插件的形式提供的，上述代码保存成 xxxx.pl 文件

然后使用 perl 来运行，就会完成微信登录并在本机产生一个监听指定地址端口的 http server

$ perl xxxx.pl

客户端数据文件介绍

微信客户端在运行过程中会产生很多的文件，这些文件默认情况下会保存在系统的临时目录下

你可以通过在启动脚本的 Mojo::Weixin->new()中增加 tmpdir 参数来修改这个临时目录的位置，例如：

Mojo::Weixin->new(log_level=>"info",http_debug=>0,tmpdir=>'C:\tmpdir\') #请确保目录已经存在并有访问权限

更多自定义参数参见Mojo::Weixin->new参数说明

mojo_weixin_cookie_{客户端名称}.dat #客户端的cookie文件，用于短时间内重复登录免扫码
mojo_weixin_pid_{客户端名称}.pid    #记录客户端进程号，防止相同微信帐号产生多个重复的客户端实例
mojo_weixin_qrcode_{客户端名称}.jpg #客户端登录二维码文件
mojo_weixin_state_{客户端名称}.json #客户端的运行状态相关的信息，json格式，实时更新

一般情况下你不需要关心这些文件保存在哪里，有什么作用，这些文件也会在程序退出的时候自动进行清理

客户端运行状态介绍

客户端运行过程中会在多种状态之间切换，有很多状态是阻塞的，相当于一个死循环，需要达到一定条件才能跳出死循环

单帐号模式采用的是单进程异步机制，API全部都是工作在非阻塞模式下，因此在阻塞的状态中API（发送消息/接收消息等）都是暂时无法工作的

比如：在登录扫描的状态下，还没有完成登录，是无法调用API去发送消息，请求会收不到任何响应

了解客户端这些状态的差异，有助于帮助你合理正确的调用API

状态	模式	状态说明
init	-	客户端创建后的初始状态
loading	blocking	客户端加载插件
scaning	blocking	等待手机扫码
confirming	blocking	等待手机点击[登录]按钮
updating	blocking	更新个人、好友、群组信息
running	non-blocking	客户端运行中，可以正常接收、发送消息，相关API可以工作
stop	-	客户端停止运行

客户端状态的一般迁移过程：

init => loading => scaning => confirming => updating => running => stop

客户端状态实时更新到 mojo_weixin_state_{客户端名称}.json 文件中，可以通过读取这个文件来获取上述相关状态的变化

也可以通过客户端事件上报中的 state_change 事件来获取客户端当前所处的状态

多账号模式下也可以通过Controller提供的 /openwx/check_client 接口查询到这个状态

（/openwx/check_client接口实际上就是返回 mojo_weixin_state_{客户端名称}.json 文件中的数据）

关于心跳请求的说明

可能用于内网穿透、客户端存活检测、客户端信息收集等方面，期待你发掘更多利用价值

设置 Openwx插件 中的参数 poll_api和poll_interval，会使得客户端在处于 running 状态时，自发的去请求poll_api地址

期望的是，这个请求会长时间阻塞等待，服务端不返回任何数据（服务端逻辑需要你自己去实现）

服务端响应结果或者请求超时断开后，会间隔poll_interval 秒后继续重复发起请求，如此往复

如果你的程序是部署在内网环境，而又希望通过外网的服务器去调用内网的api，实现发送消息等功能

当外网的服务端希望内网的客户端程序调用某个api接口时，比如希望内网的客户端调用/openwx/send_friend_message接口给指定的好友发消息

服务端通过HTTP协议的302 Location返回需要访问的完整api地址

http://127.0.0.1:3000/openwx/send_friend_message?id=xxx&content=xxxx

客户端收到302的响应后会自动请求跳转后的地址（客户端自己请求自己本机127.0.0.1的api地址）实现发送消息

> GET /poll_url HTTP/1.1
> User-Agent: curl/7.29.0
> Host: www.example.com
> Accept: */*
> 
< HTTP/1.1 302 Found
< Location: http://127.0.0.1:3000/openwx/send_friend_message?id=filehelper&content=hello
< Date: Tue, 08 Nov 2016 14:00:15 GMT
< Content-Length: 0

获取用户数据

API	获取用户数据
uri	/openwx/get_user_info
请求方法	GET\|POST
请求参数	无
调用示例	http://127.0.0.1:3000/openwx/get_user_info

返回数据:

    {
        "account": "xxx",
        "name": "xxx",
        "markname": "",
        "sex": "none",
        "display": "",
        "city": "",
        "signature": "帮助解决微信支付中遇到的困难，收集关于微信支付的建议反馈。",
        "province": "广东",
        "id": "@efc5f86c30df4b9c80e98ac428e0e257",
        "uid": 123,
        "displayname": "xxx"
    },

获取好友数据

API	获取好友数据
uri	/openwx/get_friend_info
请求方法	GET\|POST
请求参数	无
调用示例	http://127.0.0.1:3000/openwx/get_friend_info
返回JSON数组:

[#好友数组
    {#第一个好友
        "account": "wxzhifu",
        "name": "微信支付",
        "category":"公众号",
        "markname": "",
        "sex": "none",
        "display": "",
        "city": "",
        "signature": "帮助解决微信支付中遇到的困难，收集关于微信支付的建议反馈。",
        "province": "广东",
        "id": "@efc5f86c30df4b9c80e98ac428e0e257",
        "uid": 123456,
        "displayname": "微信支付"
    },
    {#第二个好友
        "account": "",
        "name": "小灰",
        "category":"好友",
        "markname": "",
        "sex": "none",
        "display": "",
        "city": "深圳",
        "signature": "小灰灰的个性签名",
        "province": "广东",
        "id": "@00227d73fa6b8326f69bca419db7a05c",
        "uid": 123456,
        "displayname": "小灰"
    }
]

获取群组数据

API	获取群组数据
uri	/openwx/get_group_info
请求方法	GET\|POST
请求参数	无
调用示例	http://127.0.0.1:3000/openwx/get_group_info
返回JSON数组:

[#群数组
    {#第一个群
        "name": "",
        "id": "@@dadadadada",
        "uid": 123456,
        "displayname": "xxxx"
        "member": [#群成员数组
            {#第一个群成员
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@adadada",
                "uid": 123456,
                "displayname": "xxx"
            },
            {#第二个群成员
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@dadada",
                "uid": 123456,
                "displayname": "xxx"
            },
        ],

    },
    {#第二个群组
        "name": "xxxx",
        "id": "@@dadadada",
        "uid": 123456,
        "displayname": "xxx"
        "member": [
            {
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@dadadada",
                "uid": 123456,
                "displayname": "xxx"
            },
            {
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@dadadada",
                "displayname": "xxx"
            },
        ],

    },
]

获取群组基本数据

API	获取群组基本数据（不包含群成员）
uri	/openwx/get_group_basic_info
请求方法	GET\|POST
请求参数	无
调用示例	http://127.0.0.1:3000/openwx/get_group_basic_info

发送好友消息

API	发送好友消息
uri	/openwx/send_friend_message
请求方法	GET\|POST
请求参数	id: 好友的id account: 好友的帐号 displayname: 好友显示名称 markname: 好友备注名称 content:发送的文本内容(中文需要做urlencode) media_id:媒体id(发送媒体消息返回的媒体id，需要做urlencode) media_path:媒体路径(可以是文件路径或url，需要做urlencode) async: 0或1,可选,是否异步发送消息
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/send_friend_message?id=xxxx&content=hello http://127.0.0.1:3000/openwx/send_friend_message?markname=xxx&content=%e4%bd%a0%e5%a5%bd http://127.0.0.1:3000/openwx/send_friend_message?id=xxx&media_path=https%3a%2f%2fss0.bdstatic.com%2flogo.png http://127.0.0.1:3000/openwx/send_friend_message?id=xxx&media_id=%40crypt_1eb0ba44_cb3de736e6ccd5ae8%3a3
特殊处理：id=@all 表示群发消息给所有的好友

####文本消息返回JSON数据格式:

{"status":"发送成功","msg_id":23910327,"code":0} #code为 0 表示发送成功

####媒体消息返回的JSON数据格式：

{"status":"发送成功","msg_id":23910327,"media_id":"@crypt_1eb0ba44_cb3de736e6ccd5ae8:3","code":0} #code为 0 表示发送成功

注意：相同媒体消息转发给多个好友或群组时，可以直接拿之前发送消息返回的media_id作为发送对象，这样可以避免重复上传文件，提高发送效率

如果不关心发送消息是否成功，可以采用异步发送的方式，调用接口马上返回:

http://127.0.0.1:3000/openwx/send_group_message?id=xxxx&content=hello&async=1

发送群组消息

API	发送群组消息
uri	/openwx/send_group_message
请求方法	GET\|POST
请求参数	id: 群组的id displayname: 群组显示名称 content:发送的文本内容(中文需要做urlencode) media_id:媒体id(发送媒体消息返回的媒体id，需要做urlencode) media_path:媒体路径(可以是文件路径或url，需要做urlencode) async: 0或1,可选,是否异步发送消息
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/send_group_message?id=xxxx&content=hello http://127.0.0.1:3000/openwx/send_group_message?displayname=xxx&content=%e4%bd%a0%e5%a5%bd http://127.0.0.1:3000/openwx/send_group_message?id=xxx&media_path=https%3a%2f%2fss0.bdstatic.com%2flogo.png http://127.0.0.1:3000/openwx/send_group_message?displayname=xxx&media_path=https%3a%2f%2fss0.bdstatic.com%2flogo.png http://127.0.0.1:3000/openwx/send_group_message?id=xxx&media_id=%40crypt_1eb0ba44_cb3de736e6ccd5ae8%3a3

####文本消息返回JSON数据格式:

{"status":"发送成功","msg_id":23910327,"code":0} #code为 0 表示发送成功

####媒体消息返回的JSON数据格式：

{"status":"发送成功","msg_id":23910327,"media_id":"@crypt_1eb0ba44_cb3de736e6ccd5ae8:3","code":0} #code为 0 表示发送成功

注意：相同媒体消息转发给多个好友或群组时，可以直接拿之前发送消息返回的media_id作为发送对象，这样可以避免重复上传文件，提高发送效率

如果不关心发送消息是否成功，可以采用异步发送的方式，调用接口马上返回:

http://127.0.0.1:3000/openwx/send_group_message?id=xxxx&content=hello&async=1

撤回消息

API	撤回消息
uri	/openwx/revoke_message
请求方法	GET\|POST
请求参数	id: 消息的id
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/revoke_message?id=xxxx

查询事件消息

API	采用HTTP GET请求长轮询获取事件（消息）
uri	/openwx/check_event
请求方法	GET
数据格式	application/json

接口返回JSON数组的形式，数组中的每个元素是一个JSON格式消息，格式和自定义事件消息上报地址完全一样

程序最大保留最近20条信息记录，可以通过插件参数check_event_list_max_size进行自定义

$client->load("Openwx",data=>{ 
    check_event_list_max_size=>100,
});

采用长轮询机制，没有事件（消息）时，请求会挂起等待30s即断开，需要客户端再次重复发起请求

API只能工作在非阻塞模式下,功能受限，不如POST上报的方式获取的信息全面，目前仅支持获取:

发送消息、接收消息以及如下一部分事件:

new_group,new_friend,new_group_member,lose_group,lose_friend,lose_group_member,friend_request

* Connected to 127.1 (127.0.0.1) port 3000 (#0)
> GET /openwx/check_event? HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.1:3000
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
< Date: Tue, 22 Nov 2016 04:11:36 GMT
< Content-Length: 16405
< Server: Mojolicious (Perl)

[ 
   {
    "class":"send",
    "content":" hello world",
    "format":"text",
    "from":"none",
    "id":"2647366348175870091",
    "post_type":"send_message",
    "receiver":"文件传输助手",
    "receiver_account":"",
    "receiver_id":"filehelper",
    "receiver_name":"文件传输助手",
    "receiver_uid":"",
    "sender":"小灰",
    "sender_markname":"xxx",
    "sender_category":"系统帐号", #系统帐号|公众号|好友
    "time":"1479787946",
    "type":"friend_message"
    }
]

没有消息等待超时后，会返回一个空的JSON数组，客户端需要再次发起请求

* Connected to 127.1 (127.0.0.1) port 3000 (#0)
> GET /openwx/check_event? HTTP/1.1
> User-Agent: curl/7.29.0
> Host: 127.1:3000
> Accept: */*
> 
< HTTP/1.1 200 OK
< Content-Type: application/json;charset=UTF-8
< Date: Tue, 22 Nov 2016 04:11:36 GMT
< Content-Length: 16405
< Server: Mojolicious (Perl)

[]

自定义事件消息上报地址

API	自定义事件（消息）上报地址
uri	自定义任意支持http协议的url
请求方法	POST
数据格式	application/json

需要加载Openwx插件时通过 post_api 参数来指定上报地址:

$client->load("Openwx",data=>{
    listen => [{host=>xxx,port=>xxx}],           #可选，发送消息api监听端口
    post_api=> 'http://127.0.0.1:3000/post_api', #可选，接收消息或事件的上报地址
    post_event => 1,                             #可选，是否上报事件，为了向后兼容性，默认值为1
    post_stdout => 0,                            #可选，上报数据是否打印到stdout，适合管道交互信息方式，默认0
    post_media_data => 1,                        #可选，是否上报经过base64编码的图片原始数据，默认值为1
    post_event_list => ['login','stop','state_change','input_qrcode'], #可选，上报事件列表
});

首先要了解消息一些关键属性信息：

上报或拉取的JSON数据的类型中的post_type属性用于区分上报的数据是消息类的数据还是其他事件

关键属性	取值	说明
post_type	receive_message send_message event	接收消息发送消息其他事件

发送接收消息（post_type为receive_message或send_message时)的关键属性信息：

关键属性	取值	说明
id	-	消息的id
type	friend_message group_message group_notice	消息类型细分: 好友消息群消息群提示消息
class	send recv	表明是发送消息还是接收消息
format	text media app revoke card	消息的格式：文本消息媒体（图片、视频、语音）应用分享撤回消息名片分享
sender_id	-	消息发送者id（注意不是所有的消息类型都存在这个属性）
receiver_id	-	消息接收者id（注意不是所有的消息类型都存在这个属性）
group_id	-	消息相关的群组id（注意不是所有的消息类型都存在这个属性）

接收消息上报

当接收到消息时，会把消息通过JSON格式数据POST到该接口

普通好友消息或群消息上报

connect to 127.0.0.1 port 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{   "receiver":"小灰",
    "time":"1442542632",
    "content":"测试一下",
    "class":"recv",
    "sender_id":"@2372835507",
    "sender_uid": 123456,
    "receiver_id":"@4072574066",
    "receiver_name": "小灰",
    "receiver_uid": 123456,
    "group":"PERL学习交流",
    "group_id":"@@2617047292",
    "group_uid": 123456,
    "group_name": "PERL学习交流",
    "sender":"灰灰",
    "sender_name": "灰灰",
    "id":"10856",
    "uid": 123456,
    "type":"group_message",
    "format": "text",
    "post_type": "receive_message"
}

群提示消息上报

connect to 127.0.0.1 port 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{   "receiver":"小灰",
    "time":"1442542632",
    "content":"你邀请灰太狼加入了群聊",
    "class":"recv",
    "receiver_id":"@4072574066",
    "receiver_name":"小灰",
    "receiver_uid":123456,
    "group":"PERL学习交流",
    "group_name":"PERL学习交流",
    "group_id":"@@2617047292",
    "id":"10856",
    "type":"group_notice",
    "format": "text",
    "post_type": "receive_message"
}

发送消息上报（包括从手机或其他设备上发送的消息）

发送的消息会通过JSON格式数据POST到该接口

connect to 127.0.0.1 port 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{   "receiver":"小灰",
    "time":"1442542632",
    "content":"测试一下",
    "class":"send",
    "sender_id":"@2372835507",
    "receiver_id":"@4072574066",
    "receiver_uid":123456,
    "receiver_name":"小灰",
    "group":"PERL学习交流",
    "group_id":"@@2617047292",
    "group_name":"PERL学习交流",
    "group_uid":123456,
    "sender":"灰灰",
    "sender_uid":123456,
    "sender_name":"灰灰",
    "id":"10856",
    "type":"group_message",
    "format": "text",
    "post_type": "send_message"
}

图片消息上报

{   "receiver":"小灰",
    "time":"1442542632",
    "content":"[media](\/tmp\/mojo_weixin_media_Ja9l.jpg)",
    "media_path": "\/tmp\/mojo_weixin_media_Ja9l.jpg",
    "media_id": "2273934420223351581",
    "media_mime":"image\/jpg",
    "media_name": "mojo_weixin_media_Ja9l.jpg",
    "media_size": "1234567",
    "media_mtime": "1462763788",
    "media_ext": "jpg",
    "media_data": "pXA88GiUcCncmxUgt2JbJxRVu2\/1j0U2xJH\/\/2Q==\n", #对图片原始二进制数据，使用base64默认方式编码
    "class":"recv",
    "sender_id":"@2372835507",
    "receiver_id":"@4072574066",
    "receiver_uid":"",
    "receiver_name":"",
    "group":"PERL学习交流",
    "group_id":"@@2617047292",
    "group_name":"",
    "group_uid":"",
    "sender":"灰灰",
    "sender_name":"",
    "sender_uid":"",
    "id":"10856",
    "type":"group_message",
    "format": "media",
    "post_type": "receive_message"
}

应用分享消息上报

{   "receiver":"小灰",
    "receiver_uid":"",
    "receiver_name":"",
    "time":"1442542632",
    "content":"[应用分享]标题：饿了么给你发红包",
    "app_name":"饿了么",
    "app_id":"wx123456",
    "app_title":"饿了么给你发红包",
    "app_desc":"撩拨你的深夜味蕾，第2份半价！"
    "app_url":"https:\/\/h.ele.me\/hongbao", 
    "class":"recv",
    "sender_id":"@2372835507",
    "receiver_id":"@4072574066",
    "group":"PERL学习交流",
    "group_id":"@@2617047292",
    "group_uid":"",
    "group_name":"",
    "sender":"灰灰",
    "sender_uid":"",
    "sender_name":"",
    "id":"10856",
    "type":"group_message",
    "format": "app",
    "post_type": "receive_message"
}

撤回消息上报

{
    "time":"1442542632",
    "content":"[撤回消息](你撤回了一条消息)",
    "revoke_id":"2513410439052032973", #被用户撤回的消息id
    "class":"send",
    "sender_id":"@2372835507",
    "sender_uid": 123456,
    "group":"PERL学习交流",
    "group_id":"@@2617047292",
    "group_uid": 123456,
    "group_name": "PERL学习交流",
    "sender":"灰灰",
    "sender_name": "灰灰",
    "id":"10856",
    "uid": 123456,
    "type":"group_message",
    "format": "revoke",
    "post_type": "send_message"
}

名片消息上报

{
    'card_avatar' => 'http://wx.qlogo.cn/mmhead/ver_1/k99g2RHrEeib9KMhGmXZGSIGDjgnmiaX2acT2wl04so2ibsq8ysVPRkRRNQyRLmUVptBpcHt6lvUZym5JgOSd4fug/0',
    'card_id' => '@bc9b2967ec91315f4dd47e5e3d0e33ee'
    'card_account' => '',
    'card_city' => '中国',
    'card_province' => '上海',
    'card_name' => 'xxx',
    'card_sex' => 'male',
    'sender_id' => '@b2c5637bb8e158a5a29eca00ac9ed0f9',
    'receiver_id' => 'filehelper',
    'id' => '5604497552796809997',
    'format' => 'card',
    'type' => 'friend_message',
    'class' => 'send',
    'time' => '1482985638',
}

一般情况下，post_api接口返回的响应内容可以是随意，会被忽略，上报完不做其他操作如果post_api接口返回的数据类型是 text/json 或者 application/json，并且json格式形式如下:

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json;charset=UTF-8
Date: Mon, 29 Feb 2016 05:53:31 GMT
Content-Length: 27
Server: Mojolicious (Perl)

{"reply":"你好","code":0} #要回复消息，必须包含reply的属性，其他属性有无并不重要

则表示希望通过post_api响应的内容来直接回复该消息，会直接对上报的该条消息进行回复，回复的内容为 "你好"

如果想要对消息回复图片内容，可以使用 media 参数，举例:


{"media":"http://www.baidu.com/test.jpg","code":0}                          #使用url地址形式
{"media":"/tmp/test.jpg","code":0}                                          #使用本地文件地址形式
{"reply":"给你发个图片","media":"http://www.baidu.com/test.jpg","code":0}   #文本和图片同时发送

其他非消息类事件上报

当事件发生时，会把事件相关信息上报到指定的接口，当前支持上报的事件包括：

事件名称	事件说明	上报参数列表
login	客户端登录	1：表示经过二维码扫描，好友等id可能会发生变化 0：表示未经过二维码扫描，好友等id不会发生变化 -1：表示登录异常，第二个参数包含异常原因
stop	客户端停止	客户端停止运行，程序退出
state_change	客户端状态变化	旧的状态，新的状态（参见客户端状态说明）
input_qrcode	扫描二维码	二维码本地保存路径，二维码原始数据的base64编码
new_group	新加入群聊	对应群对象
new_friend	新增好友	对应好友对象
new_group_member	新增群聊成员	对应成员对象，对应的群对象
lose_group	退出群聊	对应群对象
lose_friend	删除好友	对应好友对象
lose_group_member	成员退出群聊	对应成员对象，对应的群对象
group_property_change	群聊属性变化	群对象，属性，原始值，更新值
group_member_property_change	成员属性变化	成员对象，属性，原始值，更新值
friend_property_change	好友属性变化	好友对象，属性，原始值，更新值
user_property_change	帐号属性变化	账户对象，属性，原始值，更新值
update_user	初始化(更新)帐号信息	帐号对象
update_friend	初始化(更新)好友信息	好友对象列表
update_group	初始化(更新)群组信息	群组对象列表
friend_request	好友验证申请

可以在Openwx插件中，通过 post_event_list 参数来指定上报的事件

默认 post_event_list => ['login','stop','state_change','input_qrcode','new_group','new_friend','new_group_member','lose_group','lose_friend','lose_group_member','friend_request']

需要注意：属性变化类的事件可能触发的会比较频繁，导致产生大量的上报请求，默认不开启

初始化(更新）帐号信息事件

connect to 127.0.0.1 port 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{
    "post_type":"event",
    "event":"update_user",
    "params":[
        {
            "account": "xxx",
            "name": "xxx",
            "markname": "",
            "sex": "none",
            "display": "",
            "city": "",
            "signature": "帮助解决微信支付中遇到的困难，收集关于微信支付的建议反馈。",
            "province": "广东",
            "id": "@efc5f86c30df4b9c80e98ac428e0e257",
            "uid": 123,
            "displayname": "xxx"
       }
    ],

}

新增好友事件举例

connect to 127.0.0.1 port 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{
    "post_type":"event",
    "event":"new_friend",
    "params":[
        {
            "account":"ms-xiaoice",
            "name":"小冰",
            "markname":"",
            "sex":"0",
            "city":"海淀",
            "signature":"我是人工智能微软小冰，我回来了，吼吼~~",
            "province":"北京",
            "displayname":"小冰",
            "id":"@75b9db5ae52c87361d1800eaaf307f4d"
        }
    ],

}

扫描二维码事件举例

connect to 127.0.0.1 port 3000
POST /post_api
Accept: */*
Content-Length: xxx
Content-Type: application/json

{
    "post_type":"event",
    "event":"input_qrcode",
    "params":[
        {
            "\/tmp\/qrcode.jpg", #二维码本地路径
            "\/9j\/4AAQSkZJRgABAQAAAQABAAD\...UUUUUUUUUUUV\/\/Z\n", #二维码原始数据经过base64默认方式编码
        }
    ],

}

好友验证申请事件

{
    "post_type":"event",
    "event":"friend_request",
    "params":[
        "@75ab55c416dbe3a", #申请者的id
        "小灰", #申请者的显示名称
        "小灰请求加你为好友", #申请者的验证信息
        "v2_85c00f264eed801fee7@stranger" #接受好友验证申请时需要用到的ticket
    ]
}

可以通过上报的json数组中的post_type来区分上报的数据是消息还是其他事件

好友问答

API	发送消息给好友并等待好友回答
uri	/openwx/consult
请求方法	GET\|POST
请求参数	id: 好友的id account: 好友的帐号 displayname: 好友显示名称 markname: 好友备注名称 timeout：等待回复的时间，默认30秒 media_path:媒体路径(可以是文件路径或url，需要做urlencode)
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/consult?account=ms-xiaoice&content=haha http://127.0.0.1:3000/openwx/consult?account=ms-xiaoice&media_path=%2ftmp%2fhello.jpg

主要应用场景是把小冰(微信帐号ms-xiaoice)的智能回复封装成接口，给小冰发好友消息前，你需要先关注小冰的公众号

GET /openwx/consult?account=ms-xiaoice&content=haha HTTP/1.1
User-Agent: curl/7.29.0
Host: 127.0.0.1:3000
Accept: */*

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Date: Tue, 01 Mar 2016 07:25:11 GMT
Content-Length: 94
Server: Mojolicious (Perl)

{"reply":"哈哈，有什么事情","status":"发送成功","msg_id":"2683625013724723712","code":0}

超时失败时的返回结果：

{"reply":null,"reply_status":"reply timeout","status":"发送成功","msg_id":1456817344504,"code":0}

搜索好友对象

API	搜索好友对象
uri	/openwx/search_friend
请求方法	GET\|POST
请求参数	好友对象的任意属性，中文需要做urlencode，比如： id: 好友的id account: 好友的帐号 displayname: 好友显示名称 markname: 好友备注名称
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/search_friend?id=xxxxxx http://127.0.0.1:3000/openwx/search_friend?province=xxxxxx&city=xxxx
返回JSON数组:

[#好友数组
    {#第一个好友
        "account": "wxzhifu",
        "name": "微信支付",
        "markname": "",
        "sex": "none",
        "display": "",
        "city": "",
        "signature": "帮助解决微信支付中遇到的困难，收集关于微信支付的建议反馈。",
        "province": "广东",
        "id": "@efc5f86c30df4b9c80e98ac428e0e257",
        "displayname": "微信支付"
    },
    {#第二个好友
        "account": "",
        "name": "财付通",
        "markname": "",
        "sex": "none",
        "display": "",
        "city": "深圳",
        "signature": "会支付 会生活",
        "province": "广东",
        "id": "@00227d73fa6b8326f69bca419db7a05c",
        "displayname": "财付通"
    }
]

搜索群组对象

API	搜索群组对象
uri	/openwx/search_group
请求方法	GET\|POST
请求参数	群对象的任意属性，中文需要做urlencode，比如： id: 群组的id displayname: 群组的显示名称
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/search_group?id=xxxxxx http://127.0.0.1:3000/openwx/search_group?displayname=xxxxx
返回JSON数组:

[#群数组
    {#第一个群
        "name": "",
        "id": "@@dadadadada",
        "displayname": "xxxx"
        "member": [#群成员数组
            {#第一个群成员
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@adadada",
                "displayname": "xxx"
            },
            {#第二个群成员
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@dadada",
                "displayname": "xxx"
            },
        ],

    },
    {#第二个群组
        "name": "xxxx",
        "id": "@@dadadada",
        "displayname": "xxx"
        "member": [
            {
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@dadadada",
                "displayname": "xxx"
            },
            {
                "account": "",
                "name": "xxx",
                "markname": "",
                "sex": "none",
                "display": "",
                "city": "",
                "signature": "",
                "province": "",
                "id": "@dadadada",
                "displayname": "xxx"
            },
        ],

    },
]

创建群组

API	创建群组
uri	/openwx/create_group
请求方法	GET\|POST
请求参数	friends: 好友的id（多个好友id用逗号分割） displayname: 可选，群组的显示名称
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/create_group?displayname=xxxxxx&friends=xxxx,xxxx
返回JSON结果:

{
    "group_id":"@@a6588c3bfa8b5458ffc8d758ae851d3f40f396c2ebc970d006a365fdbb5299e1", #创建的群组id
    "status":"success",
    "code":0  #创建成功状态码为0，失败为非0
}

邀请好友加入群组

API	邀请好友加入群组
uri	/openwx/invite_friend
请求方法	GET\|POST
请求参数	friends: 好友的id（多个好友id用逗号分割） id: 群组对象的id displayname: 群组的显示名称
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/invite_friend?id=xxxxxx&friends=xxxx,xxxx http://127.0.0.1:3000/openwx/invite_friend?displayname=xxxxxx&friends=xxxx,xxxx
返回JSON结果:

{
    "status":"success",
    "code":0  #成功状态码为0，失败为非0
}

移除群组成员

API	移除群组成员
uri	/openwx/kick_group_member
请求方法	GET\|POST
请求参数	members: 成员的id（多个成员id用逗号分割） id: 群组的id displayname: 群组的显示名称
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/kick_group_member?id=xxxxxx&members=xxxx,xxxx http://127.0.0.1:3000/openwx/kick_group_member?displayname=xxxxxx&members=xxxx,xxxx
返回JSON结果:

{
    "status":"success",
    "code":0  #成功状态码为0，失败为非0
}

修改好友或群成员备注名称

API	修改好友或群成员备注名称（修改群成员备注的功能疑似被官方屏蔽）
uri	/openwx/set_markname
请求方法	GET\|POST
请求参数	id: 好友或群成员的id account: 好友的帐号 displayname: 好友当前显示名称 markname: 好友当前备注名称 new_markname:设置的新备注名称 (参数中包含中文需要做urlencode)
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/set_markname?id=xxxxxx&new_markname=xxxx http://127.0.0.1:3000/openwx/set_markname?account=xxxxxx&new_markname=xxxx http://127.0.0.1:3000/openwx/set_markname?id=xxxxxx&group_id=xxxx&new_markname=xxxx

注意：修改群成员备注的功能疑似被官方屏蔽，api调用即使返回成功可能也没有真正的生效，建议暂时不要使用

返回JSON结果:

{
    "status":"success",
    "code":0  #成功状态码为0，失败为非0
}

设置或取消聊天置顶

API	设置或取消群组、好友置顶
uri	/openwx/stick
请求方法	GET\|POST
请求参数	id: 群组或好友的id op: 1表示置顶,0表示取消置顶
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/stick?id=xxxxxx&op=1 http://127.0.0.1:3000/openwx/stick?id=xxxxxx&op=0

返回JSON结果:

{
    "status":"success",
    "code":0  #成功状态码为0，失败为非0
}

设置群组的显示名称

API	设置群组的显示名称
uri	/openwx/set_group_displayname
请求方法	GET\|POST
请求参数	id: 群组的id displayname: 群组当前显示名称 new_displayname:设置的新显示名称 (参数中包含中文需要做urlencode)
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/set_group_displayname?id=xxxxxx&new_displayname=xxxx
返回JSON结果:

{
    "status":"success",
    "code":0  #成功状态码为0，失败为非0
}

向指定的群成员发送好友请求

API	向指定的群成员发送好友请求
uri	/openwx/make_friend
请求方法	GET\|POST
请求参数	id: 群成员的id verify:好友请求的附加信息 (参数中包含中文需要做urlencode)
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/make_friend?id=xxxxxx&verify=hello
返回JSON结果:

{
    "status":"success",
    "code":0  #成功状态码为0，失败为非0
}

获取用户或群组头像

API	获取用户或群组头像
uri	/openwx/get_avatar
请求方法	GET\|POST
请求参数	id: 用户或群组的id group_id: 群组id（获取群成员头像时需要用到,但群成员因为经常获取不到地址可能导致无法获取头像）
数据格式	image/jpg、image/png
调用示例	获取好友或群组头像: http://127.0.0.1:3000/openwx/get_avatar?id=xxxxxx 获取群成员头像:http://127.0.0.1:3000/openwx/get_avatar?id=xxxxxx&group_id=xxxxx

返回图片原始数据:

GET /openwx/get_avatar?id=xxxxx HTTP/1.1
User-Agent: curl/7.29.0
Host: 127.0.0.1:3000
Accept: */*

HTTP/1.1 200 OK
Content-Type: image/jpg
Date: Tue, 09 Aug 2016 01:49:14 GMT
Content-Length: 1104
Server: Mojolicious (Perl)

获取程序运行信息

API	获取进程运行信息
uri	/openwx/get_client_info
请求方法	GET\|POST
请求参数	无
调用示例	http://127.0.0.1:3000/openwx/get_client_info

返回JSON结果:

{
    "code":0,
    "account":"default",
    "log_encoding":null,
    "log_level":"debug",
    "log_path":null,
    "os":"linux",
    "pid":15497,
    "runtime":3096,
    "starttime":1475135588,
    "status":"success",
    "http_debug":"0",
    "version":"1.2.0"
 }

终止程序运行

API	终止程序运行
uri	/openwx/stop_client
请求方法	GET\|POST
请求参数	无
调用示例	http://127.0.0.1:3000/openwx/stop_client

返回JSON结果:

{
    "code":0,
    "account":"default",
    "pid":15972,
    "runtime":30,
    "starttime":1475136637,
    "status":"success, client(15972) will stop in 3 seconds"
}

上传媒体文件

API	上传媒体文件，获取media_id, 用于稍后发送
uri	/openwx/upload_media
请求方法	GET\|POST
请求参数	media_path: 媒体的路径，可以是本地路径或url地址
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/upload_media?media_path=%2ftmp%2ftest.mp4

返回JSON结果:

{
    "media_ext":"mp4",
    "media_id":"@crypt_5e8967c8_e637847b7d0b00xxxxxxcb82:43",
    "media_mime":"video\/mp4",
    "media_mtime":1470650887,
    "media_name":"\/tmp\/test.mp4",
    "media_path":"\/tmp\/test.mp4",
    "media_size":66947
}

接受好友验证申请

API	接受好友验证申请
uri	/openwx/accept_friend_request
请求方法	GET\|POST
请求参数	id: 申请者id（frient_request事件中会提供） displayname：申请者显示名称（frient_request事件中会提供,中文需要urlencode） ticket：接受申请需要的ticket（frient_request事件中会提供）
数据格式	application/x-www-form-urlencoded
调用示例	http://127.0.0.1:3000/openwx/accept_friend_request?id=xxx&displayname=%85%c0%0f%2b&ticket=xxx

返回JSON结果:

{
    "code": 0,
    "status": "success",
    "id": "xxx",
    "displayname": "xxx",
    "ticket": "xxx"
}

sjdy521 / Mojo-Weixin .gitee-modal { width: 500px !important; }

本文档包含的API是针对单帐号的，如果需要多账号统一管理API，请移步到Controller-API

API列表汇总

首先启动一个API Server：

客户端数据文件介绍

客户端运行状态介绍

关于心跳请求的说明

获取用户数据

获取好友数据

获取群组数据

获取群组基本数据

发送好友消息

发送群组消息

撤回消息

查询事件消息

自定义事件消息上报地址

接收消息上报

群提示消息上报

发送消息上报（包括从手机或其他设备上发送的消息）

图片消息上报

应用分享消息上报

撤回消息上报

名片消息上报

其他非消息类事件上报

好友问答

搜索好友对象

搜索群组对象

创建群组

邀请好友加入群组

移除群组成员

修改好友或群成员备注名称

设置或取消聊天置顶

设置群组的显示名称

向指定的群成员发送好友请求

获取用户或群组头像

获取程序运行信息

终止程序运行

上传媒体文件

接受好友验证申请

简介

发行版

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

近期动态

搜索帮助

sjdy521 / Mojo-Weixin