addKeyword

Overview

The addKeyword function creates a new conversation flow that is triggered when a user sends a message matching the specified keywords or regex pattern. This is the entry point for creating conversation flows.

Function Signature

const addKeyword = <P = any, B = any>(
  keyword: string | [string, ...string[]],
  options?: ActionPropertiesKeyword
): TFlow<P, B>

Parameters

keyword

string | string[]

required

The keyword(s) that trigger this flow. Can be:

A single string: 'hello'
An array of strings: ['hello', 'hi', 'hey']
A regex pattern (when options.regex is true)

options

ActionPropertiesKeyword

Optional configuration for keyword matching behavior.

Show properties

sensitive

boolean

default:"false"

Enable case-sensitive keyword matching. When false, ‘Hello’ and ‘hello’ are treated the same.

regex

boolean

default:"false"

Treat the keyword as a regular expression pattern.

Return Value

flow

TFlow<P, B>

Returns a flow object with the following methods:

Show methods

addAnswer

function

Add a response message to the flow. See addAnswer.

addAction

function

Add a callback action without sending a message. See addAction.

toJson

function

Convert the flow to JSON representation.

ref

string

Unique reference ID for this flow.

Usage Examples

Basic Keyword Trigger

TypeScript
JavaScript

import { addKeyword } from '@builderbot/bot'

const welcomeFlow = addKeyword('hello')
  .addAnswer('Hello! Welcome to our service.')
  .addAnswer('How can I help you today?')

const { addKeyword } = require('@builderbot/bot')

const welcomeFlow = addKeyword('hello')
  .addAnswer('Hello! Welcome to our service.')
  .addAnswer('How can I help you today?')

Multiple Keywords

TypeScript
JavaScript

import { addKeyword } from '@builderbot/bot'

const greetingFlow = addKeyword(['hello', 'hi', 'hey', 'greetings'])
  .addAnswer('Hi there! Thanks for reaching out.')

const { addKeyword } = require('@builderbot/bot')

const greetingFlow = addKeyword(['hello', 'hi', 'hey', 'greetings'])
  .addAnswer('Hi there! Thanks for reaching out.')

Case-Sensitive Matching

TypeScript
JavaScript

import { addKeyword } from '@builderbot/bot'

const vipFlow = addKeyword('VIP', { sensitive: true })
  .addAnswer('Welcome VIP member!')

const { addKeyword } = require('@builderbot/bot')

const vipFlow = addKeyword('VIP', { sensitive: true })
  .addAnswer('Welcome VIP member!')

Regex Pattern Matching

TypeScript
JavaScript

import { addKeyword } from '@builderbot/bot'

// Matches any message containing a phone number
const phoneFlow = addKeyword('\\d{3}-\\d{3}-\\d{4}', { regex: true })
  .addAnswer('I detected a phone number in your message.')

// Matches email patterns
const emailFlow = addKeyword('[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}', { regex: true })
  .addAnswer('Thanks for providing your email!')

const { addKeyword } = require('@builderbot/bot')

// Matches any message containing a phone number
const phoneFlow = addKeyword('\\d{3}-\\d{3}-\\d{4}', { regex: true })
  .addAnswer('I detected a phone number in your message.')

// Matches email patterns
const emailFlow = addKeyword('[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}', { regex: true })
  .addAnswer('Thanks for providing your email!')

Complex Flow with Actions

TypeScript
JavaScript

import { addKeyword } from '@builderbot/bot'

const orderFlow = addKeyword(['order', 'buy'])
  .addAnswer('Great! Let me help you place an order.')
  .addAnswer(
    'What would you like to order?',
    { capture: true },
    async (ctx, { flowDynamic, state }) => {
      await state.update({ orderItem: ctx.body })
      await flowDynamic(`You selected: ${ctx.body}`)
    }
  )
  .addAnswer(
    'How many would you like?',
    { capture: true },
    async (ctx, { flowDynamic, state }) => {
      const orderItem = state.get('orderItem')
      await flowDynamic(`Order: ${ctx.body}x ${orderItem}`)
    }
  )

const { addKeyword } = require('@builderbot/bot')

const orderFlow = addKeyword(['order', 'buy'])
  .addAnswer('Great! Let me help you place an order.')
  .addAnswer(
    'What would you like to order?',
    { capture: true },
    async (ctx, { flowDynamic, state }) => {
      await state.update({ orderItem: ctx.body })
      await flowDynamic(`You selected: ${ctx.body}`)
    }
  )
  .addAnswer(
    'How many would you like?',
    { capture: true },
    async (ctx, { flowDynamic, state }) => {
      const orderItem = state.get('orderItem')
      await flowDynamic(`Order: ${ctx.body}x ${orderItem}`)
    }
  )

Common Patterns

const menuFlow = addKeyword(['menu', 'options'])
  .addAnswer([
    'Main Menu:',
    '1. View Products',
    '2. Check Order',
    '3. Contact Support',
    '4. FAQ'
  ])

Help Command

const helpFlow = addKeyword(['help', '?', 'commands'])
  .addAnswer('Available commands:')
  .addAnswer('- Type "menu" to see options')
  .addAnswer('- Type "order" to place an order')
  .addAnswer('- Type "support" to contact us')

Notes

Keywords are matched against the entire message body by default
When using multiple keywords, any match will trigger the flow
Regex patterns must be properly escaped in strings
Case-insensitive matching is the default behavior
The flow is only triggered once per keyword match per message

addAnswer - Add responses to your flow
addAction - Add callback actions
createFlow - Combine multiple keyword flows

Core API

Bot Instance

Flow Methods

Context & State

Utils

Overview

Function Signature

Parameters

Return Value

Usage Examples

Basic Keyword Trigger

Multiple Keywords

Case-Sensitive Matching

Regex Pattern Matching

Complex Flow with Actions

Common Patterns

Menu Flow

Help Command

Notes

Build docs developers (and LLMs) love

Core API

Bot Instance

Flow Methods

Context & State

Utils

​Overview

​Function Signature

​Parameters

​Return Value

​Usage Examples

​Basic Keyword Trigger

​Multiple Keywords

​Case-Sensitive Matching

​Regex Pattern Matching

​Complex Flow with Actions

​Common Patterns

​Menu Flow

​Help Command

​Notes

​Related

Build docs developers (and LLMs) love

Overview

Function Signature

Parameters

Return Value

Usage Examples

Basic Keyword Trigger

Multiple Keywords

Case-Sensitive Matching

Regex Pattern Matching

Complex Flow with Actions

Common Patterns

Menu Flow

Help Command

Notes

Related