Basics · Methods
Edit this page on GitHubMethods
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.
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,
})
}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 flowStandAloneNO se recomienda enviar muchos mensajes seguidos porque el provider puede determinar que es spam.
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 flowWelcomeEs importante tener en cuenta que la implementación de go to Flow debe tener un retorno antes
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')
}))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.