Listen to events

tip

The wechaty bot is available in various programming languages!

Before starting this guide, make sure you are already familiar with the ding dong bot. If not, go to examples/basics. In this section, you will learn how to add various events to a bot. Events are functions that define the operations a bot can perform. Some common events include login, logout, onMessage. The guide will demonstrate in JavaScript, but you can choose between various programming languages available.

Getting started

1. Create an empty project folder
2. Add a bot.js file
3. In the terminal, type the following command:

npm init

A package.json file is created.

4. In the terminal, install the necessary dependencies

npm i qrcode-terminal wechaty 

 npm i wechaty-puppet-PUPPET-PROVIDER

The PUPPET-PROVIDER represents the messaging platform you want to integrate your bot with.

• For WhatsApp:

 npm i wechaty-puppet-whatsapp
• For WeChat:

 npm i wechaty-puppet-wechat
5. In the package.json file, add a script:

"start": "node bot.js"


6. In the terminal, type the following commands:

 export WECHATY_LOG=verbose
• For WhatsApp:

export WECHATY_PUPPET=wechaty-puppet-whatsaap
• For WeChat:

export WECHATY_PUPPET=wechaty-puppet-wechat
7. Now, we can run the bot using the command:

npm start

But, before that we need to add events to the bot. See the following examples:

Basic Events

scan Event

The scan event generates a QR code to integrate your bot to a puppet provider.

TypeScript

import { ScanStatus } from 'wechaty'

async function onScan (
  qrcode: undefined | string,
  status: ScanStatus,
) {
  console.info('Scan QR Code to login, status:', status, ScanStatus[status])
  console.info('https://wechaty.js.org/qrcode/' + encodeURIComponent(qrcode))
}

bot.on('scan', onScan)
await bot.start()

JavaScript

import { Wechaty,ScanStatus,log }  from 'wechaty'

async function onScan (qrcode,status)
 {
  console.info('Scan QR Code to login, status:', status, ScanStatus[status])
  console.info('https://wechaty.js.org/qrcode/' + encodeURIComponent(qrcode))
}

const bot = new Wechaty({
    name: 'bot-name',
  })

bot.on('scan', onScan)
bot.start()
  .then(() => log.info('StarterBot', 'Starter Bot Started.'))
  .catch(e => log.error('StarterBot', e))

Python

from wechaty import Wechaty, ScanStatus
from typing import Optional
import asyncio

# method one
def on_scan (qrcode, status):
    print('Scan QR Code to login: {}\n'.format(staus))
    print('https://wechaty.js.org/qrcode/{}'.format(qrcode))

bot = Wechaty()
bot.on('scan', on_scan)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_scan(self, qr_code: str, status: ScanStatus, data: Optional[str]):
        """listen scan event"""
        print('Scan QR Code to login: {}\n'.format(staus))
        print('https://wechaty.js.org/qrcode/{}'.format(qrcode))

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

login Event: bot contact

The login event logs the bot in, with the contact of the user.

TypeScript

import { Contact } from 'wechaty'

function onLogin (bot: Contact) {
  console.info('Bot logged in:', bot)
}

bot.on('login', onLogin)
await bot.start()

JavaScript

function onLogin (bot) {
  console.info('Bot logged in:', bot)
}

bot.on('login', onLogin)
await bot.start()

Python

from wechaty import Wechaty, Contact
from typing import Optional
import asyncio

# method one
def on_login (contact: Contact):
  print(f'User {contact} logged in\n')

bot.on('login', on_login)

# method two (suggested)
class MyBot(Wechaty):
    async def on_login(self, contact: Contact):
        print(f'User {contact} logged in\n')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

logout Event

The logout event logs the bot out.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

function onLogout (user) {
  log.info('StarterBot', '%s logout', user)
}
bot.on('logout',  onLogout)
await bot.start()

Python

from wechaty import Wechaty, Contact
import asyncio

# method one
async def on_logout(contact: Contact):
    print(f'User <{contact}> logout')

bot = MyBot()
bot.on('logout', on_logout)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_logout(self, contact: Contact):
        print(f'User <{contact}> logout')

async def start():
    await MyBot().start()

