wechat-enterprise Documentation

api_common: API索引

API
getLatestToken
mixin

API

根据appid和appsecret创建API的构造函数。

如需跨进程跨机器进行操作Wechat API（依赖access token），access token需要进行全局维护
使用策略如下：

调用用户传入的获取token的异步方法，获得token之后使用
使用appid/appsecret获取token。并调用用户传入的保存token方法保存

Examples:

var API = require('wechat').API;
var api = new API('appid', 'secret', 'agentid');

以上即可满足单进程使用。
当多进程时，token需要全局维护，以下为保存token的接口。

var api = new API('corpid', 'secret', 'agentid', function (callback) {
  // 传入一个获取全局token的方法
  fs.readFile('access_token.txt', 'utf8', function (err, txt) {
    if (err) {return callback(err);}
    callback(null, JSON.parse(txt));
  });
}, function (token, callback) {
  // 请将token存储到全局，跨进程、跨机器级别的全局，比如写到数据库、redis等
  // 这样才能在cluster模式及多机情况下使用，以下为写入到文件的示例
  fs.writeFile('access_token.txt', JSON.stringify(token), callback);
});

函数	API()		API
参数	corpid(String)	在公众平台上申请得到的corpid
参数	corpsecret(String)	在公众平台上申请得到的app secret
参数	agentid(String)	企业应用的id
参数	getToken(Function)	可选的。获取全局token对象的方法，多进程模式部署时需在意
参数	saveToken(Function)	可选的。保存全局token对象的方法，多进程模式部署时需在意

getLatestToken

获取最新的token。

如果还没有请求过token，则发起获取Token请求。
如果请求过，则调用getToken从获取之前保存的token

Examples:

api.getLatestToken(callback);

Callback:

err, 获取access token出现异常时的异常对象
token, 获取的token

方法	API.prototype.getLatestToken()		getLatestToken
参数	callback(Function)	回调函数

mixin

用于支持对象合并。将对象合并到API.prototype上，使得能够支持扩展
Examples:

// 媒体管理（上传、下载）
API.mixin(require('./lib/api_media'));

方法	API.mixin()	API	mixin
参数	obj(Object)	要合并的对象

createDepartment

创建部门
详细请看：http://qydev.weixin.qq.com/wiki/index.php?title=管理部门

Examples:

api.createDepartment(name, opts, callback);

Opts:

parentid, 父部门id，根部门id为1
order，在父部门中的次序。从1开始，数字越大排序越靠后

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
 "errcode": 0,
 "errmsg": "created",
 "id": 2
}

方法	exports.createDepartment()	exports	createDepartment
参数	name(String)	部门名字
参数	opts(Object)	选项
参数	callback(Function)	回调函数

updateDepartment

更新部门

Examples:

var opts = {name: 'new name', parentid: 1, order: 5};
api.updateDepartment(id, opts, callback);

Opts:

name, 新的部门名字。可选
parentid, 父部门id，根部门id为1。可选
order，在父部门中的次序。从1开始，数字越大排序越靠后。可选，默认为1

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.updateDepartment()	exports	updateDepartment
参数	id(Number)	部门ID
参数	opts(Object)	选项
参数	callback(Function)	回调函数

deleteDepartment

删除部门

Examples:

