Basics · Methods

Edit this page on GitHub

Methods

State

En muchas ocasiones necesitarás compartir datos entre flujos y sin importar si has modularizado tu proyecto en diferentes archivos puedes usar state en la función callback para poder acceder al estado individual de cada usuario.

Imaginemos el caso en el que tienes dos flujos. Flujo A: Encargado de recopilar los datos de los usuarios. Flujo B: Encargado de generar un registro en la base de datos. pero ambos flujos son archivos independientes

Remember that the state is independent per conversation between user and bot.

  import { createFlow, MemoryDB, createProvider } from '@builderbot/bot';
  // ...
  import flowA from './flows/flow-a'
  import flowB from './flows/flow-b'

  const main = async () => {

      const adapterDB = new MemoryDB()
      const adapterFlow = createFlow([flowA, flowB])
      const adapterProvider = createProvider(BaileysProvider)

      adapterProvider.initHttpServer(3000)

      await createBot({
          flow: adapterFlow,
          provider: adapterProvider,
          database: adapterDB,
      })
  }

Cada historial de conversaciones con el usuario es totalmente independiente, de esta forma evitamos mezclar conversaciones.

Diagram
Diagram

GlobalState

Muy similar a state existe otro método llamado global_state para compartir un estado global del bot entre diferentes flujos. El uso principal de este método es compartir datos que pueden cambiar y a los que puede acceder cada conversación entre bot y usuario.

A continuación, puede ver un ejemplo práctico en el que usamos globalState para usarlo como un interruptor para permitir o no permitir que el bot responda sin importar quién le escriba.

  import { createFlow, MemoryDB, createProvider } from '@builderbot/bot';
  // ...
  import flowWelcome from './flows/flow-welcome'
  import flowOnOff from './flows/flow-on-off'

  const main = async () => {

      const adapterDB = new MemoryDB()
      const adapterFlow = createFlow([flowWelcome, flowOnOff])
      const adapterProvider = createProvider(BaileysProvider)

      adapterProvider.initHttpServer(3000)

      await createBot({
          flow: adapterFlow,
          provider: adapterProvider,
          database: adapterDB,
      })
  }
Diagram

State/GlobalState Options

Ambos métodos, como state y global estate, contienen opciones y funcionalidades similares, que según el caso de uso pueden resultar muy útiles.

Clear

Este método permite limpiar el estado de forma global o independiente. Técnicamente despeja el Mapa.

Disponible en: state, globalState

.addAnswer('..', null, async (_, { state }) => {
  state.clear()
})
.addAction(async (_, { globalState }) => {
  globalState.clear()
})

Update

Para agregar o actualizar un valor en el estado tenemos disponible el método update. Este método recibe un objeto que si el valor no existe lo crea y devuelve un nuevo objeto con todos los valores. Es importante comprender que es una promesa evitar comportamientos raros agregando el await

Disponible en: state, globalState

.addAnswer('..', null, async (_, { state }) => {
  await state.update({name:'Joe', age:'33'})
  await state.update({email:'test@test.com'})
})
.addAction(async (_, { globalState }) => {
  await globalState.update({name:'Joe', age:'33'})
  await globalState.update({email:'test@test.com'})
})

Get

Cuando necesitamos recuperar los valores de estado, podemos hacerlo individualmente llamando por el nombre de la propiedad de la siguiente manera.

Disponible en: state, globalState

.addAnswer('..', null, async (_, { state }) => {
  state.get('propertyName')
})
.addAction(async (_, { globalState }) => {
  globalState.get('propertyName')
})

GetMyState

Otra forma de recuperar todo el objeto de estado perteneciente a una conversación independiente del usuario es mediante getMyState

Disponible en: state

.addAnswer('..', null, async (_, { state }) => {
  state.getMyState()
})

GetAllState

Cuando estamos trabajando con el Estado global y queremos recuperar todos los objetos de propiedades con sus respectivos valores, puede usar getAllState

Disponible en: globalState

.addAnswer('..', null, async (_, { globalState }) => {
  globalState.getAllState()
})

FlowDynamic

Muchas veces necesitará enviar mensajes provenientes de una llamada API o datos dinámicos de la base de datos o de procesos. En este caso, debe usarflowDynamic.

  import { addKeyword } from '@builderbot/bot';

  const flowStandAlone = addKeyword('register')
    .addAnswer('What is your name?', { capture: true }, async (ctx, { flowDynamic }) => {
      const responseName = ctx.body
      //.... db.insert({name:responseName})
      await flowDynamic(`Thanks for register ${responseName}`)
    })

  export default flowStandAlone

Si desea enviar una lista de productos, se recomienda enviar algunos productos entre 4 y 8 y puede preguntar al usuario qué categoría de productos y otros detalles filtrar y poder responder con la lista de productos ideal.


FlowDynamic Options

  • Name
    body
    Type
    string
    Description

    Puede enviar un mensaje dentro de un objeto utilizando la propiedad body. Es ideal cuando necesita enviar un mensaje aparte del mensaje para enviar un medio o para retrasar.

  • Name
    delay
    Type
    number
    Description

    Este es el número de milisegundos que transcurrirán antes de que se envíe el mensaje.

  • Name
    media
    Type
    string
    Description

    La url o ruta local del archivo a enviar, debe ser una cadena de texto y si es una URL debe ser pública.

const flow = addKeyword('register')
.addAction(async (_, { flowDynamic }) => {

  await flowDynamic([{ body: `Thanks  ${responseName}` }])

  await flowDynamic([{ 
    body: `message with 2 seconds delay`,
    delay: 2000 
   }])

  await flowDynamic([{ 
    body: `Look at this`,
    media: `https://i.imgur.com/0HpzsEm.png` 
  }])

  await flowDynamic([{ 
    body: `Look at this`,
    media: join('assets','file.pdf') 
  }])

})

