From 4074ef53ead9a46586af895ad102cb73fb4f6bf0 Mon Sep 17 00:00:00 2001 From: Jiarui LI Date: Tue, 30 Jan 2018 17:35:52 +0800 Subject: [PATCH] fix #1079 --- docs/index.md | 1906 +++++++++++++++++++++++++----------------------- package.json | 2 +- src/message.ts | 4 +- 3 files changed, 1009 insertions(+), 903 deletions(-) diff --git a/docs/index.md b/docs/index.md index 31b3abe1a..cac6b41a4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,18 @@ -# Wechaty v0.10.6 Documentation +# Wechaty v0.13.50 Documentation ## Classes
+
Wechaty
+

Main bot class.

+

The World's Shortest ChatBot Code: 6 lines of JavaScript

+

Wechaty Starter Project

+
+
Room
+

All wechat rooms(groups) will be encapsulated as a Room.

+

Room is Sayable, +Example/Room-Bot

+
Contact

All wechat contacts(friend) will be encapsulated as a Contact.

Contact is Sayable, @@ -25,16 +35,6 @@

MediaMessage

Meidia Type Message

-
Room
-

All wechat rooms(groups) will be encapsulated as a Room.

-

Room is Sayable, -Example/Room-Bot

-
-
Wechaty
-

Main bot class.

-

The World's Shortest ChatBot Code: 6 lines of JavaScript

-

Wechaty Starter Project

-
FriendRequest
@@ -42,8 +42,11 @@ ## Typedefs
-
ContactQueryFilter
-

The way to search Contact

+
WechatyEventName
+

Wechaty Class Event Type

+
+
WechatyEventFunction
+

Wechaty Class Event Function

RoomEventName

Room Class Event Type

@@ -54,1151 +57,1197 @@
MemberQueryFilter

The way to search member by Room.member()

-
WechatyEventName
-

Wechaty Class Event Type

-
-
WechatyEventFunction
-

Wechaty Class Event Function

+
ContactQueryFilter
+

The way to search Contact