api.deleteDepartment(id, callback);
api.deleteDepartment([id1, id2], callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.deleteDepartment()	exports	deleteDepartment
参数	id(Number,Array)	部门ID
参数	callback(Function)	回调函数

getDepartments

查看所有部门

Examples:

api.getDepartments(callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
 "errcode": 0,
 "errmsg": "ok",
 "department": [
   {
     "id": 1,
     "name": "广州研发中心",
     "parentid": 0
   },
   {
     "id": 2
     "name": "邮箱产品部",
     "parentid": 1
   }
 ]
}

方法	exports.getDepartments()	exports	getDepartments
参数	callback(Function)	回调函数

api_media: API索引

uploadMedia
getMedia

uploadMedia

上传多媒体文件，分别有图片（image）、语音（voice）、视频（video）和普通文件（file）
详情请见：http://qydev.weixin.qq.com/wiki/index.php?title=上传媒体文件
Examples:

api.uploadMedia('filepath', type, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{"type":"image","media_id":"0000001","created_at":123456789}

Shortcut:

exports.uploadImage(filepath, callback);
exports.uploadVoice(filepath, callback);
exports.uploadVideo(filepath, callback);
exports.uploadFile(filepath, callback);

方法	exports.uploadMedia()	exports	uploadMedia
参数	filepath(String)	文件路径
参数	type(String)	媒体类型，可用值有image、voice、video、file
参数	callback(Function)	回调函数

getMedia

根据媒体ID获取媒体内容
详情请见：http://qydev.weixin.qq.com/wiki/index.php?title=获取媒体文件
Examples:

api.getMedia('media_id', callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的文件Buffer对象
res, HTTP响应对象

方法	exports.getMedia()	exports	getMedia
参数	mediaId(String)	媒体文件的ID
参数	callback(Function)	回调函数

api_menu: API索引

createMenu
getMenu
removeMenu

createMenu

创建自定义菜单
详细请看：http://qydev.weixin.qq.com/wiki/index.php?title=创建应用菜单

Menu:

{
 "button":[
   {
     "type":"click",
     "name":"今日歌曲",
     "key":"V1001_TODAY_MUSIC"
   },
   {
     "name":"菜单",
     "sub_button":[
       {
         "type":"view",
         "name":"搜索",
         "url":"http://www.soso.com/"
       },
       {
         "type":"click",
         "name":"赞一下我们",
         "key":"V1001_GOOD"
       }]
     }]
   }
 ]
}

Examples:

api.createMenu(menu, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.createMenu()	exports	createMenu
参数	menu(Object)	菜单对象
参数	callback(Function)	回调函数

getMenu

获取菜单
详细请看：http://qydev.weixin.qq.com/wiki/index.php?title=获取菜单列表

Examples:

api.getMenu(callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

// 结果示例
{
 "menu": {
   "button":[
     {"type":"click","name":"今日歌曲","key":"V1001_TODAY_MUSIC","sub_button":[]},
     {"type":"click","name":"歌手简介","key":"V1001_TODAY_SINGER","sub_button":[]},
     {"name":"菜单","sub_button":[
       {"type":"view","name":"搜索","url":"http://www.soso.com/","sub_button":[]},
       {"type":"view","name":"视频","url":"http://v.qq.com/","sub_button":[]},
       {"type":"click","name":"赞一下我们","key":"V1001_GOOD","sub_button":[]}]
     }
   ]
 }
}

方法	exports.getMenu()	exports	getMenu
参数	callback(Function)	回调函数

removeMenu

删除自定义菜单
详细请看：http://mp.weixin.qq.com/wiki/index.php?title=自定义菜单删除接口
Examples:

api.removeMenu(callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.removeMenu()	exports	removeMenu
参数	callback(Function)	回调函数

api_message: API索引

send

send

发送消息分别有图片（image）、语音（voice）、视频（video）和缩略图（thumb）
详细请看：http://qydev.weixin.qq.com/wiki/index.php?title=发送接口说明
Examples:

api.send(to, message, callback);

To:

{
 "touser": "UserID1|UserID2|UserID3",
 "toparty": " PartyID1 | PartyID2 ",
 "totag": " TagID1 | TagID2 "
}

Message:
文本消息：

{
 "msgtype": "text",
 "text": {
   "content": "Holiday Request For Pony(http://xxxxx)"
 },
 "safe":"0"
}

图片消息：

{
 "msgtype": "image",
 "image": {
   "media_id": "MEDIA_ID"
 },
 "safe":"0"
}

图片消息：

{
 "msgtype": "image",
 "image": {
   "media_id": "MEDIA_ID"
 },
 "safe":"0"
}

语音消息：

{
 "msgtype": "voice",
 "voice": {
   "media_id": "MEDIA_ID"
 },
 "safe":"0"
}

视频消息：

{
 "msgtype": "video",
 "video": {
   "media_id": "MEDIA_ID"
   "title": "Title",
   "description": "Description"
 },
 "safe":"0"
}

文件消息：

{
 "msgtype": "file",
 "file": {
   "media_id": "MEDIA_ID"
 },
 "safe":"0"
}

图文消息：

{
 "msgtype": "news",
 "news": {
   "articles":[
     {
       "title": "Title",
       "description": "Description",
       "url": "URL",
       "picurl": "PIC_URL",
     },
     {
       "title": "Title",
       "description": "Description",
       "url": "URL",
       "picurl": "PIC_URL",
     }
   ]
 },
 "safe":"0"
}

MP消息：

{
 "msgtype": "mpnews",
 "mpnews": {
   "articles":[
     {
       "thumb_media_id": "id",
       "author": "Author",
       "content_source_url": "URL",
       "content": "Content"
       "digest": "Digest description",
       "show_cover_pic": "0"
     },
     {
       "thumb_media_id": "id",
       "author": "Author",
       "content_source_url": "URL",
       "content": "Content"
       "digest": "Digest description",
       "show_cover_pic": "0"
     }
   ],
   "media_id": "id"
 },
 "safe":"0"
}

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
 "errcode": 0,
 "errmsg": "ok",
 "invaliduser": "UserID1",
 "invalidparty":"PartyID1",
 "invalidtag":"TagID1"
}

方法	exports.send()	exports	send
参数	to(Object)	接受消息的用户
参数	message(Object)	消息对象
参数	callback(Function)	回调函数

api_tag: API索引

createTag
updateTagName
deleteTag
getTagUsers
addTagUsers
deleteTagUsers

createTag

创建标签

详细请看：http://qydev.weixin.qq.com/wiki/index.php?title=管理标签
Examples:

api.createTag(name, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
 "errcode": 0,
 "errmsg": "created",
 "tagid": "1"
}

方法	exports.createTag()	exports	createTag
参数	name(String)	标签名字
参数	callback(Function)	回调函数

updateTagName

更新标签名字

Examples:

api.updateTagName(id, name, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.updateTagName()	exports	updateTagName
参数	id(String)	标签ID
参数	name(String)	标签名称。最长64个字符
参数	callback(Function)	回调函数

deleteTag

删除标签

Examples:

api.deleteTag(id, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.deleteTag()	exports	deleteTag
参数	id(Number)	标签ID
参数	callback(Function)	回调函数

getTagUsers

获取标签成员

Examples:

api.getTagUsers(id, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
  "errcode": 0,
  "errmsg": "ok",
  "userlist": [
    {
        "userid": "zhangsan",
        "name": "李四"
    }
  ]
}

方法	exports.getTagUsers()	exports	getTagUsers
参数	id(Number)	标签ID
参数	callback(Function)	回调函数

addTagUsers

增加标签成员

Examples:

var userIdList = ['id1', 'id2'];
api.addTagUsers(id, userIdList, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:
a)正确时返回

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

b)若部分userid非法，则返回

{
  "errcode": 0,
  "errmsg": "invalid userlist failed"
  "invalidlist"："usr1|usr2|usr"
}

c)当包含的userid全部非法时返回

{
  "errcode": 40031,
  "errmsg": "all list invalid"
}

方法	exports.addTagUsers()	exports	addTagUsers
参数	id(Number)	标签ID
参数	userIdList(Array)	用户ID列表
参数	callback(Function)	回调函数

deleteTagUsers

删除标签成员

Examples:

var userIdList = ['id1', 'id2'];
api.deleteTagUsers(id, userIdList, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:
a)正确时返回

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

b)若部分userid非法，则返回

{
  "errcode": 0,
  "errmsg": "invalid userlist failed"
  "invalidlist"："usr1|usr2|usr"
}

c)当包含的userid全部非法时返回

{
  "errcode": 40031,
  "errmsg": "all list invalid"
}

方法	exports.deleteTagUsers()	exports	deleteTagUsers
参数	id(Number)	标签ID
参数	userIdList(Array)	用户ID数组
参数	callback(Function)	回调函数

api_user: API索引

createUser
updateUser
deleteUser
getUser
getDepartmentUsers
getUserIdByCode
getAuthorizeURL

createUser

创建成员
详细请看：http://qydev.weixin.qq.com/wiki/index.php?title=管理成员

Examples:

api.createUser(user, callback);

User:

{
  "userid": "zhangsan",
  "name": "张三",
  "department": [1, 2],
  "position": "产品经理",
  "mobile": "15913215421",
  "gender": 1,
  "tel": "62394",
  "email": "zhangsan@gzdev.com",
  "weixinid": "zhangsan4dev"
}

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.createUser()	exports	createUser
参数	user(Object)	成员信息
参数	callback(Function)	回调函数

updateUser

更新成员

Examples:

api.updateUser(user, callback);

User:

{
  "userid": "zhangsan",
  "name": "李四",
  "department": [1],
  "position": "后台工程师",
  "mobile": "15913215421",
  "gender": 1,
  "tel": "62394",
  "email": "zhangsan@gzdev.com",
  "weixinid": "lisifordev",
  "enable": 1
}

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.updateUser()	exports	updateUser
参数	user(Object)	成员信息
参数	callback(Function)	回调函数

deleteUser

删除成员

Examples:

api.deleteUser(id, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

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

方法	exports.deleteUser()	exports	deleteUser
参数	id(Number)	成员ID
参数	callback(Function)	回调函数

getUser

获取成员

Examples:

api.getUser(id, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
  "errcode": 0,
  "errmsg": "ok",
  "userid": "zhangsan",
  "name": "李四",
  "department": [1, 2],
  "position": "后台工程师",
  "mobile": "15913215421",
  "gender": 1,
  "tel": "62394",
  "email": "zhangsan@gzdev.com",
  "weixinid": "lisifordev",
  "avatar": "http://wx.qlogo.cn/mmopen/ajNVdqHZLLA3WJ6DSZUfiakYe37PKnQhBIeOQBO4czqrnZDS79FH5Wm5m4X69TBicnHFlhiafvDwklOpZeXYQQ2icg/0",
  "status": 1
}

方法	exports.getUser()	exports	getUser
参数	id(Number)	成员ID
参数	callback(Function)	回调函数

getDepartmentUsers

获取部门成员

Examples:

api.getDepartmentUsers(departmentId, fetchChild, status, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
  "errcode": 0,
  "errmsg": "ok",
  "userlist": [
    {
      "userid": "zhangsan",
      "name": "李四"
    }
  ]
}

方法	exports.getDepartmentUsers()	exports	getDepartmentUsers
参数	departmentId(Number)	部门ID
参数	fetchChild(Number)	值：1/0，是否递归获取子部门下面的成员
参数	status(Number)	0获取全部员工，1获取已关注成员列表，2获取禁用成员列表，4获取未关注成员列表。status可叠加
参数	callback(Function)	回调函数

getUserIdByCode

根据Code获取用户ID

详情：http://qydev.weixin.qq.com/wiki/index.php?title=根据code获取成员信息
Examples:

api.getUserIdByCode(code, callback);

Callback:

err, 调用失败时得到的异常
result, 调用正常时得到的对象

Result:

{
  "UserId": "USERID"
}

方法	exports.getUserIdByCode()	exports	getUserIdByCode
参数	code(String)	OAuth授权获取的code
参数	callback(Function)	回调函数

getAuthorizeURL

获取授权页面的URL地址

方法	exports.getAuthorizeURL()	exports	getAuthorizeURL
参数	redirect(String)	授权后要跳转的地址
参数	state(String)	开发者可提供的数据
参数	scope(String)	作用范围，值为snsapi_userinfo和snsapi_base，前者用于弹出，后者用于跳转

list: API索引

List
get
add
get
clear

List

回复列表类型

函数	List()		List

get

从List对象中根据key取出对应的handler

方法	List.prototype.get()		get
参数	key(String)	列表中的关键词

add

静态方法，根据items生成List对象，并放置到缓存中

方法	List.add()	List	add
参数	name(String)	列表名字
参数	items(Array)	元素列表

get

静态方法，从缓存中根据名字取出List对象

方法	List.get()	List	get
参数	name(String)	列表名字

clear

静态方法，清空缓存的所有的List对象

方法	List.clear()	List	clear
参数	name(String)	列表名字

msg_crypto: API索引

PKCS7Encoder
decode
encode
WXBizMsgCrypt
getSignature
decrypt
encrypt

PKCS7Encoder

提供基于PKCS7算法的加解密接口

声明	PKCS7Encoder		PKCS7Encoder

decode

删除解密后明文的补位字符

方法	PKCS7Encoder.decode()	PKCS7Encoder	decode
参数	text(String)	解密后的明文

encode

对需要加密的明文进行填充补位

方法	PKCS7Encoder.encode()	PKCS7Encoder	encode
参数	text(String)	需要进行填充补位操作的明文

WXBizMsgCrypt

微信企业平台加解密信息构造函数

函数	WXBizMsgCrypt()		WXBizMsgCrypt
参数	token(String)	公众平台上，开发者设置的Token
参数	encodingAESKey(String)	公众平台上，开发者设置的EncodingAESKey
参数	corpId(String)	企业号的CorpId

getSignature

获取签名

方法	WXBizMsgCrypt.prototype.getSignature()		getSignature
参数	timestamp(String)	时间戳
参数	nonce(String)	随机数
参数	encrypt(String)	加密后的文本

decrypt

对密文进行解密

方法	WXBizMsgCrypt.prototype.decrypt()		decrypt
参数	text(String)	待解密的密文

encrypt

对明文进行加密

方法	WXBizMsgCrypt.prototype.encrypt()		encrypt
参数	text(String)	待加密的明文

session: API索引

Session
save
destroy

Session

Session构造函数，用于与Connect的Session中间件集成的会话脚本

函数	Session()		Session
参数	id(String)	Session ID
参数	req(Object)	Connect中的请求对象
参数	data(Object)	可选的其余数据，将被合并进Session对象中

save

保存Session对象到实际的存储中

Callback:

err, 错误对象，保存发生错误时传入

方法	Session.prototype.save()		save
参数	callback(Function)	保存Session的回调函数

destroy

销毁Session对象

Callback:

err, 错误对象，删除发生错误时传入

方法	Session.prototype.destroy()		destroy
参数	callback(Function)	从存储中删除Session数据后的回调函数

util: API索引

wechat-enterprise: API索引

Handler
setHandler
getHandler
middlewarify
middleware

Handler

微信自动回复平台的内部的Handler对象

函数	Handler()		Handler
参数	config(Object)	企业号的开发者配置对象
参数	handle(Function)	handle对象 config: ``` { token: '', // 公众平台上，开发者设置的Token encodingAESKey: '', // 公众平台上，开发者设置的EncodingAESKey corpId: '', // 企业号的CorpId } ```

setHandler

设置handler对象
按消息设置handler对象的快捷方式

text(fn)
image(fn)
voice(fn)
video(fn)
location(fn)
link(fn)
event(fn)

方法	Handler.prototype.setHandler()		setHandler
参数	type(String)	handler处理的消息类型
参数	handle(Function)	handle对象

getHandler

根据消息类型取出handler对象

方法	Handler.prototype.getHandler()		getHandler
参数	type(String)	消息类型

middlewarify

根据Handler对象生成响应方法，并最终生成中间件函数

方法	Handler.prototype.middlewarify()		middlewarify

middleware

根据口令

Examples:
使用wechat作为自动回复中间件的三种方式

wechat(config, function (req, res, next) {});

wechat(config, wechat.text(function (message, req, res, next) {
  // TODO
}).location(function (message, req, res, next) {
  // TODO
}));

wechat(config)
  .text(function (message, req, res, next) {
    // TODO
  }).location(function (message, req, res, next) {
   // TODO
  }).middleware();

静态方法

text，处理文字推送的回调函数，接受参数为(text, req, res, next)。
image，处理图片推送的回调函数，接受参数为(image, req, res, next)。
voice，处理声音推送的回调函数，接受参数为(voice, req, res, next)。
video，处理视频推送的回调函数，接受参数为(video, req, res, next)。
location，处理位置推送的回调函数，接受参数为(location, req, res, next)。
link，处理链接推送的回调函数，接受参数为(link, req, res, next)。
event，处理事件推送的回调函数，接受参数为(event, req, res, next)。

函数	middleware()		middleware
参数	config(Object)	企业号的开发者配置对象
参数	handle(Function)	生成的回调函数，参见示例