asyncio.run(start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

message Event

The message event notifies you when a new message arrives.

TypeScript

import { Message } from 'wechaty'

function onMessage (message: Message) {
  console.info('New message:', message)
}

bot.on('message', onMessage)
await bot.start()

JavaScript

function onMessage (message) {
  console.info('New message:', message)
}

bot.on('message', onMessage)
await bot.start()

Python

from wechaty import Wechaty, Message
import asyncio

# method one
async def on_message(msg: Message):
    print(f'receive message <{msg}>')

bot = MyBot()
bot.on('message', on_message)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_message(self, msg: Message):
        print(f'receive message <{msg}>')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

friendship Event: friend requests

The friendship event alerts you when someone sends you a friend request.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

bot
.on('friendship', async friendship => {
  let logMsg
  const fileHelper = bot.Contact.load('filehelper')

  try {
    logMsg = 'received `friend` event from ' + friendship.contact().name()
    await fileHelper.say(logMsg)
    console.log(logMsg)

    switch (friendship.type()) {
      /**
       *
       * 1. New Friend Request
       *
       * when request is set, we can get verify message from `request.hello`,
       * and accept this request by `request.accept()`
       */
      case Friendship.Type.Receive:
        if (friendship.hello() === 'ding') {
          logMsg = 'accepted automatically because verify messsage is "ding"'
          console.log('before accept')
          await friendship.accept()

          // if want to send msg , you need to delay sometimes
          await new Promise(r => setTimeout(r, 1000))
          await friendship.contact().say('hello from Wechaty')
          console.log('after accept')

        } else {
          logMsg = 'not auto accepted, because verify message is: ' + friendship.hello()
        }
        break

        /**
         *
         * 2. Friend Ship Confirmed
         *
         */
      case Friendship.Type.Confirm:
        logMsg = 'friend ship confirmed with ' + friendship.contact().name()
        break
    }
  } catch (e) {
    logMsg = e.message
  }

  console.log(logMsg)
  await fileHelper.say(logMsg)

})

Python

from wechaty import Wechaty, Friendship
import asyncio

# method one
async def on_friendship(friendship: Friendship):
    print(f'receive friendship<{friendship}> event')

bot = MyBot()
bot.on('friendship', on_friendship)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_friendship(self, friendship: Friendship):
        print(f'receive friendship<{friendship}> event')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

Room Events

room-topic Event: messages

The room-topic event alerts you when someone changes the room topic.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

bot
.on('room-topic', async function(room, topic, oldTopic, changer) {
  try {
    log.info('Bot', 'EVENT: room-topic - Room "%s" change topic from "%s" to "%s" by member "%s"',
                    room,
                    oldTopic,
                    topic,
                    changer,
                )
    await room.say(`room-topic - change topic from "${oldTopic}" to "${topic}" by member "${changer.name()}"` )
  } catch (e) {
    log.error('Bot', 'room-topic event exception: %s', e.stack)
  }
})

Python

from wechaty import Wechaty, Room, Contact
from datetime import datetime
import asyncio

# method one
async def on_room_topic(room: Room, new_topic: str, old_topic: str, changer: Contact, date: datetime):
    print(f'receive room topic changed event <from<{new_topic}> to <{old_topic}>> from room<{room}> ')

bot = MyBot()
bot.on('room-topic', on_room_topic)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_room_topic(self, room: Room, new_topic: str, old_topic: str, changer: Contact, date: datetime):
        print(f'receive room topic changed event <from<{new_topic}> to <{old_topic}>> from room<{room}> ')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

room-invite Event: messages

The room-invite event alerts you when there is a room invitation.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

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

Python

from wechaty import Wechaty, RoomInvitation
import asyncio


# method one
async def on_room_invite(room_invitation: RoomInvitation):
    print(f'receive room invitation<{room_invitation}> event')

bot = MyBot()
bot.on('room-invite', on_room_invite)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_room_invite(self, room_invitation: RoomInvitation):
        print(f'receive room invitation<{room_invitation}> event')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

room-join Event: messages

The room-join event alerts you when anyone joins the room.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

bot
.on('room-join', async function(room, inviteeList, inviter) {
  log.info( 'Bot', 'EVENT: room-join - Room "%s" got new member "%s", invited by "%s"',
            await room.topic(),
            inviteeList.map(c => c.name()).join(','),
            inviter.name(),
          )
  console.log('bot room-join room id:', room.id)
  const topic = await room.topic()
  await room.say(`welcome to "${topic}"!`, inviteeList[0])
})

Python

from wechaty import Wechaty, Contact, Room
from typing import List
from datetime import datetime
import asyncio

# method one
async def on_room_join(room: Room, invitees: List[Contact], inviter: Contact, date: datetime):
    print(f'receive room join event from Room<{room}>')

bot = Wechaty()
bot.on('room-join', on_room_join)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_room_join(self, room: Room, invitees: List[Contact], inviter: Contact, date: datetime):
        print(f'receive room join event from Room<{room}>')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

room-leave Event: messages

The room-leave event alerts you when anyone leaves the room.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

bot
.on('room-leave', async function(room, leaverList) {
  log.info('Bot', 'EVENT: room-leave - Room "%s" lost member "%s"',
                  await room.topic(),
                  leaverList.map(c => c.name()).join(','),
              )
  const topic = await room.topic()
  const name  = leaverList[0] ? leaverList[0].name() : 'no contact!'
  await room.say(`kick off "${name}" from "${topic}"!` )
})

Python

from wechaty import Wechaty, Contact, Room
from typing import List
from datetime import datetime
import asyncio

# method one
async def on_room_leave(room: Room, leavers: List[Contact], remover: Contact, date: datetime):
    print(f'receive room leave event from Room<{room}>')

bot = Wechaty()
bot.on('room-leave', on_room_leave)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_room_leave(self, room: Room, leavers: List[Contact], remover: Contact, date: datetime):
        print(f'receive room leave event from Room<{room}>')

asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

System events

ready Event

The ready event is executed when all data has been loaded successfully.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

    const contact = this.wechaty.Contact.load(contactId)
    await contact.ready()
    return contact

Python

from wechaty import Wechaty
from wechaty_puppet import EventReadyPayload
import asyncio

# method one
async def on_ready(payload: EventReadyPayload):
    """Any initialization work can be put in here

    Args:
        payload (EventReadyPayload): ready data
    """
    print(f'receive ready event<{payload}>')

bot = Wechaty()
bot.on('ready', on_ready)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_ready(self, payload: EventReadyPayload):
        """Any initialization work can be put in here

        Args:
            payload (EventReadyPayload): ready data
        """
        print(f'receive ready event<{payload}>')
        
asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

heartbeat Event: messages

The Heartbeat event helps to send emojis to a specified contact or group periodically.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

const config = {
    contact: 'filehelper', // contact who will receive the emoji
    emoji: {
        heartbeat: '😎', // the emoji to send
    },
    intervalSeconds: 60, // sends the emoji after an interval of 60 seconds
}
bot.use(
    Heartbeat(config),
)
bot.start()

Python

from wechaty import Wechaty
from wechaty_puppet import EventHeartbeatPayload
import asyncio

# method one
async def on_heartbeat(payload: EventHeartbeatPayload):
    print(f'receive heartbeat event from server <{payload}>')

bot = Wechaty()
bot.on('heartbeat', on_heartbeat)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_heartbeat(self, payload: EventHeartbeatPayload):
        print(f'receive heartbeat event from server <{payload}>')
        
asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!

error Event

The error event makes the bot to throw an error whenever an error is encounterd.

TypeScript

// TODO: Pull Request is welcome!

JavaScript

function onError (e) {
  console.error('Bot error:', e)
}
bot.on('error',  onError)
function onLogin (bot) {
  console.info('Bot logged in:', bot)
}

bot.on('login', onLogin)
await bot.start()

Python

from wechaty import Wechaty
from wechaty_puppet import EventErrorPayload
import asyncio

# method one
async def on_error(payload: EventErrorPayload):
    print(f'receive error event<{payload}> from sever')

bot = Wechaty()
bot.on('error', on_error)
asyncio.run(bot.start())

# method two (suggested)
class MyBot(Wechaty):
    async def on_error(self, payload: EventErrorPayload):
        print(f'receive error event<{payload}> from sever')
        
asyncio.run(MyBot().start())

Go

// TODO: Pull Request is welcome!

Java

// TODO: Pull Request is welcome!

PHP

// TODO: Pull Request is welcome!

Scala

// TODO: Pull Request is welcome!

C#

// TODO: Pull Request is welcome!

Rust

// TODO: Pull Request is welcome!