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 - - Docs - @@ -25,6 +25,14 @@ It may equals

If you want to know how to get contact, see Contact

+
Room
+

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

+

Examples/Room-Bot

+
+
Contact
+

All wechat contacts(friend) will be encapsulated as a Contact. +Examples/Contact-Bot

+
ContactSelf

Bot itself will be encapsulated as a ContactSelf.

@@ -40,6 +48,13 @@ If you want to know how to get contact, see Contact

Examples/Friend-Bot

+
Message
+

All wechat messages will be encapsulated as a Message.

+

Examples/Ding-Dong-Bot

+
+
RoomInvitation
+

accept room invitation

+
## Typedefs @@ -108,7 +123,7 @@ See more: * [.logout()](#Wechaty+logout) ⇒ 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.
You can use [FileBox](https://www.npmjs.com/package/file-box) to send file | +| [mention] | [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 -
True for friend of the bot
+False for not friend of the bot, null for unknown. +**Example** +```js +const isFriend = contact.friend() +``` + + +### contact.type() ⇒ 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.
+ +For example, the message is sent at time `8:43:01`, +and when we received it in Wechaty, the time is `8:43:15`, +then the age() will return `8:43:15 - 8:43:01 = 14 (seconds)` + +**Kind**: instance method of [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.
+ +For example, the invitation is sent at time `8:43:01`, +and when we received it in Wechaty, the time is `8:43:15`, +then the age() will return `8:43:15 - 8:43:01 = 14 (seconds)` + +**Kind**: instance method of [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.
- 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. | -| room-invite | 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
see more in [RoomInvitation](RoomInvitation) | +| room-invite | function | (this: Wechaty, room: Room, roomInvitation: RoomInvitation) => void
see more in [RoomInvitation](#RoomInvitation) | diff --git a/package.json b/package.json index 5f04a2dfa17e01da4facf2fcc3c4d98bfe2296c1..21be505abfc584416a3c04d4fd0785372eb1d44a 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "clean": "shx rm -fr dist/*", "dist": "npm run clean && npm run build", "pack": "npm pack", - "doc": "bash -x scripts/generate-docs.sh", + "docs": "bash -x scripts/generate-docs.sh", "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 scripts/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", @@ -95,7 +95,6 @@ "qr-image": "^3.2.0", "raven": "^2.6.2", "read-pkg-up": "^6.0.0", - "semver": "^6.0.0", "state-switch": "^0.6.2", "watchdog": "^0.8.1", "wechaty-puppet": "^0.17.2", @@ -107,6 +106,7 @@ "@babel/preset-env": "^7.0.0", "@chatie/eslint-config": "^0.8.1", "@chatie/git-scripts": "^0.2.3", + "@chatie/semver": "^0.4.7", "@chatie/tsconfig": "^0.6.1", "@types/blessed": "^0.1.10", "@types/cuid": "^1.3.0", @@ -120,7 +120,6 @@ "@types/raven": "^2.1.0", "@types/request": "^2.47.1", "@types/retry": "^0.12.0", - "@types/semver": "^6.0.0", "@types/sinon": "^7.0.4", "@types/ws": "^6.0.0", "apiai": "^4.0.0", diff --git a/scripts/generate-docs.sh b/scripts/generate-docs.sh index 6e65a6c829a9a76d3a235145cc8101e9eb4b758f..a62c625182da553663d1be9ed1e1751279f84773 100755 --- a/scripts/generate-docs.sh +++ b/scripts/generate-docs.sh @@ -1,14 +1,21 @@ #!/usr/bin/env bash set -e -npm version +VERSION=$(npx pkg-jq -r .version) +echo "Version $VERSION" -if [ "$1" != "-f" ] && ./scripts/development-release.ts; then +if ! npx --package @chatie/semver semver-is-prod $VERSION; then echo "Current release is a development release, please only update the docs when there's a stable release." - exit 1 -else - echo "Generating docs ..." - npm run dist - echo -e '# Wechaty v'$(jq -r .version package.json)' Documentation\n\n- Blog - \n- Docs - \n\n' > docs/index.md - jsdoc2md dist/src/wechaty.js dist/src/user/{room,contact,contact-self,friendship,message,room-invitation}.js >> docs/index.md + + if [ "$1" != "-f" ]; then + echo "Or use -f to force generating." + exit 1 + else + echo "-f found. Forcing generating ..." + fi fi + +echo "Generating docs ..." +npm run dist +echo -e '# Wechaty v'$(jq -r .version package.json)' Documentation\n\n- Blog - \n- Docs - \n\n' > docs/index.md +jsdoc2md dist/src/wechaty.js dist/src/user/{room,contact,contact-self,friendship,message,room-invitation}.js >> docs/index.md