Ações
Ações são funções do lado do servidor executadas pelo chatbot como parte de um fluxo de conversação. As ações têm o poder de:
- Alterar o estado da conversa;
- Enviar mensagens personalizadas para a conversa;
- Executar código arbitrário, como chamar uma API ou armazenar dados no banco de dados
Como são funções JavaScript, elas podem fazer praticamente qualquer coisa e têm as seguintes propriedades:
- user: todos os atributos do usuário;
- session: variáveis mantidas apenas para a sessão;
- temp: variáveis mantidas apenas para o fluxo;
- bot: objeto contendo variáveis globais para este bot (igual para todos os usuários);
- event: evento original (mais recente) recebido do usuário;
- args: argumentos passados para esta ação do editor de fluxo;
- process: VM em área restrita contendo algumas das variáveis de ambiente (começando com EXPOSED_)
/** const virtual_machine = async function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) { */
user['firstname'] = 'Bob'
user['age'] = 17
temp = {
text: 'hello there'
}
session.store = [{ id: 1, id: 2, id: 3 }]
/** } */Cadastrando Novas Ações
Há duas maneiras de registrar novas ações:
- Adicione seu código JavaScript em um .jsarquivo e coloque-o na pasta data/global/actions.
🖊 Nota: Não há como adicionar novos durante o tempo de execução programaticamente.
- Escreva ações diretamente na GUI do Conversation Studio navegando até o editor de código e usando um modelo de ação
Usamos comentários JavaDoc para exibir informações significativas (como nome, descrição, argumentos, valores padrão) no editor de fluxo de diálogo.
É possível manter uma ação oculta no editor de fluxo adicionando o sinalizador @hidden true no JavaDoc.
Bibliotecas Externas
O código nas ações deve ser mantido relativamente simples. É possível definir contadores, formatar dados, buscar dados de uma API usando a biblioteca axios incluída.
Se for necessário usar módulos ou bibliotecas npm ou de outras linguagens de programação, recomendamos que configure um servidor para essa finalidade ou use funções sem servidor e chame a API usando as ações do Botpress.
Usar o Botpress para casos de uso de computação pesada de JavaScript, como processamento de imagem ou vídeo, pode causar problemas de latência para seu bot.
Desativando Ações
O Botpress irá ignorar os arquivos que começam com um ponto (.). Dessa forma, é possível desabilitar um gancho ou ação simplesmente prefixando o nome do arquivo com um ponto.
Ações Incorporadas
Ações de Espera
- Título da Ação: Espera/Atraso
- Categoria: Utilitário
- Autor: Botpress, Inc.
- Parâmetros: data_type:number name:delay (padrão = 1000) - O número de milissegundos para espera
const wait = async delay => {
return new Promise(resolve => setTimeout(() => resolve(), delay))
}
return wait(args.delay || 1000)🖊 Nota: Como é possível ver, a ação é apenas uma simples função de seta assíncrona que leva o número de milissegundos delaycomo parâmetro.
Ao construir uma ação, é necessário especificar o tipo de ação, sua categoria, o autor e seus parâmetros.
Anexar Contexto
- Título da Ação: Anexar Contexto
- Categoria: NLU
- Autor: Botpress, Inc.
- 1º Parâmetro: data_type:string name:contexts - Lista de contextos separados por vírgulas
- 2º Parâmetro: data_type:string name:[ttl=1] - Time-To-Live do contexto em número de turnos de diálogo. Coloque 0 para desativar a expiração.
Essa ação adiciona contexto(s) à lista de contextos usados pelo mecanismo NLU para mensagens subsequentes para essa sessão de bate-papo.
🖊 Nota:
- Se um contexto já estivesse presente na lista, o TTL mais alto venceria;
- Para substituir um contexto específico, use a removeContextação antes desta ação.
Esse método é contextual à sessão de bate-papo do usuário atual. Especifique mais de um contexto separando-os com uma vírgula.
Remover Contexto
- Título da Ação: Remover contexto
- Categoria: NLU
- Autor: Botpress, Inc.
- Parâmetro: data_type:string name:contexts - Lista de contextos separados por vírgulas
Use esta ação para remover o(s) contexto(s) fornecido(s) da lista de contextos usados pelo mecanismo NLU para as mensagens subsequentes dessa sessão de bate-papo.
Esse método é contextual à sessão de bate-papo do usuário atual. Especifique mais de um contexto separando-os com uma vírgula.
Redefinir Contexto
- Título da Ação: Remover contexto
- Categoria: NLU
- Autor: Botpress, Inc.
- Parâmetro: Nenhum
Ele redefine o contexto NLU para o escopo padrão. Esse método é contextual ao usuário atual e à sessão de bate-papo atual.
Enviar Comentários
- Título da Ação: Enviar comentários
- Categoria: NLU
- Autor: Botpress, Inc.
- Parâmetro: data_type:number name:value - O valor de feedback. Use 1 para feedback positivo e -1 para feedback negativo
Fornece feedback (1 para feedback positivo ou -1 negativo) no final de uma meta (um fluxo de trabalho que o usuário concluiu).
Obter Variável
- Título da Ação: Obter variável global
- Categoria: Armazenamento
- Autor: Botpress, Inc.
- 1º Parâmetro: data_type:string name:name - O nome da variável
2º Parâmetro: data_type:string name:output - A variável de estado para saída.
Esta ação recupera uma variável que foi armazenada globalmente usando uma chave de armazenamento. O Botpress usa um sistema key: value de armazenamento para permitir definições complexas de armazenamento de objetos.
Redefinir Variável
- Título da Ação: Redefinir variável global
- Categoria: Armazenamento
- Autor: Botpress, Inc.
- Parâmetro: data_type:string name:name - O nome da variável a ser redefinida
Use esta ação para redefinir uma variável com escopo global.
Definir Variável
- Título da Ação: Definir variável global
- Categoria: Armazenamento
- Autor: Botpress, Inc.
- 1º Parâmetro: data_type:string name:name - O nome da variável
2º Parâmetro: data_type:any name:value - Defina o valor da variável
- 3º Parâmetro: data_type:string name:[expiry=never] - Defina a expiração dos dados, pode ser never ou uma string curta como 6 hours
- 4º Parâmetro: data_type:string name:output - A variável de estado para a saída.
Esta ação permite definir uma variável globalmente, com expiração opcional.
Definir Variável
- Título da Ação: Definir variável
- Categoria: Armazenamento
- Autor: Botpress, Inc.
- 1º Parâmetro: data_type:string name:type - Escolha entre: usuário, sessão, temp e bot
2º Parâmetro: data_type:string name:name - O nome da variável
- 3º Parâmetro: data_type:any name:value - Defina o valor da variável. Digite null ou deixe em branco para apagá-la
Use esta ação para armazenar dados no armazenamento desejado com base na expectativa de tempo de vida útil.
Redefinir Sessão
- Título da Ação: Redefinir sessão
- Categoria: Armazenamento
- Autor: Botpress, Inc.
- Parâmetro: nenhum
Esta ação redefine a sessão do usuário e limpa as informações armazenadas em temp e session para o usuário. Esta ação não remove o histórico de Contextos NLU e histórico de Últimas Mensagens.
Mudar Idioma
- Título da Ação: Mudar idioma
- Categoria: Armazenamento
- Autor: Botpress, Inc.
- Parâmetro: data_type:string name:lang - O código do idioma, por exemplo en
Válido para detentores de licença empresarial com bots multilíngues, esta ação permite alterar o idioma do bot para o usuário atual.
O Botpress vem pré-embalado com um mecanismo de tradução que ajuda os desenvolvedores a projetar um bot em um idioma enquanto atende aos usuários de todos os idiomas suportados e configurados.
Tipos de conteúdo
Os tipos de conteúdo são a principal maneira de exibir conteúdo no chat.
Audio
O componente de áudio pode transmitir MP3áudio (.mp3). Use-o para transmitir músicas do Spotify ou do YouTube.
Este componente também pode transmitir arquivos de áudio armazenados em seu servidor.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create a video content type in action.
* ```
* {
* type: 'audio',
* video: 'https://URL_TO_YOUR_VIDEO.mp3',
* title: 'Random_video',
* typing: true
* }
* ```
* @title Display audio in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const audio = await bp.cms.renderElement(Cartão
Um cartão é um único elemento de um carrossel. Pode ser visto como uma carta em um baralho de cartas. O carrossel é todo o baralho de cartas.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create an Card content type in action.
*```
* {
* type: 'card',
* title: 'Botpress',
* subtitle: 'Website',
* image: 'https://avatars.githubusercontent.com/u/23510677?s=200&v=4',
* actions: [{ title: 'Botpress website Documentation', action: 'Open URL', url: 'https://botpress.com/docs' }]
* }
* ```
* @title Display an Card in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const audio = await bp.cms.renderElement(
'builtin_card',
{
type: 'card',
title: 'Botpress',
subtitle: 'Website',
image: 'https://avatars.githubusercontent.com/u/23510677?s=200&v=4',
actions: [{ title: 'Botpress website Documentation', action: 'Open URL', url: 'https://botpress.com/docs' }]
},
event
)
await bp.events.replyToEvent(event, audio)
}
return myAction()
/** Your code ends here */
}Carrossel
Um carrossel é uma série de cartas. Este componente é útil no chatbot de e-commerce.
O elemento de imagem pode ser um URL ou URLs de dados.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create a Carousel content type in action.
* ```
* {
* type: 'carousel',
* items: [
* {
* title: 'Botpress',
* subtitle: 'Website',
* image: 'https://avatars.githubusercontent.com/u/23510677?s=200&v=4',
* actions: [{ title: 'Botpress website', action: 'Open URL', url: 'https://botpress.com' }]
* }
* ],
* typing: true
* },
* ```
* @title Display a carousel in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const carousel = await bp.cms.renderElement(
'builtin_carousel',
{
type: 'carousel',
items: [
{
title: 'Botpress',
subtitle: 'Website',
image: 'https://avatars.githubusercontent.com/u/23510677?s=200&v=4',
actions: [{ title: 'Botpress website', action: 'Open URL', url: 'https://botpress.com' }]
},
{
title: 'Botpress Documentation',
subtitle: 'Website',
image:
'data:image/jpeg;base64,/9j/4A /9k=',
actions: [{ title: 'Botpress website', action: 'Open URL', url: 'https://botpress.com' }]
}
],
typing: true
},
event
)
await bp.events.replyToEvent(event, carousel)
}
return myAction()
/** Your code ends here */
}Lista Suspensa
Uma lista suspensa exibe uma lista de opções.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create a dropdown content type in action.
*```
* {
* type: 'dropdown',
* message: 'Dropdown Content type',
* buttonText: 'Click me',
* placeholderText: 'dropdown placeholder',
* options: [{ label: 'Food', value: 'apple' }],
* width: 10,
* displayInKeyboard: false,
* allowCreation: false,
* allowMultiple: false,
* markdown: true,
* typing: true
* }
* ```
* @title Display a dropdown in an action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const dropdown = await bp.cms.renderElement(
'dropdown',
{
type: 'dropdown',
message: 'Dropdown Content type',
buttonText: 'Click me',
placeholderText: 'dropdown placeholder',
options: [{ label: 'Food', value: 'apple' }],
markdown: true,
typing: true
},
event
)
await bp.events.replyToEvent(event, dropdown)
}
return myAction()
/** Your code ends here */
}Imagem
É possível exibir imagens. Use uma imagem de URL ou uma URL de dados.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create an image content type in action.
* ```
* {
* type: 'image',
* title: 'Random image',
* image: 'URL_YOUR_IMAGE',
* typing: true
* }
* ```
* @title Display image in action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const image = await bp.cms.renderElement(
'builtin_image',
{
type: 'image',
image:
'https://upload.wikimedia.org/wikipedia/commons/thumb/d/d3/Sphalerite_-_Creede%2C_Mineral_County%2C_Colorado%2C_USA.jpg/1920px-Sphalerite_-_Creede%2C_Mineral_County%2C_Colorado%2C_USA.jpg',
typing: true
},
event
)
await bp.events.replyToEvent(event, image)
}
return myAction()
/** Your code ends here */
}Localização
Ele exibe um lugar em um mapa. A localização só está habilitada no canal Vonage.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create an location content type in an action.
* ```
* {
type: 'location',
latitude: '',
longitude: '',
address: '',
title: 'Botpress Office',
typing: true
* }
* ```
* @title Display an location in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const audio = await bp.cms.renderElement(
'builtin_location',
{
type: 'location',
latitude: 46.784541,
longitude: -71.2909357,
address: '2480 Ch Ste-Foy Bureau 175, Quebec City, Quebec G1V 1T6',
title: 'Botpress Office',
typing: true
},
event
)
await bp.events.replyToEvent(event, audio)
}
return myAction()
/** Your code ends here */
}Arquivo
Botpress pode exibir arquivo PDF. Atualmente, apenas o formato PDF é suportado.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create an File content type in action.
* ```
* {
* type: 'file',
* file:
* 'http://wavelets.ens.fr/BOYCOTT_ELSEVIER/DECLARATIONS/DECLARATIONS/2008_07_01_Aaron_Swartz_Open_Access_Manifesto.pdf',
* title: 'Aaron Swartz Guerilla Manifesto',
* typing: true
* }
* ```
* @title Display a file in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const file = await bp.cms.renderElement(
'builtin_file',
{
type: 'file',
file:
'http://wavelets.ens.fr/BOYCOTT_ELSEVIER/DECLARATIONS/DECLARATIONS/2008_07_01_Aaron_Swartz_Open_Access_Manifesto.pdf',
title: 'Aaron Swartz Guerilla Manifesto',
typing: true
},
event
)
await bp.events.replyToEvent(event, file)
}
return myAction()
/** Your code ends here */
}Escolha Única
Este componente carrega uma mensagem, geralmente uma pergunta, e sugere escolhas ao usuário para cumprir a mensagem.
O usuário pode escolher apenas uma opção e, ao selecionar a preferência, instrua seu chatbot a obter um valor personalizado.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create a Single-choice content type in action.
* ```
* {
* type: 'single-choice',
* text: 'Ort Cloud',
* isDropdown: 'https://ia801901.us.archive.org/13/items/Home-Odyssey/Home-Odyssey-04OortCloud.mp3',
* dropdownPlaceholder: true,
* choices: [{ title: 'title', value: 'value' }],
* markdown: true,
* disableFreeText: true,
* typing: true
* },
* ```
* @title Display a single-choice in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const single_choice = await bp.cms.renderElement(
'builtin_single-choice',
{
type: 'single-choice',
text: 'Place to eat',
isDropdown: true,
dropdownPlaceholder: true,
choices: [
{ title: 'Burger Place', value: 'Burger' },
{ title: 'Salad Place', value: 'salad' }
],
markdown: true,
disableFreeText: true,
typing: true
},
event
)
await bp.events.replyToEvent(event, single_choice)
}
return myAction()
/** Your code ends here */
}Texto
O tipo de conteúdo de texto é uma mensagem de texto normal com indicadores de digitação opcionais e alternativas. Utilize markdown em seu texto para adicionar formatação e estilo, mas certifique-se de que o canal de destino possa renderizar esse texto.
É possível escrever em HTML no conteúdo de texto no canal da web e seu chatbot irá renderizá-lo corretamente.
Isso abre a possibilidade de incluir iFrames e construir páginas da Web em miniatura (comumente conhecidas como visualizações da Web) em seu conteúdo sem criar componentes personalizados.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create a text content type in a action.
* ```
* {
* type: 'text',
* text: 'hello World !',
* variations: ['Greeting', 'Bonjour tout le monde'],
* markdown: true,
* typing: true
* }
* ```
* @title Hello World with a Built-in text
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const text = await bp.cms.renderElement(
'builtin_text',
{ type: 'text', text: 'Hello World!', typing: true, markdown: true },
event
)
await bp.events.replyToEvent(event, text)
}
return myAction()
/** Your code ends here */
}Vídeo
Faça upload de um vídeo ou link para um arquivo de vídeo que será buscado quando o elemento de conteúdo for invocado.
function action(bp: typeof sdk, event: sdk.IO.IncomingEvent, args: any, { user, temp, session } = event.state) {
/** Your code starts below */
/**
* Show how to create a video content type in a action.
* ```
* {
* type: 'video',
* video: 'https://URL_TO_YOUR_VIDEO.mp4',
* title: 'Random_video',
* typing: true
* }
* ```
* @title Display an video in the action
* @category Content type
* @author Botpress
*/
const myAction = async () => {
const video = await bp.cms.renderElement(
'builtin_video',
{
type: 'video',
title : 'Lady Gaga',
video: 'https://ia601201.us.archive.org/4/items/Lady_GaGa_Poker_Face_/Lady%20GaGa_Poker%20Face%20.mp4',
typing: true
},
event
)
await bp.events.replyToEvent(event, video)
}
return myAction()
/** Your code ends here */
}