FallBack

La función fallBack() es un recurso fundamental dentro del flujo de interacción de un bot, que se utiliza para manejar respuestas inválidas o inesperadas del usuario. Cuando un usuario proporciona un mensaje que no coincide con ninguna palabra clave o respuesta esperada, el bot puede invocar la función fallBack() para repetir el último mensaje y esperar una respuesta válida.

Para integrar la función fallBack () en el flujo de interacción del bot, se usa dentro del addAnswer() o addAction() método. Dentro de este método, se establece una condición que verifica si la respuesta del usuario es válida o no. En caso de que la respuesta no cumpla con los criterios esperados, se llama a fallBack() para repetir el último mensaje y solicitar una respuesta válida. Por ejemplo:

import { addKeyword } from '@builderbot/bot';

const flowEmailRegister = addKeyword('hello')
  .addAnswer('What is your email?', {capture:true}, (ctx, { fallBack }) => {
    if (!ctx.body.includes('@')) {
      return fallBack(`Ups! is not a valid email`);
    } else {
      // db.insert({email:ctx.body})
    }
  });

EndFlow

La función endFlow se utiliza en aplicaciones de chat o interfaces de usuario conversacionales para finalizar un flujo de interacción con el usuario. Imagine un escenario en el que está recopilando información de un usuario en varios pasos, como su nombre, dirección de correo electrónico y número de teléfono, y en cada paso el usuario tiene la opción de cancelar la operación actual.

Al utilizar endFlow, puede proporcionar al usuario una manera fácil de cancelar la transacción en cualquier momento. Por ejemplo, podría presentar un botón o comando que el usuario pueda activar para indicar que desea detener el proceso actual. Una vez que se activa endFlow, el flujo de interacción finaliza y se puede mostrar un mensaje final al usuario, informándole que la solicitud ha sido cancelada.

En resumen, endFlow mejora la experiencia del usuario al proporcionar una salida clara y fácil de usar en caso de que decida abandonar el proceso en cualquier etapa del flujo de interacción. Esto ayuda a garantizar una experiencia de usuario más fluida y satisfactoria en las aplicaciones de conversación.

flow-validate-email-custom-error.ts

const flowRegister = addKeyword(['Hi'])
  .addAnswer(
    ['Hello!', 'To submit the form I need some data...', 'Write your *Name*'],
    { capture: true },

    async (ctx, { flowDynamic, endFlow, state }) => {
      if (ctx.body === 'cancel') {
        return endFlow(`Your request has been canceled`);
      }
      await state.update({name:ctx.body})
      return flowDynamic(`Nice to meet you *${ctx.body}*, let's continue...`);
    }
  )
  .addAnswer(
    ['I also need your last names'],
    { capture: true },

    async (ctx, { flowDynamic, endFlow, state }) => {
      if (ctx.body === 'cancel') {
        return endFlow();
      }
      await state.update({lastName:ctx.body})
      return flowDynamic(`Perfect *${ctx.body}*, finally...`);
    }
  )

GotoFlow

La función gotoFlow permite la transición fluida entre diferentes flujos de interacción en una aplicación conversacional. Este método es útil cuando necesita separar la lógica de interacción en diferentes flujos y dirigir al usuario de un flujo a otro de acuerdo con ciertas condiciones o eventos.

Por ejemplo, supongamos que en una aplicación de asistente virtual tiene un flujo para usuarios registrados y otro para usuarios no registrados. Con gotoFlow, es posible dirigir a un usuario recién registrado del flujo de usuarios no registrados al flujo de usuarios registrados, o viceversa, proporcionando una experiencia personalizada y consistente para cada tipo de usuario.

En el código proporcionado, se muestra cómo usar gotoFlow para dirigir al usuario al flujo correspondiente de acuerdo con su estado de registro. Esto ayuda a modularizar la lógica de la aplicación y facilita la gestión de múltiples flujos de conversación.

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

  const flowWelcome = addKeyword('hi')
    .addAnswer('Welcome!', null, async (ctx, { gotoFlow }) => {
        // db.get(...)
        const userRegistered = true;

        if (userRegistered) return gotoFlow(flowRegistered);

        return gotoFlow(flowUserNotRegistered);
    });
  export default flowWelcome
Diagram

Blacklist

Muchas veces necesitaremos agregar o administrar una lista de números con los que no queremos interactuar con nuestro bot. Para ellos existe una lista negra que contiene una serie de métodos para agregar, eliminar y revisar números. Imagine un caso en el que desea hablar con un contacto sin la intervención del bot. Podrías usar este mecanismo

    const flowMain = addKeyword<BaileysProvider>(EVENTS.WELCOME)
        .addAction(async (_, { flowDynamic}) => {
            await flowDynamic('Hola buenas!!')
        })

    await createBot({
        database: new MemoryDB(),
        flow: createFlow([flowMain]),
        provider: createProvider(BaileysProvider),
    })

    adapterProvider.initHttpServer(3001)
    adapterProvider.server.post('/mute-number', handleCtx(async (bot, req, res) => {
        await bot.blacklist.add(`340000000`) // added to blacklist
        res.end('ok number muted')
    }))

Guides

My first chatbot

Learn how build your first chatbot in few minutes

Read more

Concepts

Understand the essential concepts for building bots

Read more

Add Functions

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

Read more

Plugins

Unlimitate and start implementing the community plugins.

Read more

Resources

Modularize

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.

Dockerizer

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

Events

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