Basics · Methods
Edit this page on GitHubMethods
State
Em muitas ocasiões, você precisará compartilhar dados entre fluxos e não importa se modularizou seu projeto em arquivos diferentes, você pode usar o estado na função de retorno de chamada para poder acessar o estado individual de cada usuário.
Vamos imaginar o caso em que você tem dois fluxos. Fluxo A: responsável pela recolha de dados do utilizador. Fluxo B: responsável por gerar um registo na base de dados. mas ambos os fluxos são ficheiros independentes
__ Lembre-se__ que o estado é independente por conversa entre o Usuário e o 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 histórico de conversas com o utilizador é totalmente independente, desta forma evitamos misturar conversas.
GlobalState
Muito semelhante ao state existe outro método chamado estado Global para compartilhar um estado global do bot entre diferentes fluxos. O principal uso desse método é compartilhar dados que podem mudar e que todas as conversas entre o bot e o usuário podem acessar.
Abaixo, você pode ver um exemplo prático em que usamos o globalState para usá-lo como um switch para permitir ou não que o bot responda, independentemente de quem escreve nele.
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 os métodos, como estado e estado global, contêm opções e funcionalidades semelhantes, que, dependendo do caso de uso, podem ser muito úteis.
Clear
Este método permite que o estado seja limpo globalmente ou de forma independente. Tecnicamente, limpa o mapa.
Disponível em: state, globalState
.addAnswer('..', null, async (_, { state }) => {
state.clear()
})
.addAction(async (_, { globalState }) => {
globalState.clear()
})Update
Para adicionar ou atualizar um valor no estado, temos disponível o método update. Este método recebe um objeto que, se o valor não existir, o cria e retorna um novo objeto com todos os valores.
É importante entender que é uma promessa evitar comportamentos raros adicionando o await
Disponível em: 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
Quando precisamos recuperar os valores de Estado, podemos fazê-lo individualmente chamando pelo nome da propriedade da seguinte forma.
Disponível em: state, globalState
.addAnswer('..', null, async (_, { state }) => {
state.get('propertyName')
})
.addAction(async (_, { globalState }) => {
globalState.get('propertyName')
})GetMyState
Outra maneira de recuperar todo o objeto de estado pertencente a uma conversa independente do Usuário é usando getMyState
Disponível em: state
.addAnswer('..', null, async (_, { state }) => {
state.getMyState()
})GetAllState
Quando estamos trabalhando com o estado global e queremos recuperar todos os objetos properties com seus respectivos valores, você pode usar getAllState
Disponível em: globalState
.addAnswer('..', null, async (_, { globalState }) => {
globalState.getAllState()
})FlowDynamic
Muitas vezes, você precisará enviar mensagens provenientes de uma chamada de API ou dados dinâmicos do banco de dados ou de processos. Neste caso, deve utilizar flowDynamic.
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 flowStandAloneNão é recomendado enviar muitas mensagens seguidas porque o provider may determine that it is spam.
Se você deseja enviar uma lista de produtos, recomenda-se enviar alguns produtos entre 4 e 8 e você pode perguntar ao usuário qual categoria de produtos e outros detalhes filtrar e ser capaz de responder com a lista de produtos ideal.
FlowDynamic Options
- Name
body- Type
- string
- Description
Você pode enviar uma mensagem dentro de um objeto usando a propriedade body. É ideal quando você precisa enviar uma mensagem para além da mensagem para enviar uma mídia ou para colocar um atraso.
- Name
delay- Type
- number
- Description
Este é o número de milissegundos que decorrerão antes de a mensagem ser enviada.
- Name
media- Type
- string
- Description
O url ou caminho local do ficheiro a enviar deve ser uma cadeia de texto e, se for um URL, deve ser público.
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
A função fallBack() é um recurso fundamental dentro do fluxo de interação de um bot, usado para lidar com respostas inválidas ou inesperadas do Usuário. Quando um usuário fornece uma mensagem que não corresponde a nenhuma palavra-chave ou resposta esperada, o bot pode invocar a função fallBack() para repetir a última mensagem e aguardar uma resposta válida.
Para integrar a função fallBack() no fluxo de interação do bot, ela é usada dentro do addAnswer() or addAction() método. Nesse método, é definida uma condição que verifica se a resposta do Usuário é válida ou não. Caso a resposta não atenda aos critérios esperados, fallBack() é chamado para repetir a última mensagem e solicitar uma resposta válida. Por exemplo:
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
A função endFlow é usada em aplicativos de bate-papo ou interfaces de usuário conversacionais para encerrar um fluxo de interação com o usuário. Imagine um cenário em que você está coletando informações de um usuário em várias etapas, como nome, endereço de E-mail e número de telefone, e em cada etapa o usuário tem a opção de cancelar a operação atual.
Ao usar o endFlow, você pode fornecer ao usuário uma maneira fácil de cancelar a transação a qualquer momento. Por exemplo, você pode apresentar um botão ou comando que o usuário pode ativar para indicar que deseja interromper o processo atual. Uma vez que o endFlow é acionado, o fluxo de interação é encerrado e uma mensagem final pode ser exibida ao usuário, informando-o de que a solicitação foi cancelada.
Em resumo, o endFlow melhora a experiência do utilizador, proporcionando uma saída clara e fácil de utilizar, caso este decida abandonar o processo em qualquer fase do fluxo de interacção. Isso ajuda a garantir uma experiência de usuário mais suave e satisfatória em aplicativos de conversação.
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
A função gotoFlow permite a transição suave entre diferentes fluxos de interação em uma aplicação conversacional. Esse método é útil quando você precisa separar a lógica de interação em fluxos diferentes e direcionar o usuário de um fluxo para outro de acordo com certas condições ou eventos.
Por exemplo, suponha que, em um aplicativo de assistente virtual, você tenha um fluxo para usuários registrados e outro para usuários não registrados. Com o gotoFlow, é possível direcionar um usuário recém-registrado do fluxo de usuário não registrado para o fluxo de usuário registrado, ou vice-versa, proporcionando uma experiência personalizada e consistente para cada tipo de usuário.
No código fornecido, é mostrado como usar gotoFlow para direcionar o Usuário para o fluxo correspondente de acordo com seu status de registro. Isto ajuda a modularizar a lógica da aplicação e facilita a gestão de múltiplos fluxos de conversação.
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É importante notar que a implementação do go to Flow deve ter um retorno antes
Blacklist
Muitas vezes, precisaremos adicionar ou gerenciar uma lista de números que não Queremos interagir com nosso bot. Para eles, existe uma lista negra que contém uma série de métodos para adicionar, remover e rever números. Imagine um caso em que você deseja falar com um contato sem a intervenção do bot. Você poderia 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.