The term Puppet in Wechaty is an Abstract Class for implementing protocol plugins. The plugins are the component that helps Wechaty to control the Wechat(that's the reason we call it puppet). The plugins are named XXXPuppet, for example:

WechatyOptions

The option parameter to create a wechaty instance

WechatyEventName

Wechaty Class Event Type

WechatyEventFunction

Wechaty Class Event Function

RoomQueryFilter

The filter to find the room: {topic: string | RegExp}

RoomEventName

Room Class Event Type

RoomEventFunction

Room Class Event Function

RoomMemberQueryFilter

The way to search member by Room.member()

ContactQueryFilter

The way to search Contact

Wechaty

Main bot class.

A Bot is a wechat client depends on which puppet you use. It may equals

web-wechat, when you use: puppet-puppeteer/puppet-wechat4u
ipad-wechat, when you use: puppet-padchat
ios-wechat, when you use: puppet-ioscat

See more:

What is a Puppet in Wechaty

If you want to know how to send message, see Message
If you want to know how to get contact, see Contact

Kind: global class

Wechaty
- new Wechaty([options])
- instance
  - .on(event, listener) ⇒ Wechaty
  - ~~.init()~~
  - .start() ⇒ Promise.<void>
  - .stop() ⇒ Promise.<void>
  - .logout() ⇒ Promise.<void>
  - .logonoff() ⇒ boolean
  - ~~.self()~~
  - .userSelf() ⇒ ContactSelf
  - .say(textOrContactOrFile) ⇒ Promise.<void>
- static
  - .instance([options])

new Wechaty([options])

Creates an instance of Wechaty.

Param	Type	Default
[options]	`WechatyOptions`	`{}`

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

const { Wechaty } = require('wechaty')
const bot = new Wechaty()
bot.on('scan',    (qrcode, status) => console.log(['https://api.qrserver.com/v1/create-qr-code/?data=',encodeURIComponent(qrcode),'&size=220x220&margin=20',].join('')))
bot.on('login',   user => console.log(`User ${user} logined`))
bot.on('message', message => console.log(`Message: ${message}`))
bot.start()

wechaty.on(event, listener) ⇒ `Wechaty`

When the bot get message, it will emit the following Event.

You can do anything you want when in these events functions. The main Event name as follows:

scan: Emit when the bot needs to show you a QR Code for scanning. After scan the qrcode, you can login
login: Emit when bot login full successful.
logout: Emit when bot detected log out.
message: Emit when there's a new message.

see more in WechatyEventName

Kind: instance method of Wechaty
Returns: Wechaty - - this for chaining, see advanced chaining usage

Param	Type	Description
event	`WechatyEventName`	Emit WechatyEvent
listener	`WechatyEventFunction`	Depends on the WechatyEvent

Example (Event:scan)

# Scan Event will emit when the bot needs to show you a QR Code for scanning

bot.on('scan', (url: string, code: number) => {
  console.log(`[${code}] Scan ${url} to login.` )
})

Example (Event:login )

# Login Event will emit when bot login full successful.

bot.on('login', (user: ContactSelf) => {
  console.log(`user ${user} login`)
})

Example (Event:logout )

# Logout Event will emit when bot detected log out.

bot.on('logout', (user: ContactSelf) => {
  console.log(`user ${user} logout`)
})

Example (Event:message )

# Message Event will emit when there's a new message.

wechaty.on('message', (message: Message) => {
  console.log(`message ${message} received`)
})

Example (Event:friendship )

# Friendship Event will emit when got a new friend request, or friendship is confirmed.

bot.on('friendship', (friendship: Friendship) => {
  if(friendship.type() === Friendship.Type.RECEIVE){ // 1. receive new friendship request from new contact
    const contact = friendship.contact()
    let result = await friendship.accept()
      if(result){
        console.log(`Request from ${contact.name()} is accept succesfully!`)
      } else{
        console.log(`Request from ${contact.name()} failed to accept!`)
      }
	  } else if (friendship.type() === Friendship.Type.CONFIRM) { // 2. confirm friendship
      console.log(`new friendship confirmed with ${contact.name()}`)
   }
 })

Example (Event:room-join )

# room-join Event will emit when someone join the room.

bot.on('room-join', (room: Room, inviteeList: Contact[], inviter: Contact) => {
  const nameList = inviteeList.map(c => c.name()).join(',')
  console.log(`Room ${room.topic()} got new member ${nameList}, invited by ${inviter}`)
})

Example (Event:room-leave )

# room-leave Event will emit when someone leave the room.

bot.on('room-leave', (room: Room, leaverList: Contact[]) => {
  const nameList = leaverList.map(c => c.name()).join(',')
  console.log(`Room ${room.topic()} lost member ${nameList}`)
})

Example (Event:room-topic )

# room-topic Event will emit when someone change the room's topic.

bot.on('room-topic', (room: Room, topic: string, oldTopic: string, changer: Contact) => {
  console.log(`Room ${room.topic()} topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
})

Example (Event:error )

# error Event will emit when there's an error occurred.

bot.on('error', (error) => {
  console.error(error)
})

wechaty.init()

Deprecated

use start instead

Kind: instance method of Wechaty

wechaty.start() ⇒ `Promise.<void>`

When you start the bot, bot will begin to login, need you wechat scan qrcode to login

Tips: All the bot operation needs to be triggered after start() is done

Kind: instance method of Wechaty
Example

await bot.start()
// do other stuff with bot here

wechaty.stop() ⇒ `Promise.<void>`

Stop the bot

Kind: instance method of Wechaty
Example

await bot.stop()

wechaty.logout() ⇒ `Promise.<void>`

Logout the bot

Kind: instance method of Wechaty
Example

await bot.logout()

wechaty.logonoff() ⇒ `boolean`

Get the logon / logoff state

Kind: instance method of Wechaty
Example

if (bot.logonoff()) {
  console.log('Bot logined')
} else {
  console.log('Bot not logined')
}

wechaty.self()

Deprecated

Should use userSelf instead

Kind: instance method of Wechaty

wechaty.userSelf() ⇒ `ContactSelf`

Get current user

Kind: instance method of Wechaty
Example

const contact = bot.userSelf()
console.log(`Bot is ${contact.name()}`)

wechaty.say(textOrContactOrFile) ⇒ `Promise.<void>`

Send message to userSelf, in other words, bot send message to itself.

Kind: instance method of Wechaty

Param	Type	Description
textOrContactOrFile	`string` \| `Contact` \| `FileBox`	send text, Contact, or file to bot. You can use FileBox to send file

Example

const bot = new Wechaty()
await bot.start()
// after logged in

# 1. send text to bot itself
await bot.say('hello!')

# 2. send Contact to bot itself
const contact = bot.Contact.load('contactId')
await bot.say(contact)

# 3. send Image to bot itself from remote url
import { FileBox }  from 'file-box'
const fileBox = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
await bot.say(fileBox)

# 4. send Image to bot itself from local file
import { FileBox }  from 'file-box'
const fileBox = FileBox.fromLocal('/tmp/text.jpg')
await bot.say(fileBox)

Wechaty.instance([options])

get the singleton instance of Wechaty

Kind: static method of Wechaty

Param	Type	Default
[options]	`WechatyOptions`	`{}`

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

const { Wechaty } = require('wechaty')

Wechaty.instance() // Singleton
.on('scan', (url, code) => console.log(`Scan QR Code to login: ${code}\n${url}`))
.on('login',       user => console.log(`User ${user} logined`))
.on('message',  message => console.log(`Message: ${message}`))
.start()

Room

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

Examples/Room-Bot

Kind: global class

Room
- instance
  - .say(textOrContactOrFile, [mention]) ⇒ Promise.<void>
  - .on(event, listener) ⇒ this
  - .add(contact) ⇒ Promise.<void>
  - .del(contact) ⇒ Promise.<void>
  - .quit() ⇒ Promise.<void>
  - .topic([newTopic]) ⇒ Promise.<(string|void)>
  - .announce([text]) ⇒ Promise.<(void|string)>
  - .qrcode() ⇒ Promise.<string>
  - .alias(contact) ⇒ Promise.<(string|null)>
  - .roomAlias(contact) ⇒ Promise.<(string|null)>
  - .has(contact) ⇒ Promise.<boolean>
  - .memberAll(query) ⇒ Promise.<Array.<Contact>>
  - .member(queryArg) ⇒ Promise.<(null|Contact)>
  - .memberList() ⇒ Promise.<Array.<Contact>>
  - .sync() ⇒ Promise.<void>
  - .owner() ⇒ Contact | null
- static
  - .create(contactList, [topic]) ⇒ Promise.<Room>
  - .findAll([query]) ⇒ Promise.<Array.<Room>>
  - .find(query) ⇒ Promise.<(Room|null)>
  - .load(id) ⇒ Room

room.say(textOrContactOrFile, [mention]) ⇒ `Promise.<void>`

Send message inside Room, if set [replyTo], wechaty will mention the contact as well.

Kind: instance method of Room

Param	Type	Description
textOrContactOrFile	`string` \| `Contact` \| `FileBox`	Send `text` or `media file` inside Room. You can use FileBox to send file
[mention]	`Contact` \| `Array.<Contact>`	Optional parameter, send content inside Room, and mention @replyTo contact or contactList.

Example

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!')

# 2. Send media file inside Room
import { FileBox }  from 'file-box'
const fileBox1 = FileBox.fromUrl('https://chatie.io/wechaty/images/bot-qr-code.png')
const fileBox2 = FileBox.fromLocal('/tmp/text.txt')
await room.say(fileBox1)
await room.say(fileBox2)

# 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)

# 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)

room.on(event, listener) ⇒ `this`

Kind: instance method of Room
Returns: this - - this for chain

Param	Type	Description
event	`RoomEventName`	Emit WechatyEvent
listener	`RoomEventFunction`	Depends on the WechatyEvent

Example (Event:join )

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: Room, inviteeList: Contact[], inviter: Contact) => {
    const nameList = inviteeList.map(c => c.name()).join(',')
    console.log(`Room got new member ${nameList}, invited by ${inviter}`)
  })
}

Example (Event:leave )

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: Room, leaverList: Contact[]) => {
    const nameList = leaverList.map(c => c.name()).join(',')
    console.log(`Room lost member ${nameList}`)
  })
}

Example (Event:topic )

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: Room, topic: string, oldTopic: string, changer: Contact) => {
    console.log(`Room topic changed from ${oldTopic} to ${topic} by ${changer.name()}`)
  })
}

room.add(contact) ⇒ `Promise.<void>`

Add contact in a room

Kind: instance method of Room

Param	Type
contact	`Contact`

Example

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 room.add(contact)
  } catch(e) {
     console.error(e)
  }
}

room.del(contact) ⇒ `Promise.<void>`

Delete a contact from the room It works only when the bot is the owner of the room

Kind: instance method of Room

Param	Type
contact	`Contact`

Example

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

Kind: instance method of Room
Example

await room.quit()

room.topic([newTopic]) ⇒ `Promise.<(string|void)>`

SET/GET topic from the room

Kind: instance method of Room

Param	Type	Description
[newTopic]	`string`	If set this para, it will change room topic.

Example (When you say anything in a room, it will get room topic. )

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()

Example (When you say anything in a room, it will change room topic. )

const bot = new Wechaty()
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()

room.announce([text]) ⇒ `Promise.<(void|string)>`

SET/GET announce from the room

Tips: It only works when bot is the owner of the room.

Kind: instance method of 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. )

const bot = new Wechaty()
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. )

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()}`)

room.qrcode() ⇒ `Promise.<string>`

Get QR Code of the Room from the room, which can be used as scan and join the room.

Kind: instance method of Room

room.alias(contact) ⇒ `Promise.<(string|null)>`

Return contact's roomAlias in the room, the same as roomAlias

Kind: instance method of Room
Returns: Promise.<(string|null)> - - If a contact has an alias in room, return string, otherwise return null

Param	Type
contact	`Contact`

Example

const bot = new Wechaty()
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()

room.roomAlias(contact) ⇒ `Promise.<(string|null)>`

Same as function alias

Kind: instance method of Room

Param	Type
contact	`Contact`

room.has(contact) ⇒ `Promise.<boolean>`

Check if the room has member contact, the return is a Promise and must be await-ed

Kind: instance method of Room
Returns: Promise.<boolean> - Return true if has contact, else return false.

Param	Type
contact	`Contact`

Example (Check whether 'lijiarui' is in the room 'wechaty')

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!`)
  }
}

room.memberAll(query) ⇒ `Promise.<Array.<Contact>>`

Find all contacts in a room

definition

name the name-string set by user-self, should be called name, equal to Contact.name()
roomAlias 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

Param	Type	Description
query	`RoomMemberQueryFilter` \| `string`	When use memberAll(name:string), return all matched members, including name, roomAlias, contactAlias

room.member(queryArg) ⇒ `Promise.<(null|Contact)>`

Find all contacts in a room, if get many, return the first one.

Kind: instance method of Room

Param	Type	Description
queryArg	`RoomMemberQueryFilter` \| `string`	When use member(name:string), return all matched members, including name, roomAlias, contactAlias

Example (Find member by name)

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)

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.memberList() ⇒ `Promise.<Array.<Contact>>`

Get all room member from the room

Kind: instance method of Room
Example

await room.memberList()

room.sync() ⇒ `Promise.<void>`

Force reload data for Room, Sync data for Room

Kind: instance method of Room
Example

await room.sync()

room.owner() ⇒ `Contact` | `null`

Get room's owner from the room.

Kind: instance method of Room
Example

const owner = room.owner()

Room.create(contactList, [topic]) ⇒ `Promise.<Room>`

Create a new room.

Kind: static method of Room

Param	Type
contactList	`Array.<Contact>`
[topic]	`string`

Example (Creat a room with 'lijiarui' and 'juxiaomi', the room topic is 'ding - created')

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

Param	Type
[query]	`RoomQueryFilter`

Example

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
Returns: Promise.<(Room|null)> - If can find the room, return Room, or return null

Param	Type
query	`RoomQueryFilter`

Example

const bot = new Wechaty()
await bot.start()
// after logged in...
const roomList = await bot.Room.find()
const roomList = await bot.Room.find({topic: 'wechaty'})

Room.load(id) ⇒ `Room`

Load room by topic.

Tips: For Web solution, it cannot get the unique topic id, but for other solutions besides web, we can get unique and permanent topic id.

Kind: static method of Room

Param	Type
id	`string`

Example

const bot = new Wechaty()
await bot.start()
// after logged in...
const room = bot.Room.load('roomId')

Contact

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

Examples/Contact-Bot

Kind: global class

Contact
- instance
  - .say(textOrContactOrFile) ⇒ Promise.<void>
  - .name() ⇒ string
  - .alias(newAlias) ⇒ string | null | Promise.<boolean>
  - ~~.stranger()~~
  - .friend() ⇒ boolean | null
  - ~~.official()~~
  - ~~.personal()~~
  - .type() ⇒ ContactType.Unknown | ContactType.Personal | ContactType.Official
  - .gender() ⇒ ContactGender.Unknown | ContactGender.Male | ContactGender.Female
  - .province() ⇒ string | null
  - .city() ⇒ string | null
  - .avatar() ⇒ Promise.<FileBox>
  - ~~.refresh()~~
  - .sync() ⇒ Promise.<this>
  - .self() ⇒ boolean
- static
  - .load(id) ⇒ Contact
  - .find(query) ⇒ Promise.<(Contact|null)>
  - .findAll([queryArg]) ⇒ Promise.<Array.<Contact>>

contact.say(textOrContactOrFile) ⇒ `Promise.<void>`

Kind: instance method of Contact

Param	Type	Description
textOrContactOrFile	`string` \| `Contact` \| `FileBox`	send text, Contact, or file to contact. You can use FileBox to send file

Example

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!')

# 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.fromLocal('/tmp/text.txt')
await contact.say(fileBox1)
await contact.say(fileBox2)

# 3. send contact card to contact

const contactCard = bot.Contact.load('contactId')
await contact.say(contactCard)

contact.name() ⇒ `string`

Get the name from a contact

Kind: instance method of Contact
Example

const name = contact.name()

contact.alias(newAlias) ⇒ `string` | `null` | `Promise.<boolean>`

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

Param	Type
newAlias	`none` \| `string` \| `null`

Example ( GET the alias for a contact, return {(string | null)})

const alias = contact.alias()
if (alias === null) {
  console.log('You have not yet set any alias for contact ' + contact.name())
} else {
  console.log('You have already set an alias for contact ' + contact.name() + ':' + alias)
}

Example (SET the alias for a contact)

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)

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.stranger()

Deprecated

Should use friend instead

Kind: instance method of Contact

contact.friend() ⇒ `boolean` | `null`

Check if contact is friend

Kind: instance method of Contact
Returns: boolean | null -
True for friend of the bot
False for not friend of the bot, null for unknown.
Example

const isFriend = contact.friend()

contact.official()

Deprecated

Check if it's a offical account, should use type instead

Kind: instance method of Contact

contact.personal()

Deprecated

Check if it's a personal account, should use type instead

Kind: instance method of Contact

contact.type() ⇒ `ContactType.Unknown` | `ContactType.Personal` | `ContactType.Official`

Return the type of the Contact

Tips: ContactType is enum here.

Kind: instance method of Contact
Example

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
Example

const gender = contact.gender() === bot.Contact.Gender.Male

contact.province() ⇒ `string` | `null`

Get the region 'province' from a contact

Kind: instance method of Contact
Example

const province = contact.province()

contact.city() ⇒ `string` | `null`

Get the region 'city' from a contact

Kind: instance method of Contact
Example

const city = contact.city()

contact.avatar() ⇒ `Promise.<FileBox>`

Get avatar picture file stream

Kind: instance method of Contact
Example

# 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.refresh()

Deprecated

Force reload(re-ready()) data for Contact, use sync instead

Kind: instance method of Contact

contact.sync() ⇒ `Promise.<this>`

Force reload(re-ready()) data for Contact,

Kind: instance method of Contact
Example

await contact.sync()

contact.self() ⇒ `boolean`

Check if contact is self

Kind: instance method of Contact
Returns: boolean - True for contact is self, False for contact is others
Example

const isSelf = contact.self()

Contact.load(id) ⇒ `Contact`

Get Contact by id

Kind: static method of Contact

Param	Type
id	`string`

Example

const bot = new Wechaty()
await bot.start()
const contact = bot.Contact.load('contactId')

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
Returns: Promise.<(Contact|null)> - If can find the contact, return Contact, or return null

Param	Type
query	`ContactQueryFilter`

Example

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

Param	Type
[queryArg]	`ContactQueryFilter`

Example

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'

Friendship

Send, receive friend request, and friend confirmation events.

send request
receive request(in friend event)
confirmation friendship(friend event)

Examples/Friend-Bot

Kind: global class

Friendship
- instance
  - .accept() ⇒ Promise.<void>
  - .hello() ⇒ string
  - .contact() ⇒ Contact
  - .type() ⇒ FriendshipType
- static
  - ~~.send()~~
  - .add(contact, hello) ⇒ Promise.<void>

friendship.accept() ⇒ `Promise.<void>`

Accept Friend Request

Kind: instance method of Friendship
Example

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
Example (If request content is `ding`, then accept the friendship)

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`

Get the contact from friendship

Kind: instance method of Friendship
Example

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
Example (If request content is `ding`, then accept the friendship)

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 instead

Kind: static method of 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

Param	Type	Description
contact	`Contact`	Send friend request to contact
hello	`string`	The friend request content

Example

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

Kind: global class

Message
- .from() ⇒ Contact
- .to() ⇒ Contact | null
- .room() ⇒ Room | null
- ~~.content()~~
- .text() ⇒ string
- .say(textOrContactOrFile, [mention]) ⇒ Promise.<void>
- .type() ⇒ MessageType
- .self() ⇒ boolean
- .mention() ⇒ Promise.<Array.<Contact>>
- ~~.mentioned()~~
- .forward(to) ⇒ Promise.<void>
- .age() ⇒ number
- ~~.file()~~
- .toFileBox() ⇒ Promise.<FileBox>
- .toContact() ⇒ Promise.<Contact>

message.from() ⇒ `Contact`

Get the sender from a message.

Kind: instance method of Message
Example

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` | `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.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
Example

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 instead

Kind: instance method of Message

message.text() ⇒ `string`

Get the text content of the message

Kind: instance method of Message
Example

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.say(textOrContactOrFile, [mention]) ⇒ `Promise.<void>`

Reply a Text or Media File message to the sender.

Kind: instance method of Message
See: Examples/ding-dong-bot

Param	Type	Description
textOrContactOrFile	`string` \| `Contact` \| `FileBox`	send text, Contact, or file to bot. You can use FileBox to send file
[mention]	`Contact` \| `Array.<Contact>`	If this is a room message, when you set mention param, you can `@` Contact in the room.

Example

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)
  }

# 2. send Text

  if (/^dong$/i.test(m.text())) {
    await msg.say('dingdingding')
  }

# 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)
  }

})
.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

Kind: instance method of Message
Example

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
Returns: boolean - - Return true for send from self, false for send from others.
Example

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
Returns: Promise.<Array.<Contact>> - - Return message mentioned contactList
Example

const contactList = await message.mention()
console.log(contactList)

message.mentioned()

Deprecated

should use mention instead

Kind: instance method of Message

message.forward(to) ⇒ `Promise.<void>`

Forward the received message.

Kind: instance method of Message

Param	Type	Description
to	`Sayable` \| `Array.<Sayable>`	Room or Contact The recipient of the message, the room, or the contact

Example

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.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.file()

Deprecated

use toFileBox instead

Kind: instance method of Message

message.toFileBox() ⇒ `Promise.<FileBox>`

Extract the Media File from the Message, and put it into the FileBox.

Kind: instance method of Message

message.toContact() ⇒ `Promise.<Contact>`

Get Share Card of the Message Extract the Contact Card from the Message, and encapsulate it into Contact class

Kind: instance method of Message