- + -## Contact -All wechat contacts(friend) will be encapsulated as a Contact. +## Wechaty +Main bot class. -`Contact` is `Sayable`, -[Example/Contact-Bot](https://github.com/Chatie/wechaty/blob/master/example/contact-bot.ts) +[The World's Shortest ChatBot Code: 6 lines of JavaScript](#wechatyinstance) + +[Wechaty Starter Project](https://github.com/lijiarui/wechaty-getting-started) **Kind**: global class -* [Contact](#Contact) +* [Wechaty](#Wechaty) * _instance_ - * [.say(textOrMedia)](#Contact+say) ⇒ Promise.<boolean> - * [.name()](#Contact+name) ⇒ string - * [.alias(newAlias)](#Contact+alias) ⇒ string \| null \| Promise.<boolean> - * [.stranger()](#Contact+stranger) ⇒ boolean \| null - * [.official()](#Contact+official) ⇒ boolean \| null - * [.special()](#Contact+special) ⇒ boolean \| null - * [.personal()](#Contact+personal) ⇒ boolean \| null - * [.star()](#Contact+star) ⇒ boolean - * [.gender()](#Contact+gender) ⇒ Gender.Male(2) \| Gender.Female(1) \| Gender.Unknown(0) - * [.province()](#Contact+province) ⇒ string \| undefined - * [.city()](#Contact+city) ⇒ string \| undefined - * [.avatar()](#Contact+avatar) ⇒ Promise.<NodeJS.ReadableStream> - * [.refresh()](#Contact+refresh) ⇒ Promise.<this> - * [.self()](#Contact+self) ⇒ boolean + * [.version([forceNpm])](#Wechaty+version) ⇒ string + * ~~[.init()](#Wechaty+init) ⇒ Promise.<void>~~ + * [.start()](#Wechaty+start) ⇒ Promise.<void> + * [.on(event, listener)](#Wechaty+on) ⇒ [Wechaty](#Wechaty) + * ~~[.quit()](#Wechaty+quit) ⇒ Promise.<void>~~ + * [.stop()](#Wechaty+stop) ⇒ Promise.<void> + * [.logout()](#Wechaty+logout) ⇒ Promise.<void> + * [.logonoff()](#Wechaty+logonoff) ⇒ boolean + * [.self()](#Wechaty+self) ⇒ [Contact](#Contact) + * [.say(content)](#Wechaty+say) ⇒ Promise.<boolean> * _static_ - * [.find(query)](#Contact.find) ⇒ Promise.<(Contact\|null)> - * [.findAll([queryArg])](#Contact.findAll) ⇒ Promise.<Array.<Contact>> + * [.instance()](#Wechaty.instance) - + -### contact.say(textOrMedia) ⇒ Promise.<boolean> -Send Text or Media File to Contact. +### wechaty.version([forceNpm]) ⇒ string +Return version of Wechaty -**Kind**: instance method of [Contact](#Contact) +**Kind**: instance method of [Wechaty](#Wechaty) +**Returns**: string - - the version number -| Param | Type | -| --- | --- | -| textOrMedia | string \| [MediaMessage](#MediaMessage) | +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [forceNpm] | boolean | false | if set to true, will only return the version in package.json. otherwise will return git commit hash if .git exists. | **Example** ```js -const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of your contact name in wechat -await contact.say('welcome to wechaty!') -await contact.say(new MediaMessage(__dirname + '/wechaty.png') // put the filePath you want to send here +console.log(Wechaty.instance().version()) // return '#git[af39df]' +console.log(Wechaty.instance().version(true)) // return '0.7.9' ``` - + -### contact.name() ⇒ string -Get the name from a contact +### ~~wechaty.init() ⇒ Promise.<void>~~ +***Deprecated*** -**Kind**: instance method of [Contact](#Contact) +Initialize the bot, return Promise. + +**Kind**: instance method of [Wechaty](#Wechaty) **Example** ```js -const name = contact.name() +await bot.init() +// do other stuff with bot here ``` - + -### contact.alias(newAlias) ⇒ string \| null \| Promise.<boolean> -GET / SET / DELETE the alias for a contact +### wechaty.start() ⇒ Promise.<void> +Start the bot, return Promise. -Tests show it will failed if set alias too frequently(60 times in one minute). +**Kind**: instance method of [Wechaty](#Wechaty) +**Example** +```js +await bot.start() +// do other stuff with bot here +``` + -**Kind**: instance method of [Contact](#Contact) +### wechaty.on(event, listener) ⇒ [Wechaty](#Wechaty) +**Kind**: instance method of [Wechaty](#Wechaty) +**Returns**: [Wechaty](#Wechaty) - - this for chain -| Param | Type | -| --- | --- | -| newAlias | none \| string \| null | +More Example Gist: [Example/Friend-Bot](https://github.com/wechaty/wechaty/blob/master/example/friend-bot.ts) -**Example** *( GET the alias for a contact, return {(string | null)})* +| Param | Type | Description | +| --- | --- | --- | +| event | WechatyEvent | Emit WechatyEvent | +| listener | [WechatyEventFunction](#WechatyEventFunction) | Depends on the WechatyEvent | + +**Example** *(Event:scan )* ```js -const alias = contact.alias() -if (alias === null) { - console.log('You have not yet set any alias for contact ' + contact.name()) -} else { - console.log('You have already set an alias for contact ' + contact.name() + ':' + alias) -} +wechaty.on('scan', (url: string, code: number) => { + console.log(`[${code}] Scan ${url} to login.` ) +}) ``` -**Example** *(SET the alias for a contact)* +**Example** *(Event:login )* ```js -const ret = await contact.alias('lijiarui') -if (ret) { - console.log(`change ${contact.name()}'s alias successfully!`) -} else { - console.log(`failed to change ${contact.name()} alias!`) -} +bot.on('login', (user: Contact) => { + console.log(`user ${user} login`) +}) ``` -**Example** *(DELETE the alias for a contact)* +**Example** *(Event:logout )* ```js -const ret = await contact.alias(null) -if (ret) { - console.log(`delete ${contact.name()}'s alias successfully!`) -} else { - console.log(`failed to delete ${contact.name()}'s alias!`) -} +bot.on('logout', (user: Contact) => { + console.log(`user ${user} logout`) +}) ``` - - -### contact.stranger() ⇒ boolean \| null -Check if contact is stranger - -**Kind**: instance method of [Contact](#Contact) -**Returns**: boolean \| null - - True for not friend of the bot, False for friend of the bot, null for unknown. -**Example** +**Example** *(Event:message )* ```js -const isStranger = contact.stranger() +wechaty.on('message', (message: Message) => { + console.log(`message ${message} received`) +}) ``` - - -### contact.official() ⇒ boolean \| null -Check if it's a offical account - -**Kind**: instance method of [Contact](#Contact) -**Returns**: boolean \| null - - True for official account, Flase for contact is not a official account, null for unknown -**See** - -- [webwxApp.js#L324](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3243) -- [Urinx/WeixinBot/README](https://github.com/Urinx/WeixinBot/blob/master/README.md) - -**Example** +**Example** *(Event:friend )* ```js -const isOfficial = contact.official() +bot.on('friend', (contact: Contact, request: FriendRequest) => { + if(request){ // 1. request to be friend from new contact + let result = await request.accept() + if(result){ + console.log(`Request from ${contact.name()} is accept succesfully!`) + } else{ + console.log(`Request from ${contact.name()} failed to accept!`) + } + } else { // 2. confirm friend ship + console.log(`new friendship confirmed with ${contact.name()}`) + } + }) ``` - - -### contact.special() ⇒ boolean \| null -Check if it's a special contact - -The contact who's id in following list will be identify as a special contact -`weibo`, `qqmail`, `fmessage`, `tmessage`, `qmessage`, `qqsync`, `floatbottle`, -`lbsapp`, `shakeapp`, `medianote`, `qqfriend`, `readerapp`, `blogapp`, `facebookapp`, -`masssendapp`, `meishiapp`, `feedsapp`, `voip`, `blogappweixin`, `weixin`, `brandsessionholder`, -`weixinreminder`, `wxid_novlwrv3lqwv11`, `gh_22b87fa7cb3c`, `officialaccounts`, `notification_messages`, +**Example** *(Event:room-join )* +```js +bot.on('room-join', (room: Room, inviteeList: Contact[], inviter: Contact) => { + const nameList = inviteeList.map(c => c.name()).join(',') + console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`) +}) +``` +**Example** *(Event:room-leave )* +```js +bot.on('room-leave', (room: Room, leaverList: Contact[]) => { + const nameList = leaverList.map(c => c.name()).join(',') + console.log(`Room ${room.topic()} lost member ${nameList}`) +}) +``` +**Example** *(Event:room-topic )* +```js +bot.on('room-topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => { + console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`) +}) +``` + -**Kind**: instance method of [Contact](#Contact) -**Returns**: boolean \| null - True for brand, Flase for contact is not a brand -**See** +### ~~wechaty.quit() ⇒ Promise.<void>~~ +***Deprecated*** -- [webwxApp.js#L3848](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3848) -- [webwxApp.js#L3246](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3246) +Quit the bot +**Kind**: instance method of [Wechaty](#Wechaty) **Example** ```js -const isSpecial = contact.special() +await bot.quit() ``` - + -### contact.personal() ⇒ boolean \| null -Check if it's a personal account +### wechaty.stop() ⇒ Promise.<void> +Stop the bot -**Kind**: instance method of [Contact](#Contact) -**Returns**: boolean \| null - - True for personal account, Flase for contact is not a personal account +**Kind**: instance method of [Wechaty](#Wechaty) **Example** ```js -const isPersonal = contact.personal() +await bot.stop() ``` - + -### contact.star() ⇒ boolean -Check if the contact is star contact. +### wechaty.logout() ⇒ Promise.<void> +Logout the bot -**Kind**: instance method of [Contact](#Contact) -**Returns**: boolean - - True for star friend, False for no star friend. +**Kind**: instance method of [Wechaty](#Wechaty) **Example** ```js -const isStar = contact.star() +await bot.logout() ``` - + -### contact.gender() ⇒ Gender.Male(2) \| Gender.Female(1) \| Gender.Unknown(0) -Contact gender +### wechaty.logonoff() ⇒ boolean +Get the logon / logoff state -**Kind**: instance method of [Contact](#Contact) +**Kind**: instance method of [Wechaty](#Wechaty) **Example** ```js -const gender = contact.gender() +if (bot.logonoff()) { + console.log('Bot logined') +} else { + console.log('Bot not logined') +} ``` - + -### contact.province() ⇒ string \| undefined -Get the region 'province' from a contact +### wechaty.self() ⇒ [Contact](#Contact) +Get current user -**Kind**: instance method of [Contact](#Contact) +**Kind**: instance method of [Wechaty](#Wechaty) **Example** ```js -const province = contact.province() +const contact = bot.self() +console.log(`Bot is ${contact.name()}`) ``` - + -### contact.city() ⇒ string \| undefined -Get the region 'city' from a contact +### wechaty.say(content) ⇒ Promise.<boolean> +Send message to filehelper -**Kind**: instance method of [Contact](#Contact) -**Example** -```js -const city = contact.city() -``` - +**Kind**: instance method of [Wechaty](#Wechaty) -### contact.avatar() ⇒ Promise.<NodeJS.ReadableStream> -Get avatar picture file stream +| Param | Type | +| --- | --- | +| content | string | -**Kind**: instance method of [Contact](#Contact) -**Example** -```js -const avatarFileName = contact.name() + `.jpg` -const avatarReadStream = await contact.avatar() -const avatarWriteStream = createWriteStream(avatarFileName) -avatarReadStream.pipe(avatarWriteStream) -log.info('Bot', 'Contact: %s: %s with avatar file: %s', contact.weixin(), contact.name(), avatarFileName) -``` - + -### contact.refresh() ⇒ Promise.<this> -Force reload data for Contact +### Wechaty.instance() +get the singleton instance of Wechaty -**Kind**: instance method of [Contact](#Contact) -**Example** +**Kind**: static method of [Wechaty](#Wechaty) +**Example** *(The World's Shortest ChatBot Code: 6 lines of JavaScript)* ```js -await contact.refresh() +const { Wechaty } = require('wechaty') + +Wechaty.instance() // Singleton +.on('scan', (url, code) => console.log(`Scan QR Code to login: ${code}\n${url}`)) +.on('login', user => console.log(`User ${user} logined`)) +.on('message', message => console.log(`Message: ${message}`)) +.init() ``` - + -### contact.self() ⇒ boolean -Check if contact is self +## Room +All wechat rooms(groups) will be encapsulated as a Room. -**Kind**: instance method of [Contact](#Contact) -**Returns**: boolean - True for contact is self, False for contact is others -**Example** -```js -const isSelf = contact.self() -``` - +`Room` is `Sayable`, +[Example/Room-Bot](https://github.com/Chatie/wechaty/blob/master/example/room-bot.ts) -### Contact.find(query) ⇒ Promise.<(Contact\|null)> -Try to find a contact by filter: {name: string | RegExp} / {alias: string | RegExp} +**Kind**: global class -Find contact by name or alias, if the result more than one, return the first one. +* [Room](#Room) + * _instance_ + * [.say(textOrMedia, [replyTo])](#Room+say) ⇒ Promise.<boolean> + * [.on(event, listener)](#Room+on) ⇒ this + * [.add(contact)](#Room+add) ⇒ Promise.<number> + * [.del(contact)](#Room+del) ⇒ Promise.<number> + * [.topic([newTopic])](#Room+topic) ⇒ string \| void + * [.alias(contact)](#Room+alias) ⇒ string \| null + * [.roomAlias(contact)](#Room+roomAlias) ⇒ string \| null + * [.has(contact)](#Room+has) ⇒ boolean + * [.memberAll(queryArg)](#Room+memberAll) ⇒ [Array.<Contact>](#Contact) + * [.member(queryArg)](#Room+member) ⇒ [Contact](#Contact) \| null + * [.memberList()](#Room+memberList) ⇒ [Array.<Contact>](#Contact) + * [.refresh()](#Room+refresh) ⇒ Promise.<void> + * _static_ + * [.create(contactList, [topic])](#Room.create) ⇒ [Promise.<Room>](#Room) + * [.findAll([query])](#Room.findAll) ⇒ Promise.<Array.<Room>> + * [.find(query)](#Room.find) ⇒ Promise.<(Room\|null)> -**Kind**: static method of [Contact](#Contact) -**Returns**: Promise.<(Contact\|null)> - If can find the contact, return Contact, or return null + -| Param | Type | -| --- | --- | -| query | [ContactQueryFilter](#ContactQueryFilter) | +### room.say(textOrMedia, [replyTo]) ⇒ Promise.<boolean> +Send message inside Room, if set [replyTo], wechaty will mention the contact as well. -**Example** +**Kind**: instance method of [Room](#Room) +**Returns**: Promise.<boolean> - If bot send message successfully, it will return true. If the bot failed to send for blocking or any other reason, it will return false + +| Param | Type | Description | +| --- | --- | --- | +| textOrMedia | string \| [MediaMessage](#MediaMessage) | Send `text` or `media file` inside Room. | +| [replyTo] | [Contact](#Contact) \| [Array.<Contact>](#Contact) | Optional parameter, send content inside Room, and mention @replyTo contact or contactList. | + +**Example** *(Send text inside Room)* ```js -const contactFindByName = await Contact.find({ name:"ruirui"} ) -const contactFindByAlias = await Contact.find({ alias:"lijiarui"} ) +const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat +await room.say('Hello world!') ``` - +**Example** *(Send media file inside Room)* +```js +const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat +await room.say(new MediaMessage('/test.jpg')) // put the filePath you want to send here +``` +**Example** *(Send text inside Room, and mention @replyTo contact)* +```js +const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member +const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat +await room.say('Hello world!', contact) +``` + -### Contact.findAll([queryArg]) ⇒ Promise.<Array.<Contact>> -Find contact by `name` or `alias` +### room.on(event, listener) ⇒ this +**Kind**: instance method of [Room](#Room) +**Returns**: this - - this for chain -If use Contact.findAll() get the contact list of the bot. +| Param | Type | Description | +| --- | --- | --- | +| event | [RoomEventName](#RoomEventName) | Emit WechatyEvent | +| listener | [RoomEventFunction](#RoomEventFunction) | Depends on the WechatyEvent | -#### definition -- `name` the name-string set by user-self, should be called name -- `alias` the name-string set by bot for others, should be called alias +**Example** *(Event:join )* +```js +const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('join', (room: Room, inviteeList: Contact[], inviter: Contact) => { + const nameList = inviteeList.map(c => c.name()).join(',') + console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`) + }) +} +``` +**Example** *(Event:leave )* +```js +const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('leave', (room: Room, leaverList: Contact[]) => { + const nameList = leaverList.map(c => c.name()).join(',') + console.log(`Room ${room.topic()} lost member ${nameList}`) + }) +} +``` +**Example** *(Event:topic )* +```js +const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat +if (room) { + room.on('topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => { + console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`) + }) +} +``` + -**Kind**: static method of [Contact](#Contact) +### room.add(contact) ⇒ Promise.<number> +Add contact in a room + +**Kind**: instance method of [Room](#Room) | Param | Type | | --- | --- | -| [queryArg] | [ContactQueryFilter](#ContactQueryFilter) | +| contact | [Contact](#Contact) | **Example** ```js -const contactList = await Contact.findAll() // get the contact list of the bot -const contactList = await Contact.findAll({name: 'ruirui'}) // find allof the contacts whose name is 'ruirui' -const contactList = await Contact.findAll({alias: 'lijiarui'}) // find all of the contacts whose alias is 'lijiarui' +const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any contact in your wechat +const room = await Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat +if (room) { + const result = await room.add(contact) + if (result) { + console.log(`add ${contact.name()} to ${room.topic()} successfully! `) + } else{ + console.log(`failed to add ${contact.name()} to ${room.topic()}! `) + } +} ``` - - -## FriendRequest -Send, receive friend request, and friend confirmation events. - -1. send request -2. receive request(in friend event) -3. confirmation friendship(friend event) - -[Example/Friend-Bot](https://github.com/Chatie/wechaty/blob/master/example/friend-bot.ts) - -**Kind**: global class - -* [FriendRequest](#FriendRequest) - * [.send(contact, [hello])](#FriendRequest+send) ⇒ Promise.<boolean> - * [.accept()](#FriendRequest+accept) ⇒ Promise.<boolean> - - + -### friendRequest.send(contact, [hello]) ⇒ Promise.<boolean> -Send a new friend request +### room.del(contact) ⇒ Promise.<number> +Delete a contact from the room +It works only when the bot is the owner of the room -**Kind**: instance method of [FriendRequest](#FriendRequest) -**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure. +**Kind**: instance method of [Room](#Room) -| Param | Type | Default | -| --- | --- | --- | -| contact | [Contact](#Contact) | | -| [hello] | string | "'Hi'" | +| Param | Type | +| --- | --- | +| contact | [Contact](#Contact) | **Example** ```js -const from = message.from() -const request = new FriendRequest() -request.send(from, 'hello~') +const room = await Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat +const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any room member in the room you just set +if (room) { + const result = await room.del(contact) + if (result) { + console.log(`remove ${contact.name()} from ${room.topic()} successfully! `) + } else{ + console.log(`failed to remove ${contact.name()} from ${room.topic()}! `) + } +} ``` - + -### friendRequest.accept() ⇒ Promise.<boolean> -Accept a friend request +### room.topic([newTopic]) ⇒ string \| void +SET/GET topic from the room -**Kind**: instance method of [FriendRequest](#FriendRequest) -**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure. - +**Kind**: instance method of [Room](#Room) -## Message -All wechat messages will be encapsulated as a Message. +| Param | Type | Description | +| --- | --- | --- | +| [newTopic] | string | If set this para, it will change room topic. | -`Message` is `Sayable`, -[Example/Ding-Dong-Bot](https://github.com/Chatie/wechaty/blob/master/example/ding-dong-bot.ts) - -**Kind**: global class - -* [Message](#Message) - * _instance_ - * [.say(textOrMedia, [replyTo])](#Message+say) ⇒ Promise.<any> - * [.from()](#Message+from) ⇒ [Contact](#Contact) - * [.room()](#Message+room) ⇒ [Room](#Room) \| null - * [.content()](#Message+content) ⇒ string - * [.type()](#Message+type) ⇒ MsgType - * [.typeSub()](#Message+typeSub) ⇒ MsgType - * [.typeApp()](#Message+typeApp) ⇒ AppMsgType - * [.typeEx()](#Message+typeEx) ⇒ MsgType - * [.self()](#Message+self) ⇒ boolean - * [.mentioned()](#Message+mentioned) ⇒ [Array.<Contact>](#Contact) - * [.to()](#Message+to) ⇒ [Contact](#Contact) \| null - * [.readyStream()](#Message+readyStream) ⇒ Promise.<Readable> - * _static_ - * [.find()](#Message.find) - * [.findAll()](#Message.findAll) - - +**Example** *(When you say anything in a room, it will get room topic. )* +```js +const bot = Wechaty.instance() +bot +.on('message', async m => { + const room = m.room() + if (room) { + const topic = room.topic() + console.log(`room topic is : ${topic}`) + } +}) +``` +**Example** *(When you say anything in a room, it will change room topic. )* +```js +const bot = Wechaty.instance() +bot +.on('message', async m => { + const room = m.room() + if (room) { + const oldTopic = room.topic() + room.topic('change topic to wechaty!') + console.log(`room topic change from ${oldTopic} to ${room.topic()}`) + } +}) +``` + -### message.say(textOrMedia, [replyTo]) ⇒ Promise.<any> -Reply a Text or Media File message to the sender. +### room.alias(contact) ⇒ string \| null +Return contact's roomAlias in the room, the same as roomAlias -**Kind**: instance method of [Message](#Message) -**See**: [Example/ding-dong-bot](https://github.com/Chatie/wechaty/blob/master/example/ding-dong-bot.ts) +**Kind**: instance method of [Room](#Room) +**Returns**: string \| null - - If a contact has an alias in room, return string, otherwise return null | Param | Type | | --- | --- | -| textOrMedia | string \| [MediaMessage](#MediaMessage) | -| [replyTo] | [Contact](#Contact) \| [Array.<Contact>](#Contact) | +| contact | [Contact](#Contact) | **Example** ```js const bot = Wechaty.instance() bot .on('message', async m => { - if (/^ding$/i.test(m.content())) { - await m.say('hello world') - console.log('Bot REPLY: hello world') - await m.say(new MediaMessage(__dirname + '/wechaty.png')) - console.log('Bot REPLY: Image') + const room = m.room() + const contact = m.from() + if (room) { + const alias = room.alias(contact) + console.log(`${contact.name()} alias is ${alias}`) } }) ``` - - -### message.from() ⇒ [Contact](#Contact) -Get the sender from a message. + -**Kind**: instance method of [Message](#Message) - +### room.roomAlias(contact) ⇒ string \| null +Same as function alias -### message.room() ⇒ [Room](#Room) \| null -Get the room from the message. -If the message is not in a room, then will return `null` +**Kind**: instance method of [Room](#Room) -**Kind**: instance method of [Message](#Message) - +| Param | Type | +| --- | --- | +| contact | [Contact](#Contact) | -### message.content() ⇒ string -Get the content of the message + -**Kind**: instance method of [Message](#Message) - +### room.has(contact) ⇒ boolean +Check if the room has member `contact`. -### message.type() ⇒ MsgType -Get the type from the message. +**Kind**: instance method of [Room](#Room) +**Returns**: boolean - Return `true` if has contact, else return `false`. -If type is equal to `MsgType.RECALLED`, [Message#id](Message#id) is the msgId of the recalled message. +| Param | Type | +| --- | --- | +| contact | [Contact](#Contact) | -**Kind**: instance method of [Message](#Message) -**See**: [MsgType](MsgType) - +**Example** *(Check whether 'lijiarui' is in the room 'wechaty')* +```js +const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of contact in your wechat +const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any of the room in your wechat +if (contact && room) { + if (room.has(contact)) { + console.log(`${contact.name()} is in the room ${room.topic()}!`) + } else { + console.log(`${contact.name()} is not in the room ${room.topic()} !`) + } +} +``` + -### message.typeSub() ⇒ MsgType -Get the typeSub from the message. +### room.memberAll(queryArg) ⇒ [Array.<Contact>](#Contact) +Find all contacts in a room -If message is a location message: `m.type() === MsgType.TEXT && m.typeSub() === MsgType.LOCATION` +#### definition +- `name` the name-string set by user-self, should be called name, equal to `Contact.name()` +- `roomAlias` | `alias` the name-string set by user-self in the room, should be called roomAlias +- `contactAlias` the name-string set by bot for others, should be called alias, equal to `Contact.alias()` -**Kind**: instance method of [Message](#Message) -**See**: [MsgType](MsgType) - +**Kind**: instance method of [Room](#Room) -### message.typeApp() ⇒ AppMsgType -Get the typeApp from the message. +| Param | Type | Description | +| --- | --- | --- | +| queryArg | [MemberQueryFilter](#MemberQueryFilter) \| string | When use memberAll(name:string), return all matched members, including name, roomAlias, contactAlias | -**Kind**: instance method of [Message](#Message) -**See**: [AppMsgType](AppMsgType) - + -### message.typeEx() ⇒ MsgType -Get the typeEx from the message. +### room.member(queryArg) ⇒ [Contact](#Contact) \| null +Find all contacts in a room, if get many, return the first one. -**Kind**: instance method of [Message](#Message) - +**Kind**: instance method of [Room](#Room) -### message.self() ⇒ boolean -Check if a message is sent by self. +| Param | Type | Description | +| --- | --- | --- | +| queryArg | [MemberQueryFilter](#MemberQueryFilter) \| string | When use member(name:string), return all matched members, including name, roomAlias, contactAlias | -**Kind**: instance method of [Message](#Message) -**Returns**: boolean - - Return `true` for send from self, `false` for send from others. -**Example** +**Example** *(Find member by name)* ```js -if (message.self()) { - console.log('this message is sent by myself!') +const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat +if (room) { + const member = room.member('lijiarui') // change 'lijiarui' to any room member in your wechat + if (member) { + console.log(`${room.topic()} got the member: ${member.name()}`) + } else { + console.log(`cannot get member in room: ${room.topic()}`) + } } ``` - - -### message.mentioned() ⇒ [Array.<Contact>](#Contact) -Get message mentioned contactList. - -Message event table as follows - -| | Web | Mac PC Client | iOS Mobile | android Mobile | -| :--- | :--: | :----: | :---: | :---: | -| [You were mentioned] tip ([有人@我]的提示) | ✘ | √ | √ | √ | -| Identify magic code (8197) by copy & paste in mobile | ✘ | √ | √ | ✘ | -| Identify magic code (8197) by programming | ✘ | ✘ | ✘ | ✘ | -| Identify two contacts with the same roomAlias by [You were mentioned] tip | ✘ | ✘ | √ | √ | - -**Kind**: instance method of [Message](#Message) -**Returns**: [Array.<Contact>](#Contact) - - Return message mentioned contactList -**Example** +**Example** *(Find member by MemberQueryFilter)* ```js -const contactList = message.mentioned() -console.log(contactList) +const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat +if (room) { + const member = room.member({name: 'lijiarui'}) // change 'lijiarui' to any room member in your wechat + if (member) { + console.log(`${room.topic()} got the member: ${member.name()}`) + } else { + console.log(`cannot get member in room: ${room.topic()}`) + } +} ``` - + -### message.to() ⇒ [Contact](#Contact) \| null -Get the destination of the message -Message.to() will return null if a message is in a room, use Message.room() to get the room. +### room.memberList() ⇒ [Array.<Contact>](#Contact) +Get all room member from the room -**Kind**: instance method of [Message](#Message) - +**Kind**: instance method of [Room](#Room) + -### message.readyStream() ⇒ Promise.<Readable> -Please notice that when we are running Wechaty, -if you use the browser that controlled by Wechaty to send attachment files, -you will get a zero sized file, because it is not an attachment from the network, -but a local data, which is not supported by Wechaty yet. +### room.refresh() ⇒ Promise.<void> +Force reload data for Room -**Kind**: instance method of [Message](#Message) - +**Kind**: instance method of [Room](#Room) + -### Message.find() -**Kind**: static method of [Message](#Message) -**Todo** +### Room.create(contactList, [topic]) ⇒ [Promise.<Room>](#Room) +Create a new room. -- [ ] add function +**Kind**: static method of [Room](#Room) - +| Param | Type | +| --- | --- | +| contactList | [Array.<Contact>](#Contact) | +| [topic] | string | -### Message.findAll() -**Kind**: static method of [Message](#Message) -**Todo** +**Example** *(Creat a room with 'lijiarui' and 'juxiaomi', the room topic is 'ding - created')* +```js +const helperContactA = await Contact.find({ name: 'lijiarui' }) // change 'lijiarui' to any contact in your wechat +const helperContactB = await Contact.find({ name: 'juxiaomi' }) // change 'juxiaomi' to any contact in your wechat +const contactList = [helperContactA, helperContactB] +console.log('Bot', 'contactList: %s', contactList.join(',')) +const room = await Room.create(contactList, 'ding') +console.log('Bot', 'createDingRoom() new ding room created: %s', room) +await room.topic('ding - created') +await room.say('ding - created') +``` + -- [ ] add function +### Room.findAll([query]) ⇒ Promise.<Array.<Room>> +Find room by topic, return all the matched room - +**Kind**: static method of [Room](#Room) -## MediaMessage -Meidia Type Message +| Param | Type | +| --- | --- | +| [query] | RoomQueryFilter | -**Kind**: global class +**Example** +```js +const roomList = await Room.findAll() // get the room list of the bot +const roomList = await Room.findAll({name: 'wechaty'}) // find all of the rooms with name 'wechaty' +``` + -* [MediaMessage](#MediaMessage) - * [.ext()](#MediaMessage+ext) ⇒ string - * [.filename()](#MediaMessage+filename) ⇒ string - * [.readyStream()](#MediaMessage+readyStream) - * [.saveFile(filePath)](#MediaMessage+saveFile) - * [.forward(to)](#MediaMessage+forward) ⇒ Promise.<boolean> - - - -### mediaMessage.ext() ⇒ string -Get the MediaMessage file extension, etc: `jpg`, `gif`, `pdf`, `word` .. - -**Kind**: instance method of [MediaMessage](#MediaMessage) -**Example** -```js -bot.on('message', async function (m) { - if (m instanceof MediaMessage) { - console.log('media message file name extention is: ' + m.ext()) - } -}) -``` - - -### mediaMessage.filename() ⇒ string -Get the MediaMessage filename, etc: `how to build a chatbot.pdf`.. - -**Kind**: instance method of [MediaMessage](#MediaMessage) -**Example** -```js -bot.on('message', async function (m) { - if (m instanceof MediaMessage) { - console.log('media message file name is: ' + m.filename()) - } -}) -``` - - -### mediaMessage.readyStream() -Get the read stream for attachment file - -**Kind**: instance method of [MediaMessage](#MediaMessage) - - -### mediaMessage.saveFile(filePath) -save file +### Room.find(query) ⇒ Promise.<(Room\|null)> +Try to find a room by filter: {topic: string | RegExp}. If get many, return the first one. -**Kind**: instance method of [MediaMessage](#MediaMessage) +**Kind**: static method of [Room](#Room) +**Returns**: Promise.<(Room\|null)> - If can find the room, return Room, or return null -| Param | Description | +| Param | Type | | --- | --- | -| filePath | save file | - - - -### mediaMessage.forward(to) ⇒ Promise.<boolean> -Forward the received message. - -The types of messages that can be forwarded are as follows: - -The return value of [type](#Message+type) matches one of the following types: -```json -MsgType { - TEXT = 1, - IMAGE = 3, - VIDEO = 43, - EMOTICON = 47, - LOCATION = 48, - APP = 49, - MICROVIDEO = 62, -} -``` - -When the return value of [type](#Message+type) is `MsgType.APP`, the return value of [typeApp](#Message+typeApp) matches one of the following types: -```json -AppMsgType { - TEXT = 1, - IMG = 2, - VIDEO = 4, - ATTACH = 6, - EMOJI = 8, -} -``` -It should be noted that when forwarding ATTACH type message, if the file size is greater than 25Mb, the forwarding will fail. -The reason is that the server shields the web wx to download more than 25Mb files with a file size of 0. - -But if the file is uploaded by you using wechaty, you can forward it. -You need to detect the following conditions in the message event, which can be forwarded if it is met. - -```javasrcipt -.on('message', async m => { - if (m.self() && m.rawObj && m.rawObj.Signature) { - // Filter the contacts you have forwarded - const msg = m - await msg.forward() - } -}) -``` - -**Kind**: instance method of [MediaMessage](#MediaMessage) - -| Param | Type | Description | -| --- | --- | --- | -| to | Sayable \| Array.<Sayable> | Room or Contact The recipient of the message, the room, or the contact | +| query | RoomQueryFilter | - + -## Room -All wechat rooms(groups) will be encapsulated as a Room. +## Contact +All wechat contacts(friend) will be encapsulated as a Contact. -`Room` is `Sayable`, -[Example/Room-Bot](https://github.com/Chatie/wechaty/blob/master/example/room-bot.ts) +`Contact` is `Sayable`, +[Example/Contact-Bot](https://github.com/Chatie/wechaty/blob/master/example/contact-bot.ts) **Kind**: global class -* [Room](#Room) +* [Contact](#Contact) * _instance_ - * [.say(textOrMedia, [replyTo])](#Room+say) ⇒ Promise.<boolean> - * [.on(event, listener)](#Room+on) ⇒ this - * [.add(contact)](#Room+add) ⇒ Promise.<number> - * [.del(contact)](#Room+del) ⇒ Promise.<number> - * [.topic([newTopic])](#Room+topic) ⇒ string \| void - * [.alias(contact)](#Room+alias) ⇒ string \| null - * [.roomAlias(contact)](#Room+roomAlias) ⇒ string \| null - * [.has(contact)](#Room+has) ⇒ boolean - * [.memberAll(queryArg)](#Room+memberAll) ⇒ [Array.<Contact>](#Contact) - * [.member(queryArg)](#Room+member) ⇒ [Contact](#Contact) \| null - * [.memberList()](#Room+memberList) ⇒ [Array.<Contact>](#Contact) - * [.refresh()](#Room+refresh) ⇒ Promise.<void> + * [.say(textOrMedia)](#Contact+say) ⇒ Promise.<boolean> + * [.name()](#Contact+name) ⇒ string + * [.alias(newAlias)](#Contact+alias) ⇒ string \| null \| Promise.<boolean> + * [.stranger()](#Contact+stranger) ⇒ boolean \| null + * [.official()](#Contact+official) ⇒ boolean \| null + * [.special()](#Contact+special) ⇒ boolean \| null + * [.personal()](#Contact+personal) ⇒ boolean \| null + * [.star()](#Contact+star) ⇒ boolean + * [.gender()](#Contact+gender) ⇒ Gender.Male(2) \| Gender.Female(1) \| Gender.Unknown(0) + * [.province()](#Contact+province) ⇒ string \| undefined + * [.city()](#Contact+city) ⇒ string \| undefined + * [.avatar()](#Contact+avatar) ⇒ Promise.<NodeJS.ReadableStream> + * [.refresh()](#Contact+refresh) ⇒ Promise.<this> + * [.self()](#Contact+self) ⇒ boolean * _static_ - * [.create(contactList, [topic])](#Room.create) ⇒ [Promise.<Room>](#Room) - * [.findAll([query])](#Room.findAll) ⇒ Promise.<Array.<Room>> - * [.find(query)](#Room.find) ⇒ Promise.<(Room\|null)> + * [.find(query)](#Contact.find) ⇒ Promise.<(Contact\|null)> + * [.findAll([queryArg])](#Contact.findAll) ⇒ Promise.<Array.<Contact>> - + -### room.say(textOrMedia, [replyTo]) ⇒ Promise.<boolean> -Send message inside Room, if set [replyTo], wechaty will mention the contact as well. +### contact.say(textOrMedia) ⇒ Promise.<boolean> +Send Text or Media File to Contact. -**Kind**: instance method of [Room](#Room) -**Returns**: Promise.<boolean> - If bot send message successfully, it will return true. If the bot failed to send for blocking or any other reason, it will return false +**Kind**: instance method of [Contact](#Contact) -| Param | Type | Description | -| --- | --- | --- | -| textOrMedia | string \| [MediaMessage](#MediaMessage) | Send `text` or `media file` inside Room. | -| [replyTo] | [Contact](#Contact) \| [Array.<Contact>](#Contact) | Optional parameter, send content inside Room, and mention @replyTo contact or contactList. | +| Param | Type | +| --- | --- | +| textOrMedia | string \| [MediaMessage](#MediaMessage) | -**Example** *(Send text inside Room)* -```js -const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat -await room.say('Hello world!') -``` -**Example** *(Send media file inside Room)* +**Example** ```js -const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat -await room.say(new MediaMessage('/test.jpg')) // put the filePath you want to send here +const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of your contact name in wechat +await contact.say('welcome to wechaty!') +await contact.say(new MediaMessage(__dirname + '/wechaty.png') // put the filePath you want to send here ``` -**Example** *(Send text inside Room, and mention @replyTo contact)* + + +### contact.name() ⇒ string +Get the name from a contact + +**Kind**: instance method of [Contact](#Contact) +**Example** ```js -const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member -const room = await Room.find({name: 'wechaty'}) // change 'wechaty' to any of your room in wechat -await room.say('Hello world!', contact) +const name = contact.name() ``` - + -### room.on(event, listener) ⇒ this -**Kind**: instance method of [Room](#Room) -**Returns**: this - - this for chain +### contact.alias(newAlias) ⇒ string \| null \| Promise.<boolean> +GET / SET / DELETE the alias for a contact -| Param | Type | Description | -| --- | --- | --- | -| event | [RoomEventName](#RoomEventName) | Emit WechatyEvent | -| listener | [RoomEventFunction](#RoomEventFunction) | Depends on the WechatyEvent | +Tests show it will failed if set alias too frequently(60 times in one minute). -**Example** *(Event:join )* +**Kind**: instance method of [Contact](#Contact) + +| Param | Type | +| --- | --- | +| newAlias | none \| string \| null | + +**Example** *( GET the alias for a contact, return {(string | null)})* ```js -const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat -if (room) { - room.on('join', (room: Room, inviteeList: Contact[], inviter: Contact) => { - const nameList = inviteeList.map(c => c.name()).join(',') - console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`) - }) +const alias = contact.alias() +if (alias === null) { + console.log('You have not yet set any alias for contact ' + contact.name()) +} else { + console.log('You have already set an alias for contact ' + contact.name() + ':' + alias) } ``` -**Example** *(Event:leave )* +**Example** *(SET the alias for a contact)* ```js -const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat -if (room) { - room.on('leave', (room: Room, leaverList: Contact[]) => { - const nameList = leaverList.map(c => c.name()).join(',') - console.log(`Room ${room.topic()} lost member ${nameList}`) - }) +const ret = await contact.alias('lijiarui') +if (ret) { + console.log(`change ${contact.name()}'s alias successfully!`) +} else { + console.log(`failed to change ${contact.name()} alias!`) } ``` -**Example** *(Event:topic )* +**Example** *(DELETE the alias for a contact)* ```js -const room = await Room.find({topic: 'event-room'}) // change `event-room` to any room topic in your wechat -if (room) { - room.on('topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => { - console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`) - }) +const ret = await contact.alias(null) +if (ret) { + console.log(`delete ${contact.name()}'s alias successfully!`) +} else { + console.log(`failed to delete ${contact.name()}'s alias!`) } ``` - + + +### contact.stranger() ⇒ boolean \| null +Check if contact is stranger + +**Kind**: instance method of [Contact](#Contact) +**Returns**: boolean \| null - - True for not friend of the bot, False for friend of the bot, null for unknown. +**Example** +```js +const isStranger = contact.stranger() +``` + + +### contact.official() ⇒ boolean \| null +Check if it's a offical account + +**Kind**: instance method of [Contact](#Contact) +**Returns**: boolean \| null - - True for official account, Flase for contact is not a official account, null for unknown +**See** + +- [webwxApp.js#L324](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3243) +- [Urinx/WeixinBot/README](https://github.com/Urinx/WeixinBot/blob/master/README.md) + +**Example** +```js +const isOfficial = contact.official() +``` + -### room.add(contact) ⇒ Promise.<number> -Add contact in a room +### contact.special() ⇒ boolean \| null +Check if it's a special contact -**Kind**: instance method of [Room](#Room) +The contact who's id in following list will be identify as a special contact +`weibo`, `qqmail`, `fmessage`, `tmessage`, `qmessage`, `qqsync`, `floatbottle`, +`lbsapp`, `shakeapp`, `medianote`, `qqfriend`, `readerapp`, `blogapp`, `facebookapp`, +`masssendapp`, `meishiapp`, `feedsapp`, `voip`, `blogappweixin`, `weixin`, `brandsessionholder`, +`weixinreminder`, `wxid_novlwrv3lqwv11`, `gh_22b87fa7cb3c`, `officialaccounts`, `notification_messages`, -| Param | Type | -| --- | --- | -| contact | [Contact](#Contact) | +**Kind**: instance method of [Contact](#Contact) +**Returns**: boolean \| null - True for brand, Flase for contact is not a brand +**See** + +- [webwxApp.js#L3848](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3848) +- [webwxApp.js#L3246](https://github.com/Chatie/webwx-app-tracker/blob/7c59d35c6ea0cff38426a4c5c912a086c4c512b2/formatted/webwxApp.js#L3246) **Example** ```js -const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any contact in your wechat -const room = await Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat -if (room) { - const result = await room.add(contact) - if (result) { - console.log(`add ${contact.name()} to ${room.topic()} successfully! `) - } else{ - console.log(`failed to add ${contact.name()} to ${room.topic()}! `) - } -} +const isSpecial = contact.special() ``` - + -### room.del(contact) ⇒ Promise.<number> -Delete a contact from the room -It works only when the bot is the owner of the room +### contact.personal() ⇒ boolean \| null +Check if it's a personal account -**Kind**: instance method of [Room](#Room) +**Kind**: instance method of [Contact](#Contact) +**Returns**: boolean \| null - - True for personal account, Flase for contact is not a personal account +**Example** +```js +const isPersonal = contact.personal() +``` + -| Param | Type | -| --- | --- | -| contact | [Contact](#Contact) | +### contact.star() ⇒ boolean +Check if the contact is star contact. +**Kind**: instance method of [Contact](#Contact) +**Returns**: boolean - - True for star friend, False for no star friend. **Example** ```js -const room = await Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat -const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any room member in the room you just set -if (room) { - const result = await room.del(contact) - if (result) { - console.log(`remove ${contact.name()} from ${room.topic()} successfully! `) - } else{ - console.log(`failed to remove ${contact.name()} from ${room.topic()}! `) - } -} +const isStar = contact.star() ``` - + -### room.topic([newTopic]) ⇒ string \| void -SET/GET topic from the room +### contact.gender() ⇒ Gender.Male(2) \| Gender.Female(1) \| Gender.Unknown(0) +Contact gender -**Kind**: instance method of [Room](#Room) +**Kind**: instance method of [Contact](#Contact) +**Example** +```js +const gender = contact.gender() +``` + -| Param | Type | Description | -| --- | --- | --- | -| [newTopic] | string | If set this para, it will change room topic. | +### contact.province() ⇒ string \| undefined +Get the region 'province' from a contact -**Example** *(When you say anything in a room, it will get room topic. )* +**Kind**: instance method of [Contact](#Contact) +**Example** ```js -const bot = Wechaty.instance() -bot -.on('message', async m => { - const room = m.room() - if (room) { - const topic = room.topic() - console.log(`room topic is : ${topic}`) - } -}) +const province = contact.province() ``` -**Example** *(When you say anything in a room, it will change room topic. )* + + +### contact.city() ⇒ string \| undefined +Get the region 'city' from a contact + +**Kind**: instance method of [Contact](#Contact) +**Example** ```js -const bot = Wechaty.instance() -bot -.on('message', async m => { - const room = m.room() - if (room) { - const oldTopic = room.topic() - room.topic('change topic to wechaty!') - console.log(`room topic change from ${oldTopic} to ${room.topic()}`) - } -}) +const city = contact.city() ``` - + -### room.alias(contact) ⇒ string \| null -Return contact's roomAlias in the room, the same as roomAlias +### contact.avatar() ⇒ Promise.<NodeJS.ReadableStream> +Get avatar picture file stream -**Kind**: instance method of [Room](#Room) -**Returns**: string \| null - - If a contact has an alias in room, return string, otherwise return null +**Kind**: instance method of [Contact](#Contact) +**Example** +```js +const avatarFileName = contact.name() + `.jpg` +const avatarReadStream = await contact.avatar() +const avatarWriteStream = createWriteStream(avatarFileName) +avatarReadStream.pipe(avatarWriteStream) +log.info('Bot', 'Contact: %s: %s with avatar file: %s', contact.weixin(), contact.name(), avatarFileName) +``` + -| Param | Type | -| --- | --- | -| contact | [Contact](#Contact) | +### contact.refresh() ⇒ Promise.<this> +Force reload data for Contact +**Kind**: instance method of [Contact](#Contact) **Example** ```js -const bot = Wechaty.instance() -bot -.on('message', async m => { - const room = m.room() - const contact = m.from() - if (room) { - const alias = room.alias(contact) - console.log(`${contact.name()} alias is ${alias}`) - } -}) +await contact.refresh() ``` - - -### room.roomAlias(contact) ⇒ string \| null -Same as function alias + -**Kind**: instance method of [Room](#Room) +### contact.self() ⇒ boolean +Check if contact is self -| Param | Type | -| --- | --- | -| contact | [Contact](#Contact) | +**Kind**: instance method of [Contact](#Contact) +**Returns**: boolean - True for contact is self, False for contact is others +**Example** +```js +const isSelf = contact.self() +``` + - +### Contact.find(query) ⇒ Promise.<(Contact\|null)> +Try to find a contact by filter: {name: string | RegExp} / {alias: string | RegExp} -### room.has(contact) ⇒ boolean -Check if the room has member `contact`. +Find contact by name or alias, if the result more than one, return the first one. -**Kind**: instance method of [Room](#Room) -**Returns**: boolean - Return `true` if has contact, else return `false`. +**Kind**: static method of [Contact](#Contact) +**Returns**: Promise.<(Contact\|null)> - If can find the contact, return Contact, or return null | Param | Type | | --- | --- | -| contact | [Contact](#Contact) | +| query | [ContactQueryFilter](#ContactQueryFilter) | -**Example** *(Check whether 'lijiarui' is in the room 'wechaty')* +**Example** ```js -const contact = await Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of contact in your wechat -const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any of the room in your wechat -if (contact && room) { - if (room.has(contact)) { - console.log(`${contact.name()} is in the room ${room.topic()}!`) - } else { - console.log(`${contact.name()} is not in the room ${room.topic()} !`) - } -} +const contactFindByName = await Contact.find({ name:"ruirui"} ) +const contactFindByAlias = await Contact.find({ alias:"lijiarui"} ) ``` - - -### room.memberAll(queryArg) ⇒ [Array.<Contact>](#Contact) -Find all contacts in a room - -#### definition -- `name` the name-string set by user-self, should be called name, equal to `Contact.name()` -- `roomAlias` | `alias` the name-string set by user-self in the room, should be called roomAlias -- `contactAlias` the name-string set by bot for others, should be called alias, equal to `Contact.alias()` - -**Kind**: instance method of [Room](#Room) + -| Param | Type | Description | -| --- | --- | --- | -| queryArg | [MemberQueryFilter](#MemberQueryFilter) \| string | When use memberAll(name:string), return all matched members, including name, roomAlias, contactAlias | +### Contact.findAll([queryArg]) ⇒ Promise.<Array.<Contact>> +Find contact by `name` or `alias` - +If use Contact.findAll() get the contact list of the bot. -### room.member(queryArg) ⇒ [Contact](#Contact) \| null -Find all contacts in a room, if get many, return the first one. +#### definition +- `name` the name-string set by user-self, should be called name +- `alias` the name-string set by bot for others, should be called alias -**Kind**: instance method of [Room](#Room) +**Kind**: static method of [Contact](#Contact) -| Param | Type | Description | -| --- | --- | --- | -| queryArg | [MemberQueryFilter](#MemberQueryFilter) \| string | When use member(name:string), return all matched members, including name, roomAlias, contactAlias | +| Param | Type | +| --- | --- | +| [queryArg] | [ContactQueryFilter](#ContactQueryFilter) | -**Example** *(Find member by name)* -```js -const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat -if (room) { - const member = room.member('lijiarui') // change 'lijiarui' to any room member in your wechat - if (member) { - console.log(`${room.topic()} got the member: ${member.name()}`) - } else { - console.log(`cannot get member in room: ${room.topic()}`) - } -} -``` -**Example** *(Find member by MemberQueryFilter)* +**Example** ```js -const room = await Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat -if (room) { - const member = room.member({name: 'lijiarui'}) // change 'lijiarui' to any room member in your wechat - if (member) { - console.log(`${room.topic()} got the member: ${member.name()}`) - } else { - console.log(`cannot get member in room: ${room.topic()}`) - } -} +const contactList = await Contact.findAll() // get the contact list of the bot +const contactList = await Contact.findAll({name: 'ruirui'}) // find allof the contacts whose name is 'ruirui' +const contactList = await Contact.findAll({alias: 'lijiarui'}) // find all of the contacts whose alias is 'lijiarui' ``` - + + +## FriendRequest +Send, receive friend request, and friend confirmation events. -### room.memberList() ⇒ [Array.<Contact>](#Contact) -Get all room member from the room +1. send request +2. receive request(in friend event) +3. confirmation friendship(friend event) -**Kind**: instance method of [Room](#Room) - +[Example/Friend-Bot](https://github.com/Chatie/wechaty/blob/master/example/friend-bot.ts) -### room.refresh() ⇒ Promise.<void> -Force reload data for Room +**Kind**: global class -**Kind**: instance method of [Room](#Room) - +* [FriendRequest](#FriendRequest) + * [.send(contact, [hello])](#FriendRequest+send) ⇒ Promise.<boolean> + * [.accept()](#FriendRequest+accept) ⇒ Promise.<boolean> -### Room.create(contactList, [topic]) ⇒ [Promise.<Room>](#Room) -Create a new room. + -**Kind**: static method of [Room](#Room) +### friendRequest.send(contact, [hello]) ⇒ Promise.<boolean> +Send a new friend request -| Param | Type | -| --- | --- | -| contactList | [Array.<Contact>](#Contact) | -| [topic] | string | +**Kind**: instance method of [FriendRequest](#FriendRequest) +**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure. -**Example** *(Creat a room with 'lijiarui' and 'juxiaomi', the room topic is 'ding - created')* +| Param | Type | Default | +| --- | --- | --- | +| contact | [Contact](#Contact) | | +| [hello] | string | "'Hi'" | + +**Example** ```js -const helperContactA = await Contact.find({ name: 'lijiarui' }) // change 'lijiarui' to any contact in your wechat -const helperContactB = await Contact.find({ name: 'juxiaomi' }) // change 'juxiaomi' to any contact in your wechat -const contactList = [helperContactA, helperContactB] -console.log('Bot', 'contactList: %s', contactList.join(',')) -const room = await Room.create(contactList, 'ding') -console.log('Bot', 'createDingRoom() new ding room created: %s', room) -await room.topic('ding - created') -await room.say('ding - created') +const from = message.from() +const request = new FriendRequest() +request.send(from, 'hello~') ``` - + -### Room.findAll([query]) ⇒ Promise.<Array.<Room>> -Find room by topic, return all the matched room +### friendRequest.accept() ⇒ Promise.<boolean> +Accept a friend request -**Kind**: static method of [Room](#Room) +**Kind**: instance method of [FriendRequest](#FriendRequest) +**Returns**: Promise.<boolean> - Return a Promise, true for accept successful, false for failure. + + +## Message +All wechat messages will be encapsulated as a Message. + +`Message` is `Sayable`, +[Example/Ding-Dong-Bot](https://github.com/Chatie/wechaty/blob/master/example/ding-dong-bot.ts) + +**Kind**: global class + +* [Message](#Message) + * _instance_ + * [.say(textOrMedia, [replyTo])](#Message+say) ⇒ Promise.<any> + * [.from()](#Message+from) ⇒ [Contact](#Contact) + * [.room()](#Message+room) ⇒ [Room](#Room) \| null + * [.content()](#Message+content) ⇒ string + * [.type()](#Message+type) ⇒ [MsgType](#MsgType) + * [.typeSub()](#Message+typeSub) ⇒ [MsgType](#MsgType) + * [.typeApp()](#Message+typeApp) ⇒ [AppMsgType](#AppMsgType) + * [.typeEx()](#Message+typeEx) ⇒ [MsgType](#MsgType) + * [.self()](#Message+self) ⇒ boolean + * [.mentioned()](#Message+mentioned) ⇒ [Array.<Contact>](#Contact) + * [.to()](#Message+to) ⇒ [Contact](#Contact) \| null + * [.readyStream()](#Message+readyStream) ⇒ Promise.<Readable> + * _static_ + * [.find()](#Message.find) + * [.findAll()](#Message.findAll) + + + +### message.say(textOrMedia, [replyTo]) ⇒ Promise.<any> +Reply a Text or Media File message to the sender. + +**Kind**: instance method of [Message](#Message) +**See**: [Example/ding-dong-bot](https://github.com/Chatie/wechaty/blob/master/example/ding-dong-bot.ts) | Param | Type | | --- | --- | -| [query] | RoomQueryFilter | +| textOrMedia | string \| [MediaMessage](#MediaMessage) | +| [replyTo] | [Contact](#Contact) \| [Array.<Contact>](#Contact) | **Example** ```js -const roomList = await Room.findAll() // get the room list of the bot -const roomList = await Room.findAll({name: 'wechaty'}) // find all of the rooms with name 'wechaty' +const bot = Wechaty.instance() +bot +.on('message', async m => { + if (/^ding$/i.test(m.content())) { + await m.say('hello world') + console.log('Bot REPLY: hello world') + await m.say(new MediaMessage(__dirname + '/wechaty.png')) + console.log('Bot REPLY: Image') + } +}) ``` - + -### Room.find(query) ⇒ Promise.<(Room\|null)> -Try to find a room by filter: {topic: string | RegExp}. If get many, return the first one. +### message.from() ⇒ [Contact](#Contact) +Get the sender from a message. -**Kind**: static method of [Room](#Room) -**Returns**: Promise.<(Room\|null)> - If can find the room, return Room, or return null +**Kind**: instance method of [Message](#Message) + -| Param | Type | -| --- | --- | -| query | RoomQueryFilter | +### message.room() ⇒ [Room](#Room) \| null +Get the room from the message. +If the message is not in a room, then will return `null` - +**Kind**: instance method of [Message](#Message) + -## Wechaty -Main bot class. +### message.content() ⇒ string +Get the content of the message -[The World's Shortest ChatBot Code: 6 lines of JavaScript](#wechatyinstance) +**Kind**: instance method of [Message](#Message) + -[Wechaty Starter Project](https://github.com/lijiarui/wechaty-getting-started) +### message.type() ⇒ [MsgType](#MsgType) +Get the type from the message. -**Kind**: global class +If type is equal to `MsgType.RECALLED`, [Message#id](Message#id) is the msgId of the recalled message. -* [Wechaty](#Wechaty) - * _instance_ - * [.init()](#Wechaty+init) ⇒ Promise.<void> - * [.on(event, listener)](#Wechaty+on) ⇒ [Wechaty](#Wechaty) - * [.quit()](#Wechaty+quit) ⇒ Promise.<void> - * [.logout()](#Wechaty+logout) ⇒ Promise.<void> - * [.self()](#Wechaty+self) ⇒ [Contact](#Contact) - * [.say(content)](#Wechaty+say) ⇒ Promise.<boolean> - * _static_ - * [.instance()](#Wechaty.instance) - * [.version([forceNpm])](#Wechaty.version) ⇒ string +**Kind**: instance method of [Message](#Message) +**See**: [MsgType](#MsgType) + - +### message.typeSub() ⇒ [MsgType](#MsgType) +Get the typeSub from the message. -### wechaty.init() ⇒ Promise.<void> -Initialize the bot, return Promise. +If message is a location message: `m.type() === MsgType.TEXT && m.typeSub() === MsgType.LOCATION` -**Kind**: instance method of [Wechaty](#Wechaty) +**Kind**: instance method of [Message](#Message) +**See**: [MsgType](#MsgType) + + +### message.typeApp() ⇒ [AppMsgType](#AppMsgType) +Get the typeApp from the message. + +**Kind**: instance method of [Message](#Message) +**See**: [AppMsgType](#AppMsgType) + + +### message.typeEx() ⇒ [MsgType](#MsgType) +Get the typeEx from the message. + +**Kind**: instance method of [Message](#Message) + + +### message.self() ⇒ boolean +Check if a message is sent by self. + +**Kind**: instance method of [Message](#Message) +**Returns**: boolean - - Return `true` for send from self, `false` for send from others. **Example** ```js -await bot.init() -// do other stuff with bot here +if (message.self()) { + console.log('this message is sent by myself!') +} ``` - + -### wechaty.on(event, listener) ⇒ [Wechaty](#Wechaty) -**Kind**: instance method of [Wechaty](#Wechaty) -**Returns**: [Wechaty](#Wechaty) - - this for chain +### message.mentioned() ⇒ [Array.<Contact>](#Contact) +Get message mentioned contactList. -More Example Gist: [Example/Friend-Bot](https://github.com/wechaty/wechaty/blob/master/example/friend-bot.ts) +Message event table as follows -| Param | Type | Description | -| --- | --- | --- | -| event | WechatyEvent | Emit WechatyEvent | -| listener | [WechatyEventFunction](#WechatyEventFunction) | Depends on the WechatyEvent | +| | Web | Mac PC Client | iOS Mobile | android Mobile | +| :--- | :--: | :----: | :---: | :---: | +| [You were mentioned] tip ([有人@我]的提示) | ✘ | √ | √ | √ | +| Identify magic code (8197) by copy & paste in mobile | ✘ | √ | √ | ✘ | +| Identify magic code (8197) by programming | ✘ | ✘ | ✘ | ✘ | +| Identify two contacts with the same roomAlias by [You were mentioned] tip | ✘ | ✘ | √ | √ | -**Example** *(Event:scan )* -```js -wechaty.on('scan', (url: string, code: number) => { - console.log(`[${code}] Scan ${url} to login.` ) -}) -``` -**Example** *(Event:login )* -```js -bot.on('login', (user: Contact) => { - console.log(`user ${user} login`) -}) -``` -**Example** *(Event:logout )* -```js -bot.on('logout', (user: Contact) => { - console.log(`user ${user} logout`) -}) -``` -**Example** *(Event:message )* -```js -wechaty.on('message', (message: Message) => { - console.log(`message ${message} received`) -}) -``` -**Example** *(Event:friend )* -```js -bot.on('friend', (contact: Contact, request: FriendRequest) => { - if(request){ // 1. request to be friend from new contact - let result = await request.accept() - if(result){ - console.log(`Request from ${contact.name()} is accept succesfully!`) - } else{ - console.log(`Request from ${contact.name()} failed to accept!`) - } - } else { // 2. confirm friend ship - console.log(`new friendship confirmed with ${contact.name()}`) - } - }) -``` -**Example** *(Event:room-join )* -```js -bot.on('room-join', (room: Room, inviteeList: Contact[], inviter: Contact) => { - const nameList = inviteeList.map(c => c.name()).join(',') - console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`) -}) -``` -**Example** *(Event:room-leave )* -```js -bot.on('room-leave', (room: Room, leaverList: Contact[]) => { - const nameList = leaverList.map(c => c.name()).join(',') - console.log(`Room ${room.topic()} lost member ${nameList}`) -}) -``` -**Example** *(Event:room-topic )* +**Kind**: instance method of [Message](#Message) +**Returns**: [Array.<Contact>](#Contact) - - Return message mentioned contactList +**Example** ```js -bot.on('room-topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => { - console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`) -}) +const contactList = message.mentioned() +console.log(contactList) ``` - + + +### message.to() ⇒ [Contact](#Contact) \| null +Get the destination of the message +Message.to() will return null if a message is in a room, use Message.room() to get the room. -### wechaty.quit() ⇒ Promise.<void> -Quit the bot +**Kind**: instance method of [Message](#Message) + -**Kind**: instance method of [Wechaty](#Wechaty) -**Example** -```js -await bot.quit() -``` - +### message.readyStream() ⇒ Promise.<Readable> +Please notice that when we are running Wechaty, +if you use the browser that controlled by Wechaty to send attachment files, +you will get a zero sized file, because it is not an attachment from the network, +but a local data, which is not supported by Wechaty yet. -### wechaty.logout() ⇒ Promise.<void> -Logout the bot +**Kind**: instance method of [Message](#Message) + -**Kind**: instance method of [Wechaty](#Wechaty) +### Message.find() +**Kind**: static method of [Message](#Message) +**Todo** + +- [ ] add function + + + +### Message.findAll() +**Kind**: static method of [Message](#Message) +**Todo** + +- [ ] add function + + + +## MediaMessage +Meidia Type Message + +**Kind**: global class + +* [MediaMessage](#MediaMessage) + * [.ext()](#MediaMessage+ext) ⇒ string + * [.mimeType()](#MediaMessage+mimeType) + * [.filename()](#MediaMessage+filename) ⇒ string + * [.readyStream()](#MediaMessage+readyStream) + * [.saveFile(filePath)](#MediaMessage+saveFile) + * [.forward(to)](#MediaMessage+forward) ⇒ Promise.<boolean> + + + +### mediaMessage.ext() ⇒ string +Get the MediaMessage file extension, etc: `jpg`, `gif`, `pdf`, `word` .. + +**Kind**: instance method of [MediaMessage](#MediaMessage) **Example** ```js -await bot.logout() +bot.on('message', async function (m) { + if (m instanceof MediaMessage) { + console.log('media message file name extention is: ' + m.ext()) + } +}) ``` - + -### wechaty.self() ⇒ [Contact](#Contact) -Get current user +### mediaMessage.mimeType() +return the MIME Type of this MediaMessage -**Kind**: instance method of [Wechaty](#Wechaty) +**Kind**: instance method of [MediaMessage](#MediaMessage) + + +### mediaMessage.filename() ⇒ string +Get the MediaMessage filename, etc: `how to build a chatbot.pdf`.. + +**Kind**: instance method of [MediaMessage](#MediaMessage) **Example** ```js -const contact = bot.self() -console.log(`Bot is ${contact.name()}`) +bot.on('message', async function (m) { + if (m instanceof MediaMessage) { + console.log('media message file name is: ' + m.filename()) + } +}) ``` - + -### wechaty.say(content) ⇒ Promise.<boolean> -Send message to filehelper +### mediaMessage.readyStream() +Get the read stream for attachment file -**Kind**: instance method of [Wechaty](#Wechaty) +**Kind**: instance method of [MediaMessage](#MediaMessage) + -| Param | Type | +### mediaMessage.saveFile(filePath) +save file + +**Kind**: instance method of [MediaMessage](#MediaMessage) + +| Param | Description | | --- | --- | -| content | string | +| filePath | save file | - + -### Wechaty.instance() -get the singleton instance of Wechaty +### mediaMessage.forward(to) ⇒ Promise.<boolean> +Forward the received message. -**Kind**: static method of [Wechaty](#Wechaty) -**Example** *(The World's Shortest ChatBot Code: 6 lines of JavaScript)* -```js -const { Wechaty } = require('wechaty') +The types of messages that can be forwarded are as follows: -Wechaty.instance() // Singleton -.on('scan', (url, code) => console.log(`Scan QR Code to login: ${code}\n${url}`)) -.on('login', user => console.log(`User ${user} logined`)) -.on('message', message => console.log(`Message: ${message}`)) -.init() +The return value of [type](#Message+type) matches one of the following types: +``` +MsgType { + TEXT = 1, + IMAGE = 3, + VIDEO = 43, + EMOTICON = 47, + LOCATION = 48, + APP = 49, + MICROVIDEO = 62, +} ``` - - -### Wechaty.version([forceNpm]) ⇒ string -Return version of Wechaty -**Kind**: static method of [Wechaty](#Wechaty) -**Returns**: string - - the version number +When the return value of [type](#Message+type) is `MsgType.APP`, the return value of [typeApp](#Message+typeApp) matches one of the following types: +``` +AppMsgType { + TEXT = 1, + IMG = 2, + VIDEO = 4, + ATTACH = 6, + EMOJI = 8, +} +``` +It should be noted that when forwarding ATTACH type message, if the file size is greater than 25Mb, the forwarding will fail. +The reason is that the server shields the web wx to download more than 25Mb files with a file size of 0. -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| [forceNpm] | boolean | false | if set to true, will only return the version in package.json. otherwise will return git commit hash if .git exists. | +But if the file is uploaded by you using wechaty, you can forward it. +You need to detect the following conditions in the message event, which can be forwarded if it is met. -**Example** -```js -console.log(Wechaty.instance().version()) // return '#git[af39df]' -console.log(Wechaty.instance().version(true)) // return '0.7.9' +```javasrcipt +.on('message', async m => { + if (m.self() && m.rawObj && m.rawObj.Signature) { + // Filter the contacts you have forwarded + const msg = m + await msg.forward() + } +}) ``` + +**Kind**: instance method of [MediaMessage](#MediaMessage) + +| Param | Type | Description | +| --- | --- | --- | +| to | Sayable \| Array.<Sayable> | Room or Contact The recipient of the message, the room, or the contact | + ## FriendRequest @@ -1248,18 +1297,104 @@ Enum for Gender values. | Male | number | 1 for Male | | Female | number | 2 for Female | - + -## ContactQueryFilter -The way to search Contact +## AppMsgType : enum +Enum for AppMsgType values. + +**Kind**: global enum +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| TEXT | number | AppMsgType.TEXT (1) for TEXT | +| IMG | number | AppMsgType.IMG (2) for IMG | +| AUDIO | number | AppMsgType.AUDIO (3) for AUDIO | +| VIDEO | number | AppMsgType.VIDEO (4) for VIDEO | +| URL | number | AppMsgType.URL (5) for URL | +| ATTACH | number | AppMsgType.ATTACH (6) for ATTACH | +| OPEN | number | AppMsgType.OPEN (7) for OPEN | +| EMOJI | number | AppMsgType.EMOJI (8) for EMOJI | +| VOICE_REMIND | number | AppMsgType.VOICE_REMIND (9) for VOICE_REMIND | +| SCAN_GOOD | number | AppMsgType.SCAN_GOOD (10) for SCAN_GOOD | +| GOOD | number | AppMsgType.GOOD (13) for GOOD | +| EMOTION | number | AppMsgType.EMOTION (15) for EMOTION | +| CARD_TICKET | number | AppMsgType.CARD_TICKET (16) for CARD_TICKET | +| REALTIME_SHARE_LOCATION | number | AppMsgType.REALTIME_SHARE_LOCATION (17) for REALTIME_SHARE_LOCATION | +| TRANSFERS | number | AppMsgType.TRANSFERS (2e3) for TRANSFERS | +| RED_ENVELOPES | number | AppMsgType.RED_ENVELOPES (2001) for RED_ENVELOPES | +| READER_TYPE | number | AppMsgType.READER_TYPE (100001) for READER_TYPE | + + + +## MsgType : enum +Enum for MsgType values. + +**Kind**: global enum +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| TEXT | number | MsgType.TEXT (1) for TEXT | +| IMAGE | number | MsgType.IMAGE (3) for IMAGE | +| VOICE | number | MsgType.VOICE (34) for VOICE | +| VERIFYMSG | number | MsgType.VERIFYMSG (37) for VERIFYMSG | +| POSSIBLEFRIEND_MSG | number | MsgType.POSSIBLEFRIEND_MSG (40) for POSSIBLEFRIEND_MSG | +| SHARECARD | number | MsgType.SHARECARD (42) for SHARECARD | +| VIDEO | number | MsgType.VIDEO (43) for VIDEO | +| EMOTICON | number | MsgType.EMOTICON (47) for EMOTICON | +| LOCATION | number | MsgType.LOCATION (48) for LOCATION | +| APP | number | MsgType.APP (49) for APP | +| VOIPMSG | number | MsgType.VOIPMSG (50) for VOIPMSG | +| STATUSNOTIFY | number | MsgType.STATUSNOTIFY (51) for STATUSNOTIFY | +| VOIPNOTIFY | number | MsgType.VOIPNOTIFY (52) for VOIPNOTIFY | +| VOIPINVITE | number | MsgType.VOIPINVITE (53) for VOIPINVITE | +| MICROVIDEO | number | MsgType.MICROVIDEO (62) for MICROVIDEO | +| SYSNOTICE | number | MsgType.SYSNOTICE (9999) for SYSNOTICE | +| SYS | number | MsgType.SYS (10000) for SYS | +| RECALLED | number | MsgType.RECALLED (10002) for RECALLED | + + + +## WechatyEventName +Wechaty Class Event Type **Kind**: global typedef **Properties** | Name | Type | Description | | --- | --- | --- | -| name | string | The name-string set by user-self, should be called name | -| alias | string | The name-string set by bot for others, should be called alias [More Detail](https://github.com/Chatie/wechaty/issues/365) | +| error | string | When the bot get error, there will be a Wechaty error event fired. | +| login | string | After the bot login full successful, the event login will be emitted, with a Contact of current logined user. | +| logout | string | Logout will be emitted when bot detected log out, with a Contact of the current login user. | +| heartbeat | string | Get bot's heartbeat. | +| friend | string | When someone sends you a friend request, there will be a Wechaty friend event fired. | +| message | string | Emit when there's a new message. | +| room-join | string | Emit when anyone join any room. | +| room-topic | string | Get topic event, emitted when someone change room topic. | +| room-leave | string | Emit when anyone leave the room.
If someone leaves the room by themselves, wechat will not notice other people in the room, so the bot will never get the "leave" event. | +| scan | string | A scan event will be emitted when the bot needs to show you a QR Code for scanning. | + + + +## WechatyEventFunction +Wechaty Class Event Function + +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| error | function | (this: Wechaty, error: Error) => void callback function | +| login | function | (this: Wechaty, user: Contact)=> void | +| logout | function | (this: Wechaty, user: Contact) => void | +| scan | function | (this: Wechaty, url: string, code: number) => void
  1. URL: {String} the QR code image URL
  2. code: {Number} the scan status code. some known status of the code list here is:
  • 0 initial_
  • 200 login confirmed
  • 201 scaned, wait for confirm
  • 408 waits for scan
