5分钟快速开发 API Document Download About Me

微信API for NodeJS

欢迎大家加入QQ群：172342609 《微信 API For Nodejs》专用交流群
该API文档正在撰写中。。。敬请期待！

基础支持

1 获取access_token

access_token是公众号的全局唯一票据，公众号调用各接口时都需使用access_token。正常情况下access_token有效期为7200秒，重复获取将导致上次获取的access_token失效。 由于获取access_token的api调用次数非常有限，建议开发者全局存储与更新access_token，频繁刷新access_token会导致api调用受限，影响自身业务。

请开发者注意，由于技术升级，公众平台的开发接口的access_token长度将增长，其存储至少要保留512个字符空间。此修改将在1个月后生效，请开发者尽快修改兼容。

公众号可以使用AppID和AppSecret调用本接口来获取access_token。AppID和AppSecret可在开发模式中获得（需要已经成为开发者，且帐号没有异常状态）。注意调用所有微信接口时均需使用https协议。

reflashAccessToken：刷新access_token

weixin.reflashAccessToken();
在开发环境下，一般将这行代码注释掉，不然项目每次重启都会去微信服务器重新获取access_token，而access_token每天的获取次数有限。

getAccessToken：从微信服务器获取一个新的access_token

weixin.getAccessToken(function(data) {
	var ret = JSON.parse(data);
	var access_token = ret.access_token;
	var expires_in = ret.expires_in;
});

返回说明：

正常情况下，微信会返回下述JSON数据包给公众号：

{"access_token":"ACCESS_TOKEN","expires_in":7200}

返回结果参数说明：

参数 说明
access_token 获取到的凭证
expires_in 凭证有效时间，单位：秒

错误时微信会返回错误码等信息，JSON数据包示例如下（该示例为AppID无效错误）:

{"errcode":40013,"errmsg":"invalid appid"}

2 全局返回码说明（详见微信开发者文档）

3 接口频率限制说明（详见微信开发者文档）

4 上传下载多媒体文件（TODO）

接受消息

1 接受普通消息

当普通微信用户向公众账号发消息时，微信服务器将POST消息的XML数据包到开发者填写的URL上。各消息类型的推送XML数据包结构如下。

（1）文本消息

