Sometimes users send messages such as an image, a video or special location messages, among others, to receive and start a conversation when a message of this type arrives we can use the events.



When a user sends a "text" message that does not exist in a keyword on another flow, the WELCOME event will be triggered by default, which is the default event.

Let's imagine the case in which a person writes the word Thank you!

  import { addKeyword, EVENTS } from '@builderbot/bot'
  const welcomeFlow = addKeyword(EVENTS.WELCOME).addAnswer('Ey welcome?')
  const greetingFlow = addKeyword(['hello','hi']).addAnswer('Hi!')

We can see in the diagram above that the bot does a search in all the flows to get the best flow that can respond to the keyword "Thank You" but as it does not find then the "WELCOME" is triggered.


Received Image or Video

When a user sends an image or a video, the MEDIA event, which is the default event, will be triggered by default. This is ideal for when we need them to send information and we need to store it.

  import { addKeyword, EVENTS } from '@builderbot/bot'
  const mediaFlow = addKeyword(EVENTS.MEDIA).addAnswer('I received a media image/video')
  import { addKeyword, EVENTS } from '@builderbot/bot'
  import { BaileysProvider } from '@builderbot/provider-baileys'

  const mediaFlow = addKeyword<BaileysProvider>(EVENTS.MEDIA)
  .addAnswer('I received a media image/video', async (ctx, { provider }) => {
    const localPath = await provider.saveFile(ctx, {path:'...'})


Received Document

When a user sends a document, DOCUMENT event will be triggered by default, which is the default event.

  import { addKeyword, EVENTS } from '@builderbot/bot'
  const documentFlow = addKeyword(EVENTS.DOCUMENT)
  .addAnswer("Wow! I'm sorry I can't read this document right now", async (ctx, { provider }) => {
    const localPath = await provider.saveFile(ctx, {path:'...'})


Received Location

When your chatbot needs to access a user's location, it's important to ensure that the location is sent directly from the WhatsApp app to have results. Once the location is received, you can perform a console log of ctx to view the details of the received location.

The received location context will look something like this in console:

ctx:  {
  message: Message {
    locationMessage: LocationMessage {
      degreesLatitude: -2.1462137699127197,
      degreesLongitude: -79.88981628417969,
      name: 'Doctor Miguel Angel Jijón Teran',
      address: 'Doctor Miguel Angel Jijón Teran, Guayaquil, Ecuador',
  body: '_event_location__0d5c9f57-0909-44a1-995f-902f9df3b21f',
  name: 'yeyodev 👨🏾‍💻',
  from: '593000000000'

This will output the user's latitude and longitude in the console, allowing you to effectively utilize the location data for your chatbot's functionality.

To access the location data, you can use the following approach:

import { EVENTS, addKeyword } from "@builderbot/bot";

export default addKeyword(EVENTS.LOCATION)
.addAnswer("I have received your location!", null, async (ctx) => {
  const userLatitude = ctx.message.locationMessage.degreesLatitude;
  const userLongitude = ctx.message.locationMessage.degreesLongitude;


Received Voice Note

When a user sends a voice note, the VOICE_NOTE event will be triggered by default, which is the event intended for this behavior, it is important to understand that a voice note is different from an image or video file.

  import { addKeyword, EVENTS } from '@builderbot/bot'
  const voiceNoteFlow = addKeyword(EVENTS.VOICE_NOTE)
  .addAnswer('Give me a second to hear you!', async (ctx, { provider }) => {
    const localPath = await provider.saveFile(ctx, {path:'...'})


My first chatbot

Learn how build your first chatbot in few minutes

Read more


Understand the essential concepts for building bots

Read more

Add Functions

The key to learning how to write flows is add-functions.

Read more


Unlimitate and start implementing the community plugins.

Read more



Learn how to modularise flows so that you can have a more maintainable bot.

Send Message

How to send a message via HTTP to start conversations, you can send multimedia as well.


A good practice is to dockerise your bots to make them more maintainable and effective.


Learning about events will make us more fluent when creating chatbots.