| +| heartbeat | function | (this: Wechaty, data: any) => void | +| friend | function | (this: Wechaty, friend: Contact, request?: FriendRequest) => void | +| message | function | (this: Wechaty, message: Message) => void | +| room-join | function | (this: Wechaty, room: Room, inviteeList: Contact[], inviter: Contact) => void | +| room-topic | function | (this: Wechaty, room: Room, topic: string, oldTopic: string, changer: Contact) => void | +| room-leave | function | (this: Wechaty, room: Room, leaverList: Contact[]) => void | @@ -1304,45 +1439,16 @@ The way to search member by Room.member() | roomAlias | string | Find the contact by alias set by the bot for others in a room. | | contactAlias | string | Find the contact by alias set by the contact out of a room, equal to `Contact.alias()`. [More Detail](https://github.com/Chatie/wechaty/issues/365) | - - -## WechatyEventName -Wechaty Class Event Type - -**Kind**: global typedef -**Properties** - -| Name | Type | Description | -| --- | --- | --- | -| error | string | When the bot get error, there will be a Wechaty error event fired. | -| login | string | After the bot login full successful, the event login will be emitted, with a Contact of current logined user. | -| logout | string | Logout will be emitted when bot detected log out, with a Contact of the current login user. | -| scan | string | A scan event will be emitted when the bot needs to show you a QR Code for scanning. | -| heartbeat | string | Get bot's heartbeat. | -| friend | string | When someone sends you a friend request, there will be a Wechaty friend event fired. | -| message | string | Emit when there's a new message. | -| room-join | string | Emit when anyone join any room. | -| room-topic | string | Get topic event, emitted when someone change room topic. | -| room-leave | string | Emit when anyone leave the room.
If someone leaves the room by themselves, wechat will not notice other people in the room, so the bot will never get the "leave" event. | - - + -## WechatyEventFunction -Wechaty Class Event Function +## ContactQueryFilter +The way to search Contact **Kind**: global typedef **Properties** | Name | Type | Description | | --- | --- | --- | -| error | function | (this: Wechaty, error: Error) => void callback function | -| login | function | (this: Wechaty, user: Contact)=> void | -| logout | function | (this: Wechaty, user: Contact) => void | -| scan | function | (this: Wechaty, url: string, code: number) => void
  1. URL: {String} the QR code image URL
  2. code: {Number} the scan status code. some known status of the code list here is:
  • 0 initial_
  • 200 login confirmed
  • 201 scaned, wait for confirm
  • 408 waits for scan
| -| heartbeat | function | (this: Wechaty, data: any) => void | -| friend | function | (this: Wechaty, friend: Contact, request?: FriendRequest) => void | -| message | function | (this: Wechaty, message: Message) => void | -| room-join | function | (this: Wechaty, room: Room, inviteeList: Contact[], inviter: Contact) => void | -| room-topic | function | (this: Wechaty, room: Room, topic: string, oldTopic: string, changer: Contact) => void | -| room-leave | function | (this: Wechaty, room: Room, leaverList: Contact[]) => void | +| name | string | The name-string set by user-self, should be called name | +| alias | string | The name-string set by bot for others, should be called alias [More Detail](https://github.com/Chatie/wechaty/issues/365) | diff --git a/package.json b/package.json index a1dd5de54..2f4e082e8 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "scripts": { "ts-node": "ts-node", "dist": "npm run clean && tsc && shx cp src/puppet-web/*.js dist/src/puppet-web/", - "doc": "npm run dist && echo '# Wechaty v'$(jq -r .version package.json)' Documentation\n' > docs/index.md && jsdoc2md dist/src/{wechaty,room,contact,friend-request,message}.js dist/src/puppet-web/friend-request.js>> docs/index.md", + "doc": "npm run dist && echo '# Wechaty v'$(jq -r .version package.json)' Documentation\n' > docs/index.md && jsdoc2md dist/src/{wechaty,room,contact,friend-request,message}.js dist/src/puppet-web/{friend-request,schema}.js>> docs/index.md", "coverage": "nyc report --reporter=text-lcov | coveralls", "changelog": "github_changelog_generator -u chatie -p wechaty && sed -i'.bak' /greenkeeper/d CHANGELOG.md && sed -i'.bak' '/An in-range update of/d' CHANGELOG.md && ts-node script/sort-contributiveness.ts < CHANGELOG.md > CHANGELOG.new.md 2>/dev/null && cat CHANGELOG.md >> CHANGELOG.new.md && mv CHANGELOG.new.md CHANGELOG.md", "doctor": "npm run check-node-version && ts-node bin/doctor", diff --git a/src/message.ts b/src/message.ts index 585f16e92..c467f9c59 100644 --- a/src/message.ts +++ b/src/message.ts @@ -938,7 +938,7 @@ export class MediaMessage extends Message { * The types of messages that can be forwarded are as follows: * * The return value of {@link Message#type} matches one of the following types: - * ```json + * ``` * MsgType { * TEXT = 1, * IMAGE = 3, @@ -951,7 +951,7 @@ export class MediaMessage extends Message { * ``` * * When the return value of {@link Message#type} is `MsgType.APP`, the return value of {@link Message#typeApp} matches one of the following types: - * ```json + * ``` * AppMsgType { * TEXT = 1, * IMG = 2,