// 监听文本消息
weixin.on('textMsg', function(data) {
	console.log('>>>>>>>>> textMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400720067',
	msgType : 'text',
	content : '文本',
	msgId : '6016046878816470340'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType text
content 文本消息内容
msgId 消息id，64位整型

（2）图片消息

// 监听图片消息
weixin.on('imageMsg', function(data) {
	console.log('>>>>>>>>> imageMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400719405',
	msgType : 'image',
	picUrl : 'http://mmbiz.qpic.cn/mmbiz/FNibvdZUiaod0RO17qicW4gtqdEjXMpD27Sic7qrRcQJJHSmoo6JxSnOCibuUDvSc8ibNZ3zVaTS3Yuib6IATaHLnIiaeg/0',
	msgId : '6016044035548120362',
	mediaId : 'b8SLXngmYMGXMNXjtMVcLGGW_BmXQbzwzTf2dbuxYEPD5EqPm_zDKI4SyIeoEbYc'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType image
picUrl 图片链接
mediaId 图片消息媒体id，可以调用多媒体文件下载接口拉取数据。
msgId 消息id，64位整型

（3）语音消息

// 监听语音消息
weixin.on('voiceMsg', function(data) {
	console.log('>>>>>>>>> voiceMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400719511',
	msgType : 'voice',
	mediaId : 'QYXeDMV2RBdPdmfBG-59jj3hEveQfVeRwfRxm0lJ-gYdE4cgDqotdjl5tmE-be0F',
	format : 'amr',
	msgId : '6016044490614112256'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 语音为voice
mediaId 语音消息媒体id，可以调用多媒体文件下载接口拉取数据。
format 语音格式，如amr，speex等
msgID 消息id，64位整型

（4）视频消息

// 监听视频消息
weixin.on('videoMsg', function(data) {
	console.log('>>>>>>>>> videoMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400719771',
	msgType : 'video',
	mediaId : '3_vygm3O4eOD-206YdWlD-2RZotkk3ATKhAzogJnYAcv2rWOGX-43mmjGAUhpgD3',
	thumbMediaId : '12qea8DjObLhIuZFeykdgAGT7AJ9M7GwYiOfIB1a_oVE2g6FTbUO4EDz1MrKykFO',
	msgId : '6016045607506150711'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 视频为video
mediaId 视频消息媒体id，可以调用多媒体文件下载接口拉取数据。
thumbMediaId 视频消息缩略图的媒体id，可以调用多媒体文件下载接口拉取数据。
msgId 消息id，64位整型

（5）地理位置消息

// 监听地理位置消息
weixin.on('locationMsg', function(data) {
	console.log('>>>>>>>>> locationMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400719863',
	msgType : 'location',
	location_X : '28.924880',
	location_Y : '121.265515',
	scale : '15',
	label : '浙江省杭州市滨江区东方郡',
	msgId : '6016046002643141948'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType location
location_X 地理位置维度
location_Y 地理位置经度
scale 地图缩放大小
label 地理位置信息
msgId 消息id，64位整型

（6）链接消息

// 监听链接消息
weixin.on('linkMsg', function(data) {
	console.log('>>>>>>>>> linkMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_9515ed00f8e0',
	fromUserName : 'oZ2t3jlm5cpXNF-y-IO0Y5PWTwzc',
	createTime : '1400762498',
	msgType : 'link',
	title : '吴晓波频道',
	description : 'http://stage.lanshizi.com/articles',
	url : 'http://stage.lanshizi.com/articles',
	msgId : '6016229118573443885'
}

参数说明：

参数 描述
toUserName 接收方微信号
fromUserName 发送方微信号，若为普通用户，则是一个OpenID
createTime 消息创建时间
msgType 消息类型，link
title 消息标题
description 消息描述
url 消息链接
msgId 消息id，64位整型

3 接收事件推送

（1） 关注/取消关注事件

用户在关注与取消关注公众号时，微信会把这个事件推送到开发者填写的URL。方便开发者给用户下发欢迎消息或者做帐号的解绑。

// 关注事件
weixin.on('subscribeEventMsg', function(data) {
	console.log('>>>>>>>>> subscribeEventMsg emit >>>>>>>>>');
	console.log(data);
});
// 取消关注事件
weixin.on('unsubscribeEventMsg', function(data) {
	console.log('>>>>>>>>> unsubscribeEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400724764',
	msgType : 'event',
	event : 'subscribe'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，subscribe(订阅)、unsubscribe(取消订阅)

（2） 扫描带参数二维码事件

用户扫描带场景值二维码时，可能推送以下两种事件：

  1. 如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者。
  2. 如果用户已经关注公众号，则微信会将带场景值扫描事件推送给开发者。

1. 用户未关注时，进行关注后的事件推送

weixin.on('subscribeEventMsg', function(data) {
	console.log('>>>>>>>>> subscribeEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例：

{ 
	ToUserName: [ 'gh_9515ed00f8e0' ],
	FromUserName: [ 'oZ2t3jhhQkQcF5p3qqItXc32CfDY' ],
	CreateTime: [ '1402060401' ],
	MsgType: [ 'event' ],
	Event: [ 'subscribe' ],
	EventKey: [ 'qrscene_123' ],
	Ticket:['gQGF8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0hYV1o5YnJsRGZCME16ck8yVm1qAAIEzZ1_UwMEAAAAAA==']
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，subscribe
eventKey 事件KEY值，qrscene_为前缀，后面为二维码的参数值
ticket 二维码的ticket，可用来换取二维码图片

2. 用户已关注时的事件推送

weixin.on("scanEventMsg", function(data) {
	console.log('>>>>>>>>> scanEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例：

{ 
	toUserName: 'gh_9515ed00f8e0',
	fromUserName: 'oZ2t3jhhQkQcF5p3qqItXc32CfDY',
	createTime: '1402061186',
	msgType: 'event',
	event: 'SCAN',
	eventKey: '123',
	ticket: 'gQGF8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0hYV1o5YnJsRGZCME16ck8yVm1qAAIEzZ1_UwMEAAAAAA=='
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，SCAN
eventKey 事件KEY值，是一个32位无符号整数，即创建二维码时的二维码scene_id
ticket 二维码的ticket，可用来换取二维码图片

（3）上报地理位置事件

用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，或在进入会话后每5秒上报一次地理位置，公众号可以在公众平台网站中修改以上设置。上报地理位置时，微信会将上报地理位置事件推送到开发者填写的URL。 

weixin.on('locationEventMsg', function(data) {
	console.log('>>>>>>>>> locationEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400724768',
	msgType : 'event',
	event : 'LOCATION',
	latitude : '28.927586',
	longitude : '121.260757',
	precision : '30.000000'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，LOCATION
latitude 地理位置纬度
longitude 地理位置经度
precision 地理位置精度

（4）自定义菜单事件

用户点击自定义菜单后，微信会把点击事件推送给开发者，请注意，点击菜单弹出子菜单，不会产生上报。

点击菜单拉取消息时的事件推送

weixin.on('clickEventMsg', function(data) {
	console.log('>>>>>>>>> clickEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400725592',
	msgType : 'event',
	event : 'CLICK',
	eventKey : 'ONE_KEY'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，CLICK
eventKey 事件KEY值，与自定义菜单接口中KEY值对应

点击菜单跳转链接时的事件推送

weixin.on('viewEventMsg', function(data) {
	console.log('>>>>>>>>> viewEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400725790',
	msgType : 'event',
	event : 'VIEW',
	eventKey : 'http://www.baidu.com/'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，VIEW
eventKey 事件KEY值，设置的跳转URL

4 接收语音识别结果

开通语音识别功能，用户每次发送语音给公众号时，微信会在推送的语音消息XML数据包中，增加一个Recongnition字段。

注：由于客户端缓存，开发者开启或者关闭语音识别功能，对新关注者立刻生效，对已关注用户需要24小时生效。开发者可以重新关注此帐号进行测试。 

weixin.on('voiceMsg', function(data) {
	console.log('>>>>>>>>> voiceMsg emit >>>>>>>>>');
	console.log(data);
	// TODO
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400726466',
	msgType : 'voice',
	mediaId : 'LJH6WzbKmSx9Nh0FVBgiGyQFM2cW7VwpFTt3r8ZNWVfoDW6yP6PkCWhPz6CuQ3om',
	format : 'amr',
	msgId : '6016074362111655936',
	recognition : '你好吗？'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 语音为voice
mediaID 语音消息媒体id，可以调用多媒体文件下载接口拉取该媒体
format 语音格式：amr
recognition 语音识别结果，UTF8编码
msgID 消息id，64位整型

发送消息

1 发送被动响应消息

对于每一个POST请求，开发者在响应包（Get）中返回特定XML结构，对该消息进行响应（现支持回复文本、图片、图文、语音、视频、音乐）。请注意，回复图片等多媒体消息时需要预先上传多媒体文件到微信服务器，只支持认证服务号。

（1）回复文本消息

示例： 

var msg = {
	toUserName : data.fromUserName,
	fromUserName : data.toUserName,
	msgType : 'text',
	content : '这是一段文本'
};
weixin.sendMsg(msg);

参数说明：（createTime属性已经默认添加，开发者不用手动添加）

参数 是否必须 描述
toUserName 是 接收方帐号（收到的OpenID）
fromUserName 是 开发者微信号
createTime 是 消息创建时间 （整型）
msgType 是 text
content 是 回复的消息内容（换行：在content中能够换行，微信客户端就支持换行显示）

（2）回复图片消息

示例： 

var msg = {
	toUserName : data.fromUserName,
	fromUserName : data.toUserName,
	msgType : 'image',
	mediaId : data.mediaId
};
weixin.sendMsg(msg);

参数说明：

参数 是否必须 说明
toUserName 是 接收方帐号（收到的OpenID）
fromUserName 是 开发者微信号
createTime 是 消息创建时间 （整型）
msgType 是 image
mediaId 是 通过上传多媒体文件，得到的id。

（3）回复语音消息

示例： 

var msg = {
	toUserName : data.fromUserName,
	fromUserName : data.toUserName,
	msgType : 'voice',
	mediaId : data.mediaId
};
weixin.sendMsg(msg);

参数说明：

参数 是否必须 说明
toUserName 是 接收方帐号（收到的OpenID）
fromUserName 是 开发者微信号
createTime 是 消息创建时间戳 （整型）
msgType 是 语音，voice
mediaId 是 通过上传多媒体文件，得到的id

（4）回复视频消息

示例： 

var msg = {
	toUserName : data.fromUserName,
	fromUserName : data.toUserName,
	msgType : 'video',
	title : '这是视频的标题',
	description : '这是视频的描述',
	mediaId : '7bTTH39M91xDI6ItEtN13bYrejJEUPWgrK5NTrqltHdOBXEHA95VFAGFxRlhalxY'
};
weixin.sendMsg(msg);

参数说明：

参数 是否必须 说明
toUserName 是 接收方帐号（收到的OpenID）
fromUserName 是 开发者微信号
createTime 是 消息创建时间 （整型）
msgType 是 video
mediaId 是 通过上传多媒体文件，得到的id
title 否 视频消息的标题
description 否 视频消息的描述

（5）回复音乐消息

示例： 

var msg = {
        toUserName : data.fromUserName,
        fromUserName : data.toUserName,
        msgType : 'music',
        title : "这是音乐标题",
        description : "这是音乐描述",
        musicUrl : '音乐Url',
        thumbMediaId : 'MhKkAXP56io9Xx5hwzuVVzwWWSFH3LTrDl65efnD9BkXAvlc1Bjn8FhEqrWRa18f'
    };
weixin.sendMsg(msg);

参数说明：

参数 是否必须 说明
toUserName 是 接收方帐号（收到的OpenID）
fromUserName 是 开发者微信号
createTime 是 消息创建时间 （整型）
msgType 是 music
title 否 音乐标题
description 否 音乐描述
musicURL 否 音乐链接
HQMusicUrl 否 高质量音乐链接，WIFI环境优先使用该链接播放音乐
thumbMediaId 是 缩略图的媒体id，通过上传多媒体文件，得到的id

（6）回复图文消息

示例： 

var articles = [];
articles[0] = {
	title : "每个Web开发者必备的9个软技能",
	description : "每个Web开发者除了精通技术，还应必备以下9个软技能：交流、倾听、适应、合作、积极的态度、有职业道德、判断/辨别、批判性思维和自负管理等",
	picUrl : "http://cms.csdnimg.cn/article/201404/01/5339fcde7d200.jpg",
	url : "http://www.csdn.net/article/2014-04-01/2819079-9-soft-skills-every-web-developer-should-master"
};
articles[1] = {
	title : "轻松打造品牌轻应用：实时Web App开发框架Clouda",
	description : "Clouda是百度历时两年共同研发的开源App技术框架，基于Node.js，简单易用，完美结合BAE，具备跨终端、云端统一、随动反馈和全实时等新一代技术能力。",
	picUrl : "http://cms.csdnimg.cn/article/201403/07/53196741f0a1d_middle.jpg",
	url : "http://www.csdn.net/article/2014-03-07/2818676-baidu-clouda"
};
var msg = {
	toUserName : data.fromUserName,
	fromUserName : data.toUserName,
	msgType : 'news',
	articles : articles
};
weixin.sendMsg(msg);

参数说明：

参数 是否必须 说明
toUserName 是 接收方帐号（收到的OpenID）
fromUserName 是 开发者微信号
createTime 是 消息创建时间 （整型）
msgType 是 news
articleCount 是 图文消息个数，限制为10条以内
articles 是 多条图文消息信息，默认第一个item为大图,注意，如果图文数超过10，则将会无响应
title 否 图文消息标题
description 否 图文消息描述
picUrl 否 图片链接，支持JPG、PNG格式，较好的效果为大图360*200，小图200*200
url 否 点击图文消息跳转链接

2 发送客服消息

当用户主动发消息给公众号的时候（包括发送信息、点击自定义菜单、订阅事件、扫描二维码事件、支付成功事件、用户维权），微信将会把消息数据推送给开发者，开发者在一段时间内（目前修改为48小时）可以调用客服消息接口，通过POST一个JSON数据包来发送消息给普通用户，在48小时内不限制发送次数。此接口主要用于客服等有人工消息处理环节的功能，方便开发者为用户提供更加优质的服务。

（1）发送文本消息

示例： 

weixin.sendCustomMsg({
	toUserName : 'OPENID',
	msgType : 'text',
	content : "这是文本内容"
}, function(data) {
	console.log(data);
});

如果发送成功，第二个参数回调函数data返回结果： 

{ errcode: 0, errmsg: 'ok' }

参数说明：

参数 是否必须 说明
toUserName 是 普通用户openid
msgType 是 消息类型，text
content 是 文本消息内容（如果在文本内容中需要换行，使用\n）

（2）发送图片消息

示例： 

weixin.sendCustomMsg({
	toUserName: 'OPENID',
	msgType: 'image',
	mediaId: 'MEDIA_ID'
}, function(data) {
	console.log(data);
});

如果发送成功，第二个参数回调函数data返回结果： 

{ errcode: 0, errmsg: 'ok' }

参数说明：

参数 是否必须 说明
toUserName 是 普通用户openid
msgType 是 消息类型，image
mediaId 是 发送的图片的媒体ID

（3）发送语音消息

示例： 

weixin.sendCustomMsg({
	toUserName : 'OPENID',
	msgType : 'voice',
	mediaId : 'MEDIA_ID'
}, function(data) {
	console.log(data);
});

如果发送成功，第二个参数回调函数data返回结果： 

{ errcode: 0, errmsg: 'ok' }

参数说明：

参数 是否必须 说明
toUserName 是 普通用户openid
msgType 是 消息类型，voice
mediaId 是 发送的语音的媒体ID

（4）发送视频消息

示例： 

weixin.sendCustomMsg({
	toUserName : 'OPENID',
	msgType : 'video',
	title: 'This is video title.',
	description: 'This is video description.',
	mediaId : 'MEDIA_ID'
}, function(data) {
	console.log(data);
});

如果发送成功，第二个参数回调函数data返回结果： 

{ errcode: 0, errmsg: 'ok' }

参数说明：

参数 是否必须 说明
toUserName 是 普通用户openid
msgType 是 消息类型，video
mediaId 是 发送的视频的媒体ID
title 否 视频消息的标题
description 否 视频消息的描述

（5）发送音乐消息

示例：

weixin.sendCustomMsg({
	toUserName : 'OPENID',
	msgType : 'music',
	title : "MUSIC_TITLE",
	description : "MUSIC_DESCRIPTION",
	musicUrl : "MUSIC_URL",
	HQMusicUrl : "HQ_MUSIC_URL",
	thumbMediaId : "THUMB_MEDIA_ID"
}, function(data) {
	console.log(data);
});

如果发送成功，第二个参数回调函数data返回结果： 

{ errcode: 0, errmsg: 'ok' }

参数说明：

参数 是否必须 说明
toUserName 是 普通用户openid
msgType 是 消息类型，music
title 否 音乐标题
description 否 音乐描述
musicUrl 是 音乐链接
HQMusicUrl 是 高品质音乐链接，wifi环境优先使用该链接播放音乐
thumbMediaId 是 缩略图的媒体ID

（6）发送图文消息

图文消息条数限制在10条以内，注意，如果图文数超过10，则将会无响应。

示例：

weixin.sendCustomMsg({
	toUserName : 'OPENID',
	msgType : 'news',

	articles : [{
		title : "每个Web开发者必备的9个软技能",
		description : "每个Web开发者除了精通技术，还应必备以下9个软技能：交流、倾听、适应、合作、积极的态度、有职业道德、判断/辨别、批判性思维和自负管理等",
		picurl : "http://cms.csdnimg.cn/article/201404/01/5339fcde7d200.jpg",
		url : "http://www.csdn.net/article/2014-04-01/2819079-9-soft-skills-every-web-developer-should-master"
	}, {
		title : "轻松打造品牌轻应用：实时Web App开发框架Clouda",
		description : "Clouda是百度历时两年共同研发的开源App技术框架，基于Node.js，简单易用，完美结合BAE，具备跨终端、云端统一、随动反馈和全实时等新一代技术能力。",
		picurl : "http://cms.csdnimg.cn/article/201403/07/53196741f0a1d_middle.jpg",
		url : "http://www.csdn.net/article/2014-03-07/2818676-baidu-clouda"
	}]

}, function(data) {
	console.log(data);
});

如果发送成功，第二个参数回调函数data返回结果： 

{ errcode: 0, errmsg: 'ok' }

参数说明：

参数 是否必须 说明
toUserName 是 普通用户openid
msgType 是 消息类型，news
title 否 标题
description 否 描述
url 否 点击后跳转的链接
picurl 否 图文消息的图片链接，支持JPG、PNG格式，较好的效果为大图640*320，小图80*80

3 高级群发接口

在公众平台网站上，为订阅号提供了每天一条的群发权限，为服务号提供每月（自然月）4条的群发权限。而对于某些具备开发能力的公众号运营者， 可以通过高级群发接口，实现更灵活的群发能力。

请注意：

  1. 该接口暂时仅提供给已微信认证的服务号
  2. 虽然开发者使用高级群发接口的每日调用限制为100次，但是用户每月只能接收4条，请小心测试
  3. 无论在公众平台网站上，还是使用接口群发，用户每月只能接收4条群发消息，多于4条的群发将对该用户发送失败。

（1）上传图文消息素材

示例：

weixin.uploadNews({
	articles : [{
		"thumb_media_id" : "K1frURlJ6aauzYO40c-qjl3ztRerMnH3QV-eVfEFPMgriLQckA1FMEfx8pBD18Ys",
		"author" : "图文消息的作者",
		"title" : "每个Web开发者必备的9个软技能",
		"content_source_url" : "http://www.csdn.net/article/2014-04-01/2819079-9-soft-skills-every-web-developer-should-master",
		"content" : "图文消息页面的内容，支持HTML标签",
		"digest" : "图文消息的描述",
		"show_cover_pic" : "1"
	}, {
		"thumb_media_id" : "K1frURlJ6aauzYO40c-qjl3ztRerMnH3QV-eVfEFPMgriLQckA1FMEfx8pBD18Ys",
		"author" : "图文消息的作者",
		"title" : "轻松打造品牌轻应用：实时Web App开发框架Clouda",
		"content_source_url" : "http://www.csdn.net/article/2014-03-07/2818676-baidu-clouda",
		"content" : "图文消息页面的内容，支持HTML标签",
		"digest" : "图文消息的描述",
		"show_cover_pic" : "0"
	}]
}, function(data) {
	console.log(data);
});

参数说明：

参数 是否必须 说明
articles 是 图文消息，一个图文消息支持1到10条图文
thumb_media_id 是 图文消息缩略图的media_id，可以在基础支持-上传多媒体文件接口中获得
author 否 图文消息的作者
title 是 图文消息的标题
content_source_url 否 在图文消息页面点击“阅读原文”后的页面
content 是 图文消息页面的内容，支持HTML标签
digest 否 图文消息的描述
show_cover_pic 否 是否显示封面，1为显示，0为不显示

返回数据示例（正确时的JSON返回结果）：

{ 
	type: 'news',
	media_id: 'pKZBTA-E7ZLT5NcL9Ec2kr7xUYuWUhKgt_Ly4WXnjREEjmRAQ3ydRtNTWHqsssbG',
	created_at: 1402101120
}

参数说明：

参数 说明
type 媒体文件类型，分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb），次数为news，即图文消息
media_id 媒体文件/图文消息上传后获取的唯一标识
created_at 媒体文件上传时间

错误时微信会返回错误码等信息，请根据错误码查询错误信息: 全局返回码说明

（2）根据分组进行群发（TODO）

（3）根据OpenID列表群发（TODO）

图文消息

weixin.sendByOpenIdList({
	touser: [
		"OPENID1",
		"OPENID2"
	],
	msgType: 'news',
	mediaId: '-NyQKU1aM-Ka1YVcxfmzAUwXeXQ_Er1eN0T6Bl71HP4BmYlPuVPWtOIEQSvnyqlW'
});

文本消息

weixin.sendByOpenIdList({
	touser: [
		"OPENID1",
		"OPENID2"
	],
	msgType: 'text',
	content: '文本内容'
});

语音消息

weixin.sendByOpenIdList({
	touser: [
		"OPENID1",
		"OPENID2"
	],
	msgType: 'voice',
	mediaId: '-NyQKU1aM-Ka1YVcxfmzAUwXeXQ_Er1eN0T6Bl71HP4BmYlPuVPWtOIEQSvnyqlW'
});

图片消息

weixin.sendByOpenIdList({
	touser: [
		"OPENID1",
		"OPENID2"
	],
	msgType: 'image',
	mediaId: 'IMAGE_MEDIAID'
});

（4）删除群发（TODO）

（5）事件推送群发结果（TODO）

用户管理

1 分组管理接口

开发者可以使用接口，对公众平台的分组进行查询、创建、修改操作，也可以使用接口在需要时移动用户到某个分组。

（1）创建分组

一个公众账号，最多支持创建500个分组。

示例：

weixin.createGroup({
	name: "私人定制"
}, function(data) {
	console.log(data);
});

参数说明：

参数 说明
name 分组名字（30个字符以内）

返回说明 正常时的返回JSON数据包示例：

{
	"group":{
		"id":102,
		"name":"testname"
	}
}

返回结果参数说明：

参数 说明
id 分组id，由微信分配
name 分组名字，UTF8编码

错误时的JSON数据包示例（该示例为AppID无效错误）

{"errcode":40013,"errmsg":"invalid appid"}

（2）查询所有分组

示例：

weixin.getGroups(function(data) {
	console.log(data);
});

返回说明 正常时的返回JSON数据包示例：

{
	"groups" : [{
		"id" : 0,
		"name" : "未分组",
		"count" : 1
	}, {
		"id" : 1,
		"name" : "黑名单",
		"count" : 0
	}, {
		"id" : 2,
		"name" : "星标组",
		"count" : 0
	}, {
		"id" : 100,
		"name" : "test",
		"count" : 0
	}, {
		"id" : 102,
		"name" : "testname",
		"count" : 0
	}]
}

参数说明：

参数 说明
groups 公众平台分组信息列表
id 分组id，由微信分配
name 分组名字，UTF8编码
count 分组内用户数量

错误时的JSON数据包示例（该示例为AppID无效错误）：

{"errcode":40013,"errmsg":"invalid appid"}

（3）查询用户所在分组

通过用户的OpenID查询其所在的GroupID。

示例：

weixin.getGroupId('openid', function(data) {
	console.log(data);
});

参数说明：

参数 说明
openid 用户的OpenID

返回说明 正常时的返回JSON数据包示例：

{"groupid":0}

返回结果参数说明：

参数 说明
groupid 用户所属的groupid

（4）修改分组名

示例：

weixin.updateGroup({
	id: 102,
	name: '私人定制'
}, function(data) {
	console.log(data);
});

参数说明：

参数 说明
id 分组id，由微信分配
name 分组名字（30个字符以内）

返回说明 正常时的返回JSON数据包示例：

{"errcode": 0, "errmsg": "ok"}

错误时的JSON数据包示例（该示例为AppID无效错误）：

{"errcode":40013,"errmsg":"invalid appid"}

（5）移动用户分组

示例：

weixin.updateMemberGroup({
	openid: 'openid',
	toGroupid: 'to_groupid'
}, function(data) {
	console.log(data);
});

参数说明：

参数 说明
openid 用户唯一标识符
to_groupid 分组id

返回说明 正常时的返回JSON数据包示例：

{"errcode": 0, "errmsg": "ok"}

错误时的JSON数据包示例（该示例为AppID无效错误）：

{"errcode":40013,"errmsg":"invalid appid"}

2 获取用户基本信息

在关注者与公众号产生消息交互后，公众号可获得关注者的OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的。 对于不同公众号，同一用户的openid不同）。公众号可通过本接口来根据OpenID获取用户基本信息，包括昵称、头像、性别、所在城市、语言和关注时间

开发者可通过OpenID来获取用户基本信息。请使用https协议。

示例：

weixin.getUserInfo({
	openid: 'openid'
}, function(data) {
	console.log(data);
});

参数说明：

参数 是否必须 说明
openid 是 普通用户的标识，对当前公众号唯一
lang 否 返回国家地区语言版本，zh_CN 简体，zh_TW 繁体，en 英语

正常情况下，微信会返回下述JSON数据包给公众号：

{
	"subscribe" : 1,
	"openid" : "o6_bmjrPTlm6_2sgVt7hMZOPfL2M",
	"nickname" : "Band",
	"sex" : 1,
	"language" : "zh_CN",
	"city" : "广州",
	"province" : "广东",
	"country" : "中国",
	"headimgurl" : "http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/0",
	"subscribe_time" : 1382694957
}

参数说明：

参数 说明
subscribe 用户是否订阅该公众号标识，值为0时，代表此用户没有关注该公众号，拉取不到其余信息。
openid 用户的标识，对当前公众号唯一
nickname 用户的昵称
sex 用户的性别，值为1时是男性，值为2时是女性，值为0时是未知
city 用户所在城市
country 用户所在国家
province 用户所在省份
language 用户的语言，简体中文为zh_CN
headimgurl 用户头像，最后一个数值代表正方形头像大小（有0、46、64、96、132数值可选，0代表640*640正方形头像），用户没有头像时该项为空
subscribe_time 用户关注时间，为时间戳。如果用户曾多次关注，则取最后关注时间

错误时微信会返回错误码等信息，JSON数据包示例如下（该示例为AppID无效错误）:

{"errcode":40013,"errmsg":"invalid appid"}

3 获取关注者列表

公众号可通过本接口来获取帐号的关注者列表，关注者列表由一串OpenID（加密后的微信号，每个用户对每个公众号的OpenID是唯一的）组成。 一次拉取调用最多拉取10000个关注者的OpenID，可以通过多次拉取的方式来满足需求。

示例：

weixin.getUsers('', function(data) {
	console.log(data);
});

参数说明：

参数 是否必须 说明
next_openid 是 第一个拉取的OPENID，不填默认从头开始拉取

正确时返回JSON数据包：

{
	"total" : 2,
	"count" : 2,
	"data" : {
		"openid" : ["OPENID1", "OPENID2"]
	},
	"next_openid" : "NEXT_OPENID"
}

参数说明：

参数 说明
total 关注该公众账号的总用户数
count 拉取的OPENID个数，最大值为10000
data 列表数据，OPENID的列表
next_openid 拉取列表的后一个用户的OPENID

错误时返回JSON数据包（示例为无效AppID错误）：

{"errcode":40013,"errmsg":"invalid appid"}

附：关注者数量超过10000时

当公众号关注者数量超过10000时，可通过填写next_openid的值，从而多次拉取列表的方式来满足需求。 具体而言，就是在调用接口时，将上一次调用得到的返回中的next_openid值，作为下一次调用中的next_openid值。

示例如下：

// 第一次调用
weixin.getUsers('', function(data) {
	console.log(data);
});
// 返回结果
{
	"total" : 23000,
	"count" : 10000,
	"data" : {
		"openid" : ["OPENID1", "OPENID2", "...", "OPENID10000"]
	},
	"next_openid" : "NEXT_OPENID1"
}
// 第二次调用
weixin.getUsers("NEXT_OPENID1", function(data) {
	console.log(data);
});
// 返回结果
{
	"total" : 23000,
	"count" : 10000,
	"data" : {
		"openid" : ["OPENID10001", "OPENID10002", "...", "OPENID20000"]
	},
	"next_openid" : "NEXT_OPENID2"
}
// 第三次调用
weixin.getUsers("NEXT_OPENID2", function(data) {
	console.log(data);
});
// 返回结果
{
	"total" : 23000,
	"count" : 3000,
	"data" : {
		"openid" : ["OPENID20001", "OPENID20002", "...", "OPENID23000"]
	},
	"next_openid" : " "
}

4 获取用户地理位置

开通了上报地理位置接口的公众号，用户在关注后进入公众号会话时，会弹框让用户确认是否允许公众号使用其地理位置。弹框只在关注后出现一次，用户以后可以在公众号详情页面进行操作。

用户同意上报地理位置后，每次进入公众号会话时，都会在进入时上报地理位置，上报地理位置以推送XML数据包到开发者填写的URL来实现。

详见：上报地理位置事件

5 网页授权获取用户基本信息（TODO）

6 网页获取用户网络状态（JS接口）

为了方便开发者根据用户的网络状态来提供不同质量的服务，公众号可以在公众号内部的网页中使用JavaScript代码调用来获取网络状态。

接口调用代码（JavaScript）

WeixinJSBridge.invoke('getNetworkType', {}, function(e) {
	WeixinJSBridge.log(e.err_msg);
});

获取用户网络状态的返回值如下：

network_type:wifi wifi网络
network_type:edge 非wifi,包含3G/2G
network_type:fail 网络断开连接

多客服功能（TODO）

1 将消息转发到多客服

2 获取客服聊天记录

3 PC客户端自定义插件接口

自定义菜单

目前自定义菜单最多包括3个一级菜单，每个一级菜单最多包含5个二级菜单。一级菜单最多4个汉字，二级菜单最多7个汉字，多出来的部分将会以“...”代替。请注意，创建自定义菜单后，由于微信客户端缓存，需要24小时微信客户端才会展现出来。建议测试时可以尝试取消关注公众账号后再次关注，则可以看到创建后的效果。

目前自定义菜单接口可实现两种类型按钮，如下：

click：
用户点击click类型按钮后，微信服务器会通过消息接口推送消息类型为event 的结构给开发者（参考消息接口指南），并且带上按钮中开发者填写的key值，开发者可以通过自定义的key值与用户进行交互；
view：
用户点击view类型按钮后，微信客户端将会打开开发者在按钮中填写的url值 （即网页链接），达到打开网页的目的，建议与网页授权获取用户基本信息接口结合，获得用户的登入个人信息。

1 自定义菜单创建接口

示例：

var menu = {
	"button" : [{
		"type" : "click",
		"name" : "今日歌曲",
		"key" : "V1001_TODAY_MUSIC"
	}, {
		"type" : "click",
		"name" : "歌手简介",
		"key" : "V1001_TODAY_SINGER"
	}, {
		"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"
		}]
	}]
};

weixin.createMenu(menu, function(data) {
	console.log(data);
});

创建成功时回调函数data返回结果：

{ errcode: 0, errmsg: 'ok' }

错误时的返回JSON数据包如下（示例为无效菜单名长度）：

{"errcode":40018,"errmsg":"invalid button name size"}

参数说明：

参数 是否必须 说明
button 是 一级菜单数组，个数应为1~3个
sub_button 否 二级菜单数组，个数应为1~5个
type 是 菜单的响应动作类型，目前有click、view两种类型
name 是 菜单标题，不超过16个字节，子菜单不超过40个字节
key click类型必须 菜单KEY值，用于消息接口推送，不超过128字节
url view类型必须 网页链接，用户点击菜单可打开链接，不超过256字节

2 自定义菜单查询接口

使用接口创建自定义菜单后，开发者还可使用接口查询自定义菜单的结构。 

weixin.getMenu(function(data) {
	console.log(data)
	// TODO
});

如果菜单存在，返回结果示例： 

{
    "button": [
        {
            "type": "click", 
            "name": "今日歌曲", 
            "key": "V1001_TODAY_MUSIC"
        }, 
        {
            "type": "click", 
            "name": "歌手简介", 
            "key": "V1001_TODAY_SINGER"
        }, 
        {
            "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"
                }
            ]
        }
    ]
}

如果菜单不存在，返回结果： 

{ errcode: 46003, errmsg: 'menu no exist' }

3 自定义菜单删除接口

使用接口创建自定义菜单后，开发者还可使用接口删除当前使用的自定义菜单。 

weixin.deleteMenu(function(data) {
	console.log(data);
});

如果删除成功，返回结果 

{ errcode: 0, errmsg: 'ok' }

4 自定义菜单事件推送

用户点击自定义菜单后，微信会把点击事件推送给开发者，请注意，点击菜单弹出子菜单，不会产生上报。

点击菜单拉取消息时的事件推送

weixin.on('clickEventMsg', function(data) {
	console.log('>>>>>>>>> clickEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400725592',
	msgType : 'event',
	event : 'CLICK',
	eventKey : 'ONE_KEY'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，CLICK
eventKey 事件KEY值，与自定义菜单接口中KEY值对应

点击菜单跳转链接时的事件推送

weixin.on('viewEventMsg', function(data) {
	console.log('>>>>>>>>> viewEventMsg emit >>>>>>>>>');
	console.log(data);
});

data参数示例： 

{
	toUserName : 'gh_6716c73fdcbe',
	fromUserName : 'ojim5txO8ivc0Ff2LKW1nlUJ9hM4',
	createTime : '1400725790',
	msgType : 'event',
	event : 'VIEW',
	eventKey : 'http://www.baidu.com/'
}

参数说明：

参数 描述
toUserName 开发者微信号
fromUserName 发送方帐号（一个OpenID）
createTime 消息创建时间 （整型）
msgType 消息类型，event
event 事件类型，VIEW
eventKey 事件KEY值，设置的跳转URL

推广支持

1 生成带参数的二维码

为了满足用户渠道推广分析的需要，公众平台提供了生成带参数二维码的接口。使用该接口可以获得多个带不同场景值的二维码，用户扫描后，公众号可以接收到事件推送。

目前有2种类型的二维码，分别是临时二维码和永久二维码，前者有过期时间，最大为1800秒，但能够生成较多数量，后者无过期时间，数量较少（目前参数只支持1--100000）。两种二维码分别适用于帐号绑定、用户来源统计等场景。

用户扫描带场景值二维码时，可能推送以下两种事件：

  1. 如果用户还未关注公众号，则用户可以关注公众号，关注后微信会将带场景值关注事件推送给开发者。
  2. 如果用户已经关注公众号，在用户扫描后会自动进入会话，微信也会将带场景值扫描事件推送给开发者。

获取带参数的二维码的过程包括两步，首先创建二维码ticket，然后凭借ticket到指定URL换取二维码。

（1）创建二维码ticket

临时二维码请求示例：

var qrcode = {
	"expire_seconds" : 1800,
	"action_name" : "QR_SCENE",
	"action_info" : {
		"scene" : {
			"scene_id" : 123
		}
	}
}
weixin.createQrcode(qrcode, function(data) {
	console.log(data);
});

如果创建成功返回结果：

{
	ticket: 'gQEA8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0MzWFh4bExtcWZEUS1DNFhsMXVqAAIEaZ1_UwMECAcAAA==',
	expire_seconds: 1800
}

永久二维码请求示例：

var qrcode = {
	"action_name" : "QR_LIMIT_SCENE",
	"action_info" : {
		"scene" : {
			"scene_id" : 123
		}
	}
};
weixin.createQrcode(qrcode, function(data) {
	console.log(data);
});

如果创建成功返回结果：

{ ticket: 'gQGF8DoAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL0hYV1o5YnJsRGZCME16ck8yVm1qAAIEzZ1_UwMEAAAAAA==' }

请求参数说明：

参数 说明
expire_seconds 该二维码有效时间，以秒为单位。 最大不超过1800。
action_name 二维码类型，QR_SCENE为临时,QR_LIMIT_SCENE为永久
action_info 二维码详细信息
scene_id 场景值ID，临时二维码时为32位非0整型，永久二维码时最大值为100000（目前参数只支持1--100000）

返回结果参数说明：

参数 说明
ticket 获取的二维码ticket，凭借此ticket可以在有效时间内换取二维码。
expire_seconds 二维码的有效时间，以秒为单位。最大不超过1800。

（2）通过ticket换取二维码

获取二维码ticket后，开发者可用ticket换取二维码图片。请注意，本接口无须登录态即可调用。

请求说明：
HTTP GET请求（请使用https协议）
https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET
提醒：TICKET记得进行UrlEncode
返回说明：

ticket正确情况下，http 返回码是200，是一张图片，可以直接展示或者下载。

错误情况下（如ticket非法）返回HTTP错误码404。

Fork me on GitHub