diff --git a/docs/index.md b/docs/index.md
index 0eba9de819224434c1be82d669e371a02cd56f7e..0248235dd4d9137561a1e8dea2b127066be37fa5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,4 +1,4 @@
-# Wechaty v0.27.39 Documentation
+# Wechaty v0.29.5 Documentation
- Blog -
All wechat rooms(groups) will be encapsulated as a Room.
+ +All wechat contacts(friend) will be encapsulated as a Contact. +Examples/Contact-Bot
+Bot itself will be encapsulated as a ContactSelf.
@@ -40,6 +48,13 @@ If you want to know how to get contact, see Contact
All wechat messages will be encapsulated as a Message.
+ +accept room invitation
+Promise.<void>
* [.logonoff()](#Wechaty+logonoff) ⇒ boolean
* [.userSelf()](#Wechaty+userSelf) ⇒ [ContactSelf
](#ContactSelf)
- * [.say(textOrContactOrFileOrUrlOrMini)](#Wechaty+say) ⇒ Promise.<void>
+ * [.say(something)](#Wechaty+say) ⇒ Promise.<void>
* _static_
* [.instance([options])](#Wechaty.instance)
@@ -310,7 +325,7 @@ console.log(`Bot is ${contact.name()}`)
```
-### wechaty.say(textOrContactOrFileOrUrlOrMini) ⇒ Promise.<void>
+### wechaty.say(something) ⇒ Promise.<void>
Send message to userSelf, in other words, bot send message to itself.
> Tips:
This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
@@ -319,7 +334,7 @@ This function is depending on the Puppet Implementation, see [puppet-compatible-
| Param | Type | Description |
| --- | --- | --- |
-| textOrContactOrFileOrUrlOrMini | string
\| Contact
\| FileBox
\| UrlLink
\| MiniProgram
| send text, Contact, or file to bot. You can use [FileBox](https://www.npmjs.com/package/file-box) to send file |
+| something | string
\| [Contact
](#Contact) \| FileBox
\| UrlLink
\| MiniProgram
| send text, Contact, or file to bot. You can use [FileBox](https://www.npmjs.com/package/file-box) to send file |
**Example**
```js
@@ -354,15 +369,15 @@ const linkPayload = new UrlLink ({
await bot.say(linkPayload)
// 6. send MiniProgram to bot itself
-const miniProgramPayload = new MiniProgram ({
- username : 'gh_xxxxxxx', //get from mp.weixin.qq.com
- appid : '', //optional, get from mp.weixin.qq.com
- title : '', //optional
- pagepath : '', //optional
- description : '', //optional
- thumbnailurl : '', //optional
+const miniPayload = new MiniProgram ({
+ username : 'gh_xxxxxxx', //get from mp.weixin.qq.com
+ appid : '', //optional, get from mp.weixin.qq.com
+ title : '', //optional
+ pagepath : '', //optional
+ description : '', //optional
+ thumbnailurl : '', //optional
})
-await bot.say(miniProgramPayload)
+await bot.say(miniPayload)
```
@@ -385,238 +400,1503 @@ Wechaty.instance() // Global instance
.on('message', message => console.log(`Message: ${message}`))
.start()
```
-
+
-## ContactSelf
-Bot itself will be encapsulated as a ContactSelf.
+## Room
+All wechat rooms(groups) will be encapsulated as a Room.
-> Tips: this class is extends Contact
+[Examples/Room-Bot](https://github.com/Chatie/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/room-bot.ts)
**Kind**: global class
+**Properties**
-* [ContactSelf](#ContactSelf)
- * [.avatar([file])](#ContactSelf+avatar) ⇒ Promise.<(void\|FileBox)>
- * [.qrcode()](#ContactSelf+qrcode) ⇒ Promise.<string>
- * [.signature(signature)](#ContactSelf+signature)
+| Name | Type | Description |
+| --- | --- | --- |
+| id | string
| Room id. This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table) |
-
-### contactSelf.avatar([file]) ⇒ Promise.<(void\|FileBox)>
-GET / SET bot avatar
+* [Room](#Room)
+ * _instance_
+ * [.sync()](#Room+sync) ⇒ Promise.<void>
+ * [.say(textOrContactOrFileOrUrlOrMini, [mention])](#Room+say) ⇒ Promise.<(void\|Message)>
+ * [.on(event, listener)](#Room+on) ⇒ this
+ * [.add(contact)](#Room+add) ⇒ Promise.<void>
+ * [.del(contact)](#Room+del) ⇒ Promise.<void>
+ * [.quit()](#Room+quit) ⇒ Promise.<void>
+ * [.topic([newTopic])](#Room+topic) ⇒ Promise.<(string\|void)>
+ * [.announce([text])](#Room+announce) ⇒ Promise.<(void\|string)>
+ * [.qrcode()](#Room+qrcode) ⇒ Promise.<string>
+ * [.alias(contact)](#Room+alias) ⇒ Promise.<(string\|null)>
+ * [.has(contact)](#Room+has) ⇒ Promise.<boolean>
+ * [.memberAll([query])](#Room+memberAll) ⇒ Promise.<Array.<Contact>>
+ * [.member(queryArg)](#Room+member) ⇒ Promise.<(null\|Contact)>
+ * [.owner()](#Room+owner) ⇒ [Contact
](#Contact) \| null
+ * _static_
+ * [.create(contactList, [topic])](#Room.create) ⇒ [Promise.<Room>
](#Room)
+ * [.findAll([query])](#Room.findAll) ⇒ Promise.<Array.<Room>>
+ * [.find(query)](#Room.find) ⇒ Promise.<(Room\|null)>
-**Kind**: instance method of [ContactSelf
](#ContactSelf)
+
-| Param | Type |
-| --- | --- |
-| [file] | FileBox
|
+### room.sync() ⇒ Promise.<void>
+Force reload data for Room, Sync data from lowlevel API again.
-**Example** *( GET the avatar for bot, return {Promise<FileBox>})*
+**Kind**: instance method of [Room
](#Room)
+**Example**
```js
-// Save avatar to local file like `1-name.jpg`
-
-bot.on('login', (user: ContactSelf) => {
- console.log(`user ${user} login`)
- const file = await user.avatar()
- const name = file.name
- await file.toFile(name, true)
- console.log(`Save bot avatar: ${contact.name()} with avatar file: ${name}`)
-})
+await room.sync()
```
-**Example** *(SET the avatar for a bot)*
+
+
+### room.say(textOrContactOrFileOrUrlOrMini, [mention]) ⇒ Promise.<(void\|Message)>
+Send message inside Room, if set [replyTo], wechaty will mention the contact as well.
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Room
](#Room)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| textOrContactOrFileOrUrlOrMini | string
\| [Contact
](#Contact) \| FileBox
| Send `text` or `media file` inside Room. Contact
](#Contact) \| [Array.<Contact>
](#Contact) | Optional parameter, send content inside Room, and mention @replyTo contact or contactList. |
+
+**Example**
```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'wechaty'})
+
+// 1. Send text inside Room
+
+await room.say('Hello world!')
+const msg = await room.say('Hello world!') // only supported by puppet-padplus
+
+// 2. Send media file inside Room
import { FileBox } from 'file-box'
-bot.on('login', (user: ContactSelf) => {
- console.log(`user ${user} login`)
- const fileBox = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
- await user.avatar(fileBox)
- console.log(`Change bot avatar successfully!`)
+const fileBox1 = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
+const fileBox2 = FileBox.fromLocal('/tmp/text.txt')
+await room.say(fileBox1)
+const msg1 = await room.say(fileBox1) // only supported by puppet-padplus
+await room.say(fileBox2)
+const msg2 = await room.say(fileBox2) // only supported by puppet-padplus
+
+// 3. Send Contact Card in a room
+const contactCard = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member
+await room.say(contactCard)
+const msg = await room.say(contactCard) // only supported by puppet-padplus
+
+// 4. Send text inside room and mention @mention contact
+const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of the room member
+await room.say('Hello world!', contact)
+const msg = await room.say('Hello world!', contact) // only supported by puppet-padplus
+
+// 5. Send text inside room and mention someone with Tagged Template
+const contact2 = await bot.Contact.find({name: 'zixia'}) // change 'zixia' to any of the room member
+await room.say`Hello ${contact}, here is the world ${contact2}`
+const msg = await room.say`Hello ${contact}, here is the world ${contact2}` // only supported by puppet-padplus
+
+// 6. send url link in a room
+
+const urlLink = new UrlLink ({
+ description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love',
+ thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4',
+ title : 'Welcome to Wechaty',
+ url : 'https://github.com/chatie/wechaty',
+})
+await room.say(urlLink)
+const msg = await room.say(urlLink) // only supported by puppet-padplus
+
+// 7. send mini program in a room
+
+const miniProgram = new MiniProgram ({
+ username : 'gh_xxxxxxx', //get from mp.weixin.qq.com
+ appid : '', //optional, get from mp.weixin.qq.com
+ title : '', //optional
+ pagepath : '', //optional
+ description : '', //optional
+ thumbnailurl : '', //optional
})
+await room.say(miniProgram)
+const msg = await room.say(miniProgram) // only supported by puppet-padplus
```
-
+
-### contactSelf.qrcode() ⇒ Promise.<string>
-Get bot qrcode
+### room.on(event, listener) ⇒ this
+**Kind**: instance method of [Room
](#Room)
+**Returns**: this
- - this for chain
-**Kind**: instance method of [ContactSelf
](#ContactSelf)
-**Example**
+| Param | Type | Description |
+| --- | --- | --- |
+| event | [RoomEventName
](#RoomEventName) | Emit WechatyEvent |
+| listener | [RoomEventFunction
](#RoomEventFunction) | Depends on the WechatyEvent |
+
+**Example** *(Event:join )*
```js
-import { generate } from 'qrcode-terminal'
-bot.on('login', (user: ContactSelf) => {
- console.log(`user ${user} login`)
- const qrcode = await user.qrcode()
- console.log(`Following is the bot qrcode!`)
- generate(qrcode, { small: true })
-})
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat
+if (room) {
+ room.on('join', (room, inviteeList, inviter) => {
+ const nameList = inviteeList.map(c => c.name()).join(',')
+ console.log(`Room got new member ${nameList}, invited by ${inviter}`)
+ })
+}
```
-
+**Example** *(Event:leave )*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat
+if (room) {
+ room.on('leave', (room, leaverList) => {
+ const nameList = leaverList.map(c => c.name()).join(',')
+ console.log(`Room lost member ${nameList}`)
+ })
+}
+```
+**Example** *(Event:topic )*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat
+if (room) {
+ room.on('topic', (room, topic, oldTopic, changer) => {
+ console.log(`Room topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
+ })
+}
+```
+**Example** *(Event:invite )*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'topic of your room'}) // change `event-room` to any room topic in your wechat
+if (room) {
+ room.on('invite', roomInvitation => roomInvitation.accept())
+}
+```
+
-### contactSelf.signature(signature)
-Change bot signature
+### room.add(contact) ⇒ Promise.<void>
+Add contact in a room
-**Kind**: instance method of [ContactSelf
](#ContactSelf)
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+>
+> see [Web version of WeChat closed group interface](https://github.com/Chatie/wechaty/issues/1441)
-| Param | Description |
+**Kind**: instance method of [Room
](#Room)
+
+| Param | Type |
| --- | --- |
-| signature | The new signature that the bot will change to |
+| contact | [Contact
](#Contact) |
**Example**
```js
-bot.on('login', async user => {
- console.log(`user ${user} login`)
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any contact in your wechat
+const room = await bot.Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat
+if (room) {
try {
- await user.signature(`Signature changed by wechaty on ${new Date()}`)
- } catch (e) {
- console.error('change signature failed', e)
+ await room.add(contact)
+ } catch(e) {
+ console.error(e)
}
-})
+}
```
-
+
-## Friendship
-Send, receive friend request, and friend confirmation events.
+### room.del(contact) ⇒ Promise.<void>
+Delete a contact from the room
+It works only when the bot is the owner of the room
-1. send request
-2. receive request(in friend event)
-3. confirmation friendship(friend event)
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+>
+> see [Web version of WeChat closed group interface](https://github.com/Chatie/wechaty/issues/1441)
-[Examples/Friend-Bot](https://github.com/Chatie/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/friend-bot.ts)
+**Kind**: instance method of [Room
](#Room)
-**Kind**: global class
+| Param | Type |
+| --- | --- |
+| contact | [Contact
](#Contact) |
-* [Friendship](#Friendship)
- * _instance_
- * [.accept()](#Friendship+accept) ⇒ Promise.<void>
- * [.hello()](#Friendship+hello) ⇒ string
- * [.contact()](#Friendship+contact) ⇒ Contact
- * [.type()](#Friendship+type) ⇒ FriendshipType
- * _static_
- * ~~[.send()](#Friendship.send)~~
- * [.add(contact, hello)](#Friendship.add) ⇒ Promise.<void>
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'wechat'}) // change 'wechat' to any room topic in your wechat
+const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any room member in the room you just set
+if (room) {
+ try {
+ await room.del(contact)
+ } catch(e) {
+ console.error(e)
+ }
+}
+```
+
-
+### room.quit() ⇒ Promise.<void>
+Bot quit the room itself
-### friendship.accept() ⇒ Promise.<void>
-Accept Friend Request
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
-**Kind**: instance method of [Friendship
](#Friendship)
+**Kind**: instance method of [Room
](#Room)
**Example**
```js
-const bot = new Wechaty()
-bot.on('friendship', async friendship => {
- try {
- console.log(`received friend event.`)
- switch (friendship.type()) {
+await room.quit()
+```
+
- // 1. New Friend Request
+### room.topic([newTopic]) ⇒ Promise.<(string\|void)>
+SET/GET topic from the room
- case Friendship.Type.Receive:
- await friendship.accept()
- break
+**Kind**: instance method of [Room
](#Room)
- // 2. Friend Ship Confirmed
+| Param | Type | Description |
+| --- | --- | --- |
+| [newTopic] | string
| If set this para, it will change room topic. |
- case Friendship.Type.Confirm:
- console.log(`friend ship confirmed`)
- break
- }
- } catch (e) {
- console.error(e)
+**Example** *(When you say anything in a room, it will get room topic. )*
+```js
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+ const room = m.room()
+ if (room) {
+ const topic = await room.topic()
+ console.log(`room topic is : ${topic}`)
}
-}
+})
.start()
```
-
-
-### friendship.hello() ⇒ string
-Get verify message from
-
-**Kind**: instance method of [Friendship
](#Friendship)
-**Example** *(If request content is `ding`, then accept the friendship)*
+**Example** *(When you say anything in a room, it will change room topic. )*
```js
const bot = new Wechaty()
-bot.on('friendship', async friendship => {
- try {
- console.log(`received friend event from ${friendship.contact().name()}`)
- if (friendship.type() === Friendship.Type.Receive && friendship.hello() === 'ding') {
- await friendship.accept()
- }
- } catch (e) {
- console.error(e)
+bot
+.on('message', async m => {
+ const room = m.room()
+ if (room) {
+ const oldTopic = await room.topic()
+ await room.topic('change topic to wechaty!')
+ console.log(`room topic change from ${oldTopic} to ${room.topic()}`)
}
-}
+})
.start()
```
-
+
-### friendship.contact() ⇒ Contact
-Get the contact from friendship
+### room.announce([text]) ⇒ Promise.<(void\|string)>
+SET/GET announce from the room
+> Tips: It only works when bot is the owner of the room.
+>
+> This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
-**Kind**: instance method of [Friendship
](#Friendship)
-**Example**
+**Kind**: instance method of [Room
](#Room)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [text] | string
| If set this para, it will change room announce. |
+
+**Example** *(When you say anything in a room, it will get room announce. )*
```js
const bot = new Wechaty()
-bot.on('friendship', async friendship => {
- const contact = friendship.contact()
- const name = contact.name()
- console.log(`received friend event from ${name}`)
-}
-.start()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'your room'})
+const announce = await room.announce()
+console.log(`room announce is : ${announce}`)
```
-
+**Example** *(When you say anything in a room, it will change room announce. )*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'your room'})
+const oldAnnounce = await room.announce()
+await room.announce('change announce to wechaty!')
+console.log(`room announce change from ${oldAnnounce} to ${room.announce()}`)
+```
+
-### friendship.type() ⇒ FriendshipType
-Return the Friendship Type
-> Tips: FriendshipType is enum here.
-- FriendshipType.Unknown
-- FriendshipType.Confirm
-- FriendshipType.Receive
-- FriendshipType.Verify
+### room.qrcode() ⇒ Promise.<string>
+Get QR Code of the Room from the room, which can be used as scan and join the room.
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
-**Kind**: instance method of [Friendship
](#Friendship)
-**Example** *(If request content is `ding`, then accept the friendship)*
+**Kind**: instance method of [Room
](#Room)
+
+
+### room.alias(contact) ⇒ Promise.<(string\|null)>
+Return contact's roomAlias in the room
+
+**Kind**: instance method of [Room
](#Room)
+**Returns**: Promise.<(string\|null)>
- - If a contact has an alias in room, return string, otherwise return null
+
+| Param | Type |
+| --- | --- |
+| contact | [Contact
](#Contact) |
+
+**Example**
```js
const bot = new Wechaty()
-bot.on('friendship', async friendship => {
- try {
- if (friendship.type() === Friendship.Type.Receive && friendship.hello() === 'ding') {
- await friendship.accept()
- }
- } catch (e) {
- console.error(e)
+bot
+.on('message', async m => {
+ const room = m.room()
+ const contact = m.from()
+ if (room) {
+ const alias = await room.alias(contact)
+ console.log(`${contact.name()} alias is ${alias}`)
}
-}
+})
.start()
```
-
+
-### ~~Friendship.send()~~
-***Deprecated***
+### room.has(contact) ⇒ Promise.<boolean>
+Check if the room has member `contact`, the return is a Promise and must be `await`-ed
-use [Friendship#add](Friendship#add) instead
+**Kind**: instance method of [Room
](#Room)
+**Returns**: Promise.<boolean>
- Return `true` if has contact, else return `false`.
-**Kind**: static method of [Friendship
](#Friendship)
-
+| Param | Type |
+| --- | --- |
+| contact | [Contact
](#Contact) |
-### Friendship.add(contact, hello) ⇒ Promise.<void>
-Send a Friend Request to a `contact` with message `hello`.
+**Example** *(Check whether 'lijiarui' is in the room 'wechaty')*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of contact in your wechat
+const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any of the room in your wechat
+if (contact && room) {
+ if (await room.has(contact)) {
+ console.log(`${contact.name()} is in the room wechaty!`)
+ } else {
+ console.log(`${contact.name()} is not in the room wechaty!`)
+ }
+}
+```
+
-The best practice is to send friend request once per minute.
-Remeber not to do this too frequently, or your account may be blocked.
+### room.memberAll([query]) ⇒ Promise.<Array.<Contact>>
+Find all contacts in a room
-**Kind**: static method of [Friendship
](#Friendship)
+#### definition
+- `name` the name-string set by user-self, should be called name, equal to `Contact.name()`
+- `roomAlias` 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 |
| --- | --- | --- |
-| contact | Contact
| Send friend request to contact |
-| hello | string
| The friend request content |
+| [query] | [RoomMemberQueryFilter
](#RoomMemberQueryFilter) \| string
| Optional parameter, When use memberAll(name:string), return all matched members, including name, roomAlias, contactAlias |
**Example**
```js
-const memberList = await room.memberList()
-for (let i = 0; i < memberList.length; i++) {
+const roomList:Conatct[] | null = await room.findAll()
+if(roomList)
+ console.log(`room all member list: `, roomList)
+const memberContactList: Conatct[] | null =await room.findAll(`abc`)
+console.log(`contact list with all name, room alias, alias are abc:`, memberContactList)
+```
+
+
+### room.member(queryArg) ⇒ Promise.<(null\|Contact)>
+Find all contacts in a room, if get many, return the first one.
+
+**Kind**: instance method of [Room
](#Room)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| queryArg | [RoomMemberQueryFilter
](#RoomMemberQueryFilter) \| string
| When use member(name:string), return all matched members, including name, roomAlias, contactAlias |
+
+**Example** *(Find member by name)*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat
+if (room) {
+ const member = await room.member('lijiarui') // change 'lijiarui' to any room member in your wechat
+ if (member) {
+ console.log(`wechaty room got the member: ${member.name()}`)
+ } else {
+ console.log(`cannot get member in wechaty room!`)
+ }
+}
+```
+**Example** *(Find member by MemberQueryFilter)*
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const room = await bot.Room.find({topic: 'wechaty'}) // change 'wechaty' to any room name in your wechat
+if (room) {
+ const member = await room.member({name: 'lijiarui'}) // change 'lijiarui' to any room member in your wechat
+ if (member) {
+ console.log(`wechaty room got the member: ${member.name()}`)
+ } else {
+ console.log(`cannot get member in wechaty room!`)
+ }
+}
+```
+
+
+### room.owner() ⇒ [Contact
](#Contact) \| null
+Get room's owner from the room.
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Room
](#Room)
+**Example**
+```js
+const owner = room.owner()
+```
+
+
+### Room.create(contactList, [topic]) ⇒ [Promise.<Room>
](#Room)
+Create a new room.
+
+**Kind**: static method of [Room
](#Room)
+
+| Param | Type |
+| --- | --- |
+| contactList | [Array.<Contact>
](#Contact) |
+| [topic] | string
|
+
+**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')
+```
+
+
+### Room.findAll([query]) ⇒ Promise.<Array.<Room>>
+Find room by by filter: {topic: string | RegExp}, return all the matched room
+
+**Kind**: static method of [Room
](#Room)
+
+| Param | Type |
+| --- | --- |
+| [query] | [RoomQueryFilter
](#RoomQueryFilter) |
+
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in
+const roomList = await bot.Room.findAll() // get the room list of the bot
+const roomList = await bot.Room.findAll({topic: 'wechaty'}) // find all of the rooms with name 'wechaty'
+```
+
+
+### Room.find(query) ⇒ Promise.<(Room\|null)>
+Try to find a room by filter: {topic: string | RegExp}. If get many, return the first one.
+
+**Kind**: static method of [Room
](#Room)
+**Returns**: Promise.<(Room\|null)>
- If can find the room, return Room, or return null
+
+| Param | Type |
+| --- | --- |
+| query | [RoomQueryFilter
](#RoomQueryFilter) |
+
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+// after logged in...
+const roomList = await bot.Room.find()
+const roomList = await bot.Room.find({topic: 'wechaty'})
+```
+
+
+## Contact
+All wechat contacts(friend) will be encapsulated as a Contact.
+[Examples/Contact-Bot](https://github.com/Chatie/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/contact-bot.ts)
+
+**Kind**: global class
+**Properties**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| id | string
| Get Contact id. This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table) |
+
+
+* [Contact](#Contact)
+ * _instance_
+ * [.say(something)](#Contact+say) ⇒ Promise.<(void\|Message)>
+ * [.name()](#Contact+name) ⇒ string
+ * [.alias(newAlias)](#Contact+alias) ⇒ Promise.<(null\|string\|void)>
+ * [.friend()](#Contact+friend) ⇒ boolean
\| null
+ * [.type()](#Contact+type) ⇒ ContactType.Unknown
\| ContactType.Personal
\| ContactType.Official
+ * [.gender()](#Contact+gender) ⇒ ContactGender.Unknown
\| ContactGender.Male
\| ContactGender.Female
+ * [.province()](#Contact+province) ⇒ string
\| null
+ * [.city()](#Contact+city) ⇒ string
\| null
+ * [.avatar()](#Contact+avatar) ⇒ Promise.<FileBox>
+ * [.sync()](#Contact+sync) ⇒ Promise.<this>
+ * [.self()](#Contact+self) ⇒ boolean
+ * _static_
+ * [.find(query)](#Contact.find) ⇒ Promise.<(Contact\|null)>
+ * [.findAll([queryArg])](#Contact.findAll) ⇒ Promise.<Array.<Contact>>
+
+
+
+### contact.say(something) ⇒ Promise.<(void\|Message)>
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Contact
](#Contact)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| something | string
\| [Contact
](#Contact) \| FileBox
\| UrlLink
\| MiniProgram
| send text, Contact, or file to contact. You can use [FileBox](https://www.npmjs.com/package/file-box) to send file |
+
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+const contact = await bot.Contact.find({name: 'lijiarui'}) // change 'lijiarui' to any of your contact name in wechat
+
+// 1. send text to contact
+
+await contact.say('welcome to wechaty!')
+const msg = await contact.say('welcome to wechaty!') // only supported by puppet-padplus
+
+// 2. send media file to contact
+
+import { FileBox } from 'file-box'
+const fileBox1 = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
+const fileBox2 = FileBox.fromFile('/tmp/text.txt')
+await contact.say(fileBox1)
+const msg1 = await contact.say(fileBox1) // only supported by puppet-padplus
+await contact.say(fileBox2)
+const msg2 = await contact.say(fileBox2) // only supported by puppet-padplus
+
+// 3. send contact card to contact
+
+const contactCard = bot.Contact.load('contactId')
+const msg = await contact.say(contactCard) // only supported by puppet-padplus
+
+// 4. send url link to contact
+
+const urlLink = new UrlLink ({
+ description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love',
+ thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4',
+ title : 'Welcome to Wechaty',
+ url : 'https://github.com/chatie/wechaty',
+})
+await contact.say(urlLink)
+const msg = await contact.say(urlLink) // only supported by puppet-padplus
+
+// 5. send mini program to contact
+
+const miniProgram = new MiniProgram ({
+ username : 'gh_xxxxxxx', //get from mp.weixin.qq.com
+ appid : '', //optional, get from mp.weixin.qq.com
+ title : '', //optional
+ pagepath : '', //optional
+ description : '', //optional
+ thumbnailurl : '', //optional
+})
+await contact.say(miniProgram)
+const msg = await contact.say(miniProgram) // only supported by puppet-padplus
+```
+
+
+### contact.name() ⇒ string
+Get the name from a contact
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+const name = contact.name()
+```
+
+
+### contact.alias(newAlias) ⇒ Promise.<(null\|string\|void)>
+GET / SET / DELETE the alias for a contact
+
+Tests show it will failed if set alias too frequently(60 times in one minute).
+
+**Kind**: instance method of [Contact
](#Contact)
+
+| Param | Type |
+| --- | --- |
+| newAlias | none
\| string
\| null
|
+
+**Example** *( GET the alias for a contact, return {(Promise<string | null>)})*
+```js
+const alias = await 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** *(SET the alias for a contact)*
+```js
+try {
+ await contact.alias('lijiarui')
+ console.log(`change ${contact.name()}'s alias successfully!`)
+} catch (e) {
+ console.log(`failed to change ${contact.name()} alias!`)
+}
+```
+**Example** *(DELETE the alias for a contact)*
+```js
+try {
+ const oldAlias = await contact.alias(null)
+ console.log(`delete ${contact.name()}'s alias successfully!`)
+ console.log('old alias is ${oldAlias}`)
+} catch (e) {
+ console.log(`failed to delete ${contact.name()}'s alias!`)
+}
+```
+
+
+### contact.friend() ⇒ boolean
\| null
+Check if contact is friend
+
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Contact
](#Contact)
+**Returns**: boolean
\| null
- ContactType.Unknown
\| ContactType.Personal
\| ContactType.Official
+Return the type of the Contact
+> Tips: ContactType is enum here.
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+const isOfficial = contact.type() === bot.Contact.Type.Official
+```
+
+
+### contact.gender() ⇒ ContactGender.Unknown
\| ContactGender.Male
\| ContactGender.Female
+Contact gender
+> Tips: ContactGender is enum here.
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+const gender = contact.gender() === bot.Contact.Gender.Male
+```
+
+
+### contact.province() ⇒ string
\| null
+Get the region 'province' from a contact
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+const province = contact.province()
+```
+
+
+### contact.city() ⇒ string
\| null
+Get the region 'city' from a contact
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+const city = contact.city()
+```
+
+
+### contact.avatar() ⇒ Promise.<FileBox>
+Get avatar picture file stream
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+// Save avatar to local file like `1-name.jpg`
+
+const file = await contact.avatar()
+const name = file.name
+await file.toFile(name, true)
+console.log(`Contact: ${contact.name()} with avatar file: ${name}`)
+```
+
+
+### contact.sync() ⇒ Promise.<this>
+Force reload data for Contact, Sync data from lowlevel API again.
+
+**Kind**: instance method of [Contact
](#Contact)
+**Example**
+```js
+await contact.sync()
+```
+
+
+### contact.self() ⇒ boolean
+Check if contact is self
+
+**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}
+
+Find contact by name or alias, if the result more than one, return the first one.
+
+**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) |
+
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+const contactFindByName = await bot.Contact.find({ name:"ruirui"} )
+const contactFindByAlias = await bot.Contact.find({ alias:"lijiarui"} )
+```
+
+
+### Contact.findAll([queryArg]) ⇒ Promise.<Array.<Contact>>
+Find contact by `name` or `alias`
+
+If use Contact.findAll() get the contact list of the bot.
+
+#### 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**: static method of [Contact
](#Contact)
+
+| Param | Type |
+| --- | --- |
+| [queryArg] | [ContactQueryFilter
](#ContactQueryFilter) |
+
+**Example**
+```js
+const bot = new Wechaty()
+await bot.start()
+const contactList = await bot.Contact.findAll() // get the contact list of the bot
+const contactList = await bot.Contact.findAll({ name: 'ruirui' }) // find allof the contacts whose name is 'ruirui'
+const contactList = await bot.Contact.findAll({ alias: 'lijiarui' }) // find all of the contacts whose alias is 'lijiarui'
+```
+
+
+## ContactSelf
+Bot itself will be encapsulated as a ContactSelf.
+
+> Tips: this class is extends Contact
+
+**Kind**: global class
+
+* [ContactSelf](#ContactSelf)
+ * [.avatar([file])](#ContactSelf+avatar) ⇒ Promise.<(void\|FileBox)>
+ * [.qrcode()](#ContactSelf+qrcode) ⇒ Promise.<string>
+ * [.signature(signature)](#ContactSelf+signature)
+
+
+
+### contactSelf.avatar([file]) ⇒ Promise.<(void\|FileBox)>
+GET / SET bot avatar
+
+**Kind**: instance method of [ContactSelf
](#ContactSelf)
+
+| Param | Type |
+| --- | --- |
+| [file] | FileBox
|
+
+**Example** *( GET the avatar for bot, return {Promise<FileBox>})*
+```js
+// Save avatar to local file like `1-name.jpg`
+
+bot.on('login', (user: ContactSelf) => {
+ console.log(`user ${user} login`)
+ const file = await user.avatar()
+ const name = file.name
+ await file.toFile(name, true)
+ console.log(`Save bot avatar: ${contact.name()} with avatar file: ${name}`)
+})
+```
+**Example** *(SET the avatar for a bot)*
+```js
+import { FileBox } from 'file-box'
+bot.on('login', (user: ContactSelf) => {
+ console.log(`user ${user} login`)
+ const fileBox = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
+ await user.avatar(fileBox)
+ console.log(`Change bot avatar successfully!`)
+})
+```
+
+
+### contactSelf.qrcode() ⇒ Promise.<string>
+Get bot qrcode
+
+**Kind**: instance method of [ContactSelf
](#ContactSelf)
+**Example**
+```js
+import { generate } from 'qrcode-terminal'
+bot.on('login', (user: ContactSelf) => {
+ console.log(`user ${user} login`)
+ const qrcode = await user.qrcode()
+ console.log(`Following is the bot qrcode!`)
+ generate(qrcode, { small: true })
+})
+```
+
+
+### contactSelf.signature(signature)
+Change bot signature
+
+**Kind**: instance method of [ContactSelf
](#ContactSelf)
+
+| Param | Description |
+| --- | --- |
+| signature | The new signature that the bot will change to |
+
+**Example**
+```js
+bot.on('login', async user => {
+ console.log(`user ${user} login`)
+ try {
+ await user.signature(`Signature changed by wechaty on ${new Date()}`)
+ } catch (e) {
+ console.error('change signature failed', e)
+ }
+})
+```
+
+
+## Friendship
+Send, receive friend request, and friend confirmation events.
+
+1. send request
+2. receive request(in friend event)
+3. confirmation friendship(friend event)
+
+[Examples/Friend-Bot](https://github.com/Chatie/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/friend-bot.ts)
+
+**Kind**: global class
+
+* [Friendship](#Friendship)
+ * _instance_
+ * [.accept()](#Friendship+accept) ⇒ Promise.<void>
+ * [.hello()](#Friendship+hello) ⇒ string
+ * [.contact()](#Friendship+contact) ⇒ [Contact
](#Contact)
+ * [.type()](#Friendship+type) ⇒ FriendshipType
+ * _static_
+ * ~~[.send()](#Friendship.send)~~
+ * [.add(contact, hello)](#Friendship.add) ⇒ Promise.<void>
+
+
+
+### friendship.accept() ⇒ Promise.<void>
+Accept Friend Request
+
+**Kind**: instance method of [Friendship
](#Friendship)
+**Example**
+```js
+const bot = new Wechaty()
+bot.on('friendship', async friendship => {
+ try {
+ console.log(`received friend event.`)
+ switch (friendship.type()) {
+
+ // 1. New Friend Request
+
+ case Friendship.Type.Receive:
+ await friendship.accept()
+ break
+
+ // 2. Friend Ship Confirmed
+
+ case Friendship.Type.Confirm:
+ console.log(`friend ship confirmed`)
+ break
+ }
+ } catch (e) {
+ console.error(e)
+ }
+}
+.start()
+```
+
+
+### friendship.hello() ⇒ string
+Get verify message from
+
+**Kind**: instance method of [Friendship
](#Friendship)
+**Example** *(If request content is `ding`, then accept the friendship)*
+```js
+const bot = new Wechaty()
+bot.on('friendship', async friendship => {
+ try {
+ console.log(`received friend event from ${friendship.contact().name()}`)
+ if (friendship.type() === Friendship.Type.Receive && friendship.hello() === 'ding') {
+ await friendship.accept()
+ }
+ } catch (e) {
+ console.error(e)
+ }
+}
+.start()
+```
+
+
+### friendship.contact() ⇒ [Contact
](#Contact)
+Get the contact from friendship
+
+**Kind**: instance method of [Friendship
](#Friendship)
+**Example**
+```js
+const bot = new Wechaty()
+bot.on('friendship', async friendship => {
+ const contact = friendship.contact()
+ const name = contact.name()
+ console.log(`received friend event from ${name}`)
+}
+.start()
+```
+
+
+### friendship.type() ⇒ FriendshipType
+Return the Friendship Type
+> Tips: FriendshipType is enum here.
+- FriendshipType.Unknown
+- FriendshipType.Confirm
+- FriendshipType.Receive
+- FriendshipType.Verify
+
+**Kind**: instance method of [Friendship
](#Friendship)
+**Example** *(If request content is `ding`, then accept the friendship)*
+```js
+const bot = new Wechaty()
+bot.on('friendship', async friendship => {
+ try {
+ if (friendship.type() === Friendship.Type.Receive && friendship.hello() === 'ding') {
+ await friendship.accept()
+ }
+ } catch (e) {
+ console.error(e)
+ }
+}
+.start()
+```
+
+
+### ~~Friendship.send()~~
+***Deprecated***
+
+use [Friendship#add](Friendship#add) instead
+
+**Kind**: static method of [Friendship
](#Friendship)
+
+
+### Friendship.add(contact, hello) ⇒ Promise.<void>
+Send a Friend Request to a `contact` with message `hello`.
+
+The best practice is to send friend request once per minute.
+Remeber not to do this too frequently, or your account may be blocked.
+
+**Kind**: static method of [Friendship
](#Friendship)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| contact | [Contact
](#Contact) | Send friend request to contact |
+| hello | string
| The friend request content |
+
+**Example**
+```js
+const memberList = await room.memberList()
+for (let i = 0; i < memberList.length; i++) {
await bot.Friendship.add(member, 'Nice to meet you! I am wechaty bot!')
}
```
+
+
+## Message
+All wechat messages will be encapsulated as a Message.
+
+[Examples/Ding-Dong-Bot](https://github.com/Chatie/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/ding-dong-bot.ts)
+
+**Kind**: global class
+
+* [Message](#Message)
+ * _instance_
+ * [.from()](#Message+from) ⇒ [Contact
](#Contact)
+ * [.to()](#Message+to) ⇒ [Contact
](#Contact) \| null
+ * [.room()](#Message+room) ⇒ [Room
](#Room) \| null
+ * ~~[.content()](#Message+content)~~
+ * [.text()](#Message+text) ⇒ string
+ * [.toRecalled()](#Message+toRecalled)
+ * [.say(textOrContactOrFile, [mention])](#Message+say) ⇒ Promise.<(void\|Message)>
+ * [.type()](#Message+type) ⇒ MessageType
+ * [.self()](#Message+self) ⇒ boolean
+ * [.mention()](#Message+mention) ⇒ Promise.<Array.<Contact>>
+ * [.mentionSelf()](#Message+mentionSelf) ⇒ Promise.<boolean>
+ * [.forward(to)](#Message+forward) ⇒ Promise.<void>
+ * [.date()](#Message+date)
+ * [.age()](#Message+age) ⇒ number
+ * ~~[.file()](#Message+file)~~
+ * [.toFileBox()](#Message+toFileBox) ⇒ Promise.<FileBox>
+ * [.toContact()](#Message+toContact) ⇒ [Promise.<Contact>
](#Contact)
+ * _static_
+ * [.find()](#Message.find)
+ * [.findAll()](#Message.findAll)
+
+
+
+### message.from() ⇒ [Contact
](#Contact)
+Get the sender from a message.
+
+**Kind**: instance method of [Message
](#Message)
+**Example**
+```js
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+ const contact = msg.from()
+ const text = msg.text()
+ const room = msg.room()
+ if (room) {
+ const topic = await room.topic()
+ console.log(`Room: ${topic} Contact: ${contact.name()} Text: ${text}`)
+ } else {
+ console.log(`Contact: ${contact.name()} Text: ${text}`)
+ }
+})
+.start()
+```
+
+
+### 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.
+
+**Kind**: instance method of [Message
](#Message)
+
+
+### 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)
+**Example**
+```js
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+ const contact = msg.from()
+ const text = msg.text()
+ const room = msg.room()
+ if (room) {
+ const topic = await room.topic()
+ console.log(`Room: ${topic} Contact: ${contact.name()} Text: ${text}`)
+ } else {
+ console.log(`Contact: ${contact.name()} Text: ${text}`)
+ }
+})
+.start()
+```
+
+
+### ~~message.content()~~
+***Deprecated***
+
+use [text](#Message+text) instead
+
+**Kind**: instance method of [Message
](#Message)
+
+
+### message.text() ⇒ string
+Get the text content of the message
+
+**Kind**: instance method of [Message
](#Message)
+**Example**
+```js
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+ const contact = msg.from()
+ const text = msg.text()
+ const room = msg.room()
+ if (room) {
+ const topic = await room.topic()
+ console.log(`Room: ${topic} Contact: ${contact.name()} Text: ${text}`)
+ } else {
+ console.log(`Contact: ${contact.name()} Text: ${text}`)
+ }
+})
+.start()
+```
+
+
+### message.toRecalled()
+Get the recalled message
+
+**Kind**: instance method of [Message
](#Message)
+**Example**
+```js
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+ if (m.type() === MessageType.Recalled) {
+ const recalledMessage = await m.toRecalled()
+ console.log(`Message: ${recalledMessage} has been recalled.`)
+ }
+})
+.start()
+```
+
+
+### message.say(textOrContactOrFile, [mention]) ⇒ Promise.<(void\|Message)>
+Reply a Text or Media File message to the sender.
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Message
](#Message)
+**See**: [Examples/ding-dong-bot](https://github.com/Chatie/wechaty/blob/1523c5e02be46ebe2cc172a744b2fbe53351540e/examples/ding-dong-bot.ts)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| textOrContactOrFile | string
\| [Contact
](#Contact) \| FileBox
\| UrlLink
\| MiniProgram
| send text, Contact, or file to bot. You can use [FileBox](https://www.npmjs.com/package/file-box) to send file |
+| [mention] | [Contact
](#Contact) \| [Array.<Contact>
](#Contact) | If this is a room message, when you set mention param, you can `@` Contact in the room. |
+
+**Example**
+```js
+import { FileBox } from 'file-box'
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+
+// 1. send Image
+
+ if (/^ding$/i.test(m.text())) {
+ const fileBox = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
+ await msg.say(fileBox)
+ const message = await msg.say(fileBox) // only supported by puppet-padplus
+ }
+
+// 2. send Text
+
+ if (/^dong$/i.test(m.text())) {
+ await msg.say('dingdingding')
+ const message = await msg.say('dingdingding') // only supported by puppet-padplus
+ }
+
+// 3. send Contact
+
+ if (/^lijiarui$/i.test(m.text())) {
+ const contactCard = await bot.Contact.find({name: 'lijiarui'})
+ if (!contactCard) {
+ console.log('not found')
+ return
+ }
+ await msg.say(contactCard)
+ const message = await msg.say(contactCard) // only supported by puppet-padplus
+ }
+
+// 4. send Link
+
+ if (/^link$/i.test(m.text())) {
+ const linkPayload = new UrlLink ({
+ description : 'WeChat Bot SDK for Individual Account, Powered by TypeScript, Docker, and Love',
+ thumbnailUrl: 'https://avatars0.githubusercontent.com/u/25162437?s=200&v=4',
+ title : 'Welcome to Wechaty',
+ url : 'https://github.com/chatie/wechaty',
+ })
+ await msg.say(linkPayload)
+ const message = await msg.say(linkPayload) // only supported by puppet-padplus
+ }
+
+// 5. send MiniProgram
+
+ if (/^link$/i.test(m.text())) {
+ const miniProgramPayload = new MiniProgram ({
+ username : 'gh_xxxxxxx', //get from mp.weixin.qq.com
+ appid : '', //optional, get from mp.weixin.qq.com
+ title : '', //optional
+ pagepath : '', //optional
+ description : '', //optional
+ thumbnailurl : '', //optional
+ })
+ await msg.say(miniProgramPayload)
+ const message = await msg.say(miniProgramPayload) // only supported by puppet-padplus
+ }
+
+})
+.start()
+```
+
+
+### message.type() ⇒ MessageType
+Get the type from the message.
+> Tips: MessageType is Enum here.
+- MessageType.Unknown
+- MessageType.Attachment
+- MessageType.Audio
+- MessageType.Contact
+- MessageType.Emoticon
+- MessageType.Image
+- MessageType.Text
+- MessageType.Video
+- MessageType.Url
+
+**Kind**: instance method of [Message
](#Message)
+**Example**
+```js
+const bot = new Wechaty()
+if (message.type() === bot.Message.Type.Text) {
+ console.log('This is a text 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
+if (message.self()) {
+ console.log('this message is sent by myself!')
+}
+```
+
+
+### message.mention() ⇒ Promise.<Array.<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**: Promise.<Array.<Contact>>
- - Return message mentioned contactList
+**Example**
+```js
+const contactList = await message.mention()
+console.log(contactList)
+```
+
+
+### message.mentionSelf() ⇒ Promise.<boolean>
+Check if a message is mention self.
+
+**Kind**: instance method of [Message
](#Message)
+**Returns**: Promise.<boolean>
- - Return `true` for mention me.
+**Example**
+```js
+if (await message.mentionSelf()) {
+ console.log('this message were mentioned me! [You were mentioned] tip ([有人@我]的提示)')
+}
+```
+
+
+### message.forward(to) ⇒ Promise.<void>
+Forward the received message.
+
+**Kind**: instance method of [Message
](#Message)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| to | Sayable
\| Array.<Sayable>
| Room or Contact The recipient of the message, the room, or the contact |
+
+**Example**
+```js
+const bot = new Wechaty()
+bot
+.on('message', async m => {
+ const room = await bot.Room.find({topic: 'wechaty'})
+ if (room) {
+ await m.forward(room)
+ console.log('forward this message to wechaty room!')
+ }
+})
+.start()
+```
+
+
+### message.date()
+Message sent date
+
+**Kind**: instance method of [Message
](#Message)
+
+
+### message.age() ⇒ number
+Returns the message age in seconds. Message
](#Message)
+
+
+### ~~message.file()~~
+***Deprecated***
+
+use [toFileBox](#Message+toFileBox) instead
+
+**Kind**: instance method of [Message
](#Message)
+
+
+### message.toFileBox() ⇒ Promise.<FileBox>
+Extract the Media File from the Message, and put it into the FileBox.
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Message
](#Message)
+**Example** *(Save media file from a message)*
+```js
+const fileBox = await message.toFileBox()
+const fileName = fileBox.name
+fileBox.toFile(fileName)
+```
+
+
+### message.toContact() ⇒ [Promise.<Contact>
](#Contact)
+Get Share Card of the Message
+Extract the Contact Card from the Message, and encapsulate it into Contact class
+> Tips:
+This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/Chatie/wechaty/wiki/Puppet#3-puppet-compatible-table)
+
+**Kind**: instance method of [Message
](#Message)
+
+
+### Message.find()
+Find message in cache
+
+**Kind**: static method of [Message
](#Message)
+
+
+### Message.findAll()
+Find messages in cache
+
+**Kind**: static method of [Message
](#Message)
+
+
+## RoomInvitation
+accept room invitation
+
+**Kind**: global class
+
+* [RoomInvitation](#RoomInvitation)
+ * [.accept()](#RoomInvitation+accept) ⇒ Promise.<void>
+ * [.inviter()](#RoomInvitation+inviter) ⇒ [Contact
](#Contact)
+ * [.topic()](#RoomInvitation+topic) ⇒ [Contact
](#Contact)
+ * [.roomTopic()](#RoomInvitation+roomTopic)
+ * [.date()](#RoomInvitation+date) ⇒ Promise.<Date>
+ * [.age()](#RoomInvitation+age) ⇒ number
+
+
+
+### roomInvitation.accept() ⇒ Promise.<void>
+Accept Room Invitation
+
+**Kind**: instance method of [RoomInvitation
](#RoomInvitation)
+**Example**
+```js
+const bot = new Wechaty()
+bot.on('room-invite', async roomInvitation => {
+ try {
+ console.log(`received room-invite event.`)
+ await roomInvitation.accept()
+ } catch (e) {
+ console.error(e)
+ }
+}
+.start()
+```
+
+
+### roomInvitation.inviter() ⇒ [Contact
](#Contact)
+Get the inviter from room invitation
+
+**Kind**: instance method of [RoomInvitation
](#RoomInvitation)
+**Example**
+```js
+const bot = new Wechaty()
+bot.on('room-invite', async roomInvitation => {
+ const inviter = await roomInvitation.inviter()
+ const name = inviter.name()
+ console.log(`received room invitation event from ${name}`)
+}
+.start()
+```
+
+
+### roomInvitation.topic() ⇒ [Contact
](#Contact)
+Get the room topic from room invitation
+
+**Kind**: instance method of [RoomInvitation
](#RoomInvitation)
+**Example**
+```js
+const bot = new Wechaty()
+bot.on('room-invite', async roomInvitation => {
+ const topic = await roomInvitation.topic()
+ console.log(`received room invitation event from room ${topic}`)
+}
+.start()
+```
+
+
+### roomInvitation.roomTopic()
+**Kind**: instance method of [RoomInvitation
](#RoomInvitation)
+**Deprecated:**: use topic() instead
+
+
+### roomInvitation.date() ⇒ Promise.<Date>
+Get the invitation time
+
+**Kind**: instance method of [RoomInvitation
](#RoomInvitation)
+
+
+### roomInvitation.age() ⇒ number
+Returns the roopm invitation age in seconds. RoomInvitation
](#RoomInvitation)
## PuppetModuleName
@@ -672,7 +1952,7 @@ Wechaty Class Event Type
| 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.string
| Emit when there is a room invitation, see more in [RoomInvitation](RoomInvitation) |
+| room-invite | string
| Emit when there is a room invitation, see more in [RoomInvitation](#RoomInvitation) |
| scan | string
| A scan event will be emitted when the bot needs to show you a QR Code for scanning. It is recommend to install qrcode-terminal(run `npm install qrcode-terminal`) in order to show qrcode in the terminal. |
@@ -696,7 +1976,7 @@ Wechaty Class Event Function
| room-join | function
| (this: Wechaty, room: Room, inviteeList: Contact[], inviter: Contact) => void |
| room-topic | function
| (this: Wechaty, room: Room, newTopic: string, oldTopic: string, changer: Contact) => void |
| room-leave | function
| (this: Wechaty, room: Room, leaverList: Contact[]) => void |
-| room-invite | function
| (this: Wechaty, room: Room, leaverList: Contact[]) => void function
| (this: Wechaty, room: Room, roomInvitation: RoomInvitation) => void