---
title: Ações
slug: helper-new/acoes
description: Learn about actions in Botpress, server-side functions executed by chatbots in conversation flows. Alter conversation state, send personalized messages, and run code with built-in actions like "Wait" and "Attach Context". Discover different types of conte
createdAt: 2022-08-29T12:44:19.000Z
---
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\_*)
:::CodeblockTabs
Exemplo
```javascript
/** 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`.
:::hint{type="info"}
🖊 **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
:::CodeblockTabs
Exemplo
```javascript
const wait = async delay => {
return new Promise(resolve => setTimeout(() => resolve(), delay))
}
return wait(args.delay || 1000)
```
:::
:::hint{type="info"}
🖊 **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.
:::hint{type="info"}
🖊 **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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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.
:::CodeblockTabs
Exemplo
````javascript
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 */
}
````
:::