Aviso de fim do suporte: em 15 de setembro de 2025, o suporte para o Amazon Lex V1 AWS será interrompido. Após 15 de setembro de 2025, você não poderá mais acessar o console do Amazon Lex V1 nem os respectivos recursos. Se você estiver usando o Amazon Lex V2, consulte o [guia do Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/what-is.html) em vez disso.
As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Amazon Lex: como funciona
O Amazon Lex permite criar aplicativos usando uma interface de texto ou de fala com a mesma tecnologia usada pelo Amazon Alexa. Veja a seguir as etapas comuns que você executa ao trabalhar com Amazon Lex:
1. Crie e configure um bot com uma ou mais intenções a que você deseja oferecer suporte. Configure o bot para que ele entenda o objetivo do usuário (intenção), inicie uma conversa com o usuário para obter informações e cumpra a intenção do usuário.
1. Teste o bot. Você pode usar o cliente da janela de teste fornecido pelo console do Amazon Lex.
1. Publique uma versão e crie um alias.
1. Implante o bot. Você pode implantar o bot em plataformas como aplicações móveis ou plataformas de mensagens, como Facebook Messenger.
Antes de começar a usar, familiarize-se com os seguintes conceitos principais e a terminologia do Amazon Lex:
+ **Bot**: um bot executa tarefas automatizadas, como pedir uma pizza, reservar um hotel, encomendar flores, e assim por diante. Um bot do Amazon Lex possui os recursos de reconhecimento automático de voz (ASR) e compreensão de linguagem natural (NLU). Cada bot deve ter um nome exclusivo na sua conta.
Os bots do Amazon Lex podem compreender a entrada do usuário fornecida por texto ou fala e conversar em linguagem natural. É possível criar funções do Lambda e adicioná-las como hooks de código em sua configuração de intenção para executar a validação de dados do usuário e tarefas de atendimento.
+ **Intenção**: uma intenção representa uma ação que o usuário deseja executar. Crie um bot para oferecer suporte a uma ou mais intenções relacionadas. Por exemplo, você pode criar um bot que peça pizza e bebidas. Para cada intenção, forneça as seguintes informações obrigatórias:
+ **Nome da intenção**: um nome descritivo para a intenção. Por exemplo, .**OrderPizza** Os nomes de função devem ser exclusivos em sua conta.
+ **Amostra de declarações**: como um usuário pode expressar a intenção. Por exemplo, um usuário pode dizer "Posso pedir uma pizza" ou "Quero pedir uma pizza".
+ **Como cumprir a intenção**: como você deseja cumprir a intenção depois que o usuário fornecer todas as informações necessárias (por exemplo, fazer um pedido com uma pizzaria local). Recomendamos criar uma função do Lambda para atender à intenção.
Opcionalmente, você pode configurar a intenção para que o Amazon Lex simplesmente retorne as informações de volta ao aplicativo cliente para executar o atendimento necessário.
Além de intenções personalizadas, como encomendar uma pizza, o Amazon Lex também fornece intenções integradas para configurar seu bot rapidamente. Para obter mais informações, consulte [Intenções integradas e tipos de slot](howitworks-builtins.md).
+ **Slot**: uma intenção pode exigir zero ou mais slots ou parâmetros. Você adiciona slots como parte da configuração de intenção. Em runtime, o Amazon Lex solicita ao usuário valores específicos do slot. O usuário deve fornecer valores para todos os slots *necessários* para que o Amazon Lex possa atender à intenção.
Por exemplo, a intenção `OrderPizza` exige slots como tamanho da pizza, tipo de massa e número de pizzas. Na configuração de intenção, você adiciona esses slots. Para cada slot, você fornece o tipo de slot e um prompt para o Amazon Lex enviar ao cliente para obter os dados do usuário. Um usuário pode responder com um valor de slot que inclui palavras adicionais, como "pizza grande, por favor" ou "vamos querer a pequena". O Amazon Lex ainda consegue entender o valor pretendido do slot.
+ **Tipo de slot**: cada slot possui um tipo. Você pode criar tipos de slot personalizados ou usar tipos de slot integrados. Cada tipo de slot deve ter um nome exclusivo na sua conta. Por exemplo, você pode criar e usar os seguintes tipos de slot para a intenção `OrderPizza`:
+ Tamanho – Com valores de enumeração `Small`, `Medium` e `Large`.
+ Massa – Com valores de enumeração `Thick` e `Thin`.
O Amazon Lex também fornece tipos de slot integrados. Por exemplo, `AMAZON.NUMBER` é um tipo de slot integrado que você pode usar para o número de pizzas pedidas. Para obter mais informações, consulte [Intenções integradas e tipos de slot](howitworks-builtins.md).
Para obter uma lista de regiões da AWS onde o Amazon Lex está disponível, consulte [Regiões e endpoints da AWS](https://docs.aws.amazon.com/general/latest/gr/rande.html#lex_region) na *Referência geral do Amazon Web Services*.
Os tópicos a seguir fornecem informações adicionais. Recomendamos que você analise-as em ordem e, em seguida, explore os exercícios [Conceitos básicos do Amazon Lex](getting-started.md).
**Topics**
+ [Idiomas compatíveis com o Amazon Lex](how-it-works-language.md)
+ [Modelo de programação](programming-model.md)
+ [Gerenciamento de mensagens](howitworks-manage-prompts.md)
+ [Gerenciar contexto da conversa](context-mgmt.md)
+ [Usar pontuações de confiança](confidence-scores.md)
+ [Logs de conversa](conversation-logs.md)
+ [Gerenciamento de sessões com a API do Amazon Lex](how-session-api.md)
+ [Opções de implantação de bot](chatbot-service.md)
+ [Intenções integradas e tipos de slot](howitworks-builtins.md)
+ [Tipos de slot personalizados](howitworks-custom-slots.md)
+ [Ofuscação de slot](how-obfuscate.md)
+ [Análise de sentimento](sentiment-analysis.md)
+ [Marcação de seus recursos do Amazon Lex](how-it-works-tags.md)
# Idiomas compatíveis com o Amazon Lex
O Amazon Lex V1 oferece suporte a uma série de Idiomas e localidades. Os idiomas compatíveis e os atributos compatíveis estão listados nas tabelas a seguir.
O Amazon Lex V2 oferece suporte a outros idiomas, consulte [Idiomas compatíveis no Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/how-languages.html)
## Idiomas e locais compatíveis
O Amazon Lex V1 oferece suporte aos seguintes idiomas e locais.
| Código | Idioma e local |
| --- | --- |
| de-DE | Alemão (Alemanha) |
| en-AU | Inglês (Austrália) |
| en-GB | Inglês (Reino Unido) |
| en-IN | Inglês (Índia) |
| en-US | Inglês (EUA) |
| es-419 | Espanhol (América Latina) |
| es-ES | Espanhol (Espanha) |
| es-US | Espanhol (EUA) |
| fr-CA | Francês (Canadá) |
| fr-FR | Francês (França) |
| it-IT | Italiano (Itália) |
| ja-JP | Japonês (Japão) |
| ko-KR | Coreano (Coreia) |
## Idiomas e locais compatíveis com os atributos do Amazon Lex
Todos os atributos do Amazon Lex são compatíveis em todos os idiomas e locais, exceto conforme listado nesta tabela.
| Atributo | Idiomas e locais compatíveis |
| --- | --- |
| [Definir o contexto da intenção](context-mgmt-active-context.md) | Inglês (EUA) (en-US) |
# Modelo de programação
Um *bot* é o principal tipo de recurso no Amazon Lex. Os outros tipos de recursos no Amazon Lex; são *intenção*, *tipo de slot*, *alias* e *associação de canal de bot*.
Você cria um bot usando o console do Amazon Lex ou a API de criação de modelos. O console fornece uma interface gráfica de usuário que você usa para criar um bot pronto para produção para seu aplicativo. Se preferir, você pode usar a API de criação de modelos por meio do AWS CLI ou de seu próprio programa personalizado para criar um bot.
Depois de criar um bot, você o implanta em uma das [plataformas compatíveis](https://docs.aws.amazon.com/lex/latest/dg/chatbot-service.html) ou o integra em seu próprio aplicativo. Quando um usuário interage com o bot, o aplicativo cliente envia solicitações ao bot usando a API de runtime do Amazon Lex. Por exemplo, quando um usuário diz "Quero encomendar uma pizza", o cliente envia essa entrada do usuário ao Amazon Lex usando uma das operações da API de runtime. Os usuários podem fornecer entrada de voz ou texto.
Você também pode criar funções do Lambda; e usá-las em uma intenção. Use esses hooks de código de função do Lambda para executar atividades em runtime, como inicialização, validação da entrada do usuário e atendimento da intenção. As seções a seguir fornecem informações adicionais.
**Topics**
+ [Operações de API de criação de modelo](#programming-model-build-time-api)
+ [Operações de API de runtime](#programming-model-runtime-api)
+ [Funções do Lambda como hooks de código](#prog-model-lambda)
## Operações de API de criação de modelo
Para criar programaticamente bots, intenções e tipos de slot, use a API de operações de criação de modelo. Você também pode usar a API de criação de modelo para gerenciar, atualizar e excluir os recursos para o seu bot. As operações de API de criação de modelo incluem:
+ [PutBot](API_PutBot.md), [PutBotAlias](API_PutBotAlias.md), [PutIntent](API_PutIntent.md)e [PutSlotType](API_PutSlotType.md) para criar e atualizar bots, aliases de bot, intenções e tipos de slot, respectivamente.
+ [CreateBotVersion](API_CreateBotVersion.md), [CreateIntentVersion](API_CreateIntentVersion.md) e [CreateSlotTypeVersion](API_CreateSlotTypeVersion.md) para criar e publicar versões de seus bots, intenções e tipos de slot, respectivamente.
+ [GetBot](API_GetBot.md) e [GetBots](API_GetBots.md) para obter um bot específico ou uma lista de bots que você criou, respectivamente.
+ [GetIntent](API_GetIntent.md) e [GetIntents](API_GetIntents.md) para obter uma intenção específica ou uma lista de intenções que você criou, respectivamente.
+ [GetSlotType](API_GetSlotType.md) e [GetSlotTypes](API_GetSlotTypes.md) para obter um tipo de slot específico ou uma lista de tipos de slot que você criou, respectivamente.
+ [GetBuiltinIntent](API_GetBuiltinIntent.md), [GetBuiltinIntents](API_GetBuiltinIntents.md) e [GetBuiltinSlotTypes](API_GetBuiltinSlotTypes.md) para obter uma intenção integrada do Amazon Lex, uma lista de intenções integradas do Amazon Lex ou uma lista de tipos de slot integrado que você pode usar em seu bot, respectivamente.
+ [GetBotChannelAssociation](API_GetBotChannelAssociation.md) e [GetBotChannelAssociations](API_GetBotChannelAssociations.md) para obter uma associação entre seu bot e uma plataforma de mensagens ou uma lista de associações entre seu bot e plataformas de mensagens, respectivamente.
+ [DeleteBot](API_DeleteBot.md), [DeleteBotAlias](API_DeleteBotAlias.md), [DeleteBotChannelAssociation](API_DeleteBotChannelAssociation.md), [DeleteIntent](API_DeleteIntent.md) e [DeleteSlotType](API_DeleteSlotType.md) para remover recursos desnecessários em sua conta.
Você pode usar a API de criação de modelo para criar ferramentas personalizadas a fim de gerenciar os recursos do Amazon Lex. Por exemplo, há um limite de 100 versões para bots, intenções e tipos de slot. Você pode usar a API de criação de modelo para criar uma ferramenta que exclui automaticamente versões antigas quando o bot se aproxima do limite.
Para garantir que apenas uma operação atualize um recurso por vez, o Amazon Lex usa somas de verificação. Quando usa uma operação de API `Put`, [PutBot](API_PutBot.md), [PutBotAlias](API_PutBotAlias.md) [PutIntent](API_PutIntent.md) ou [PutSlotType](API_PutSlotType.md), para atualizar um recurso, você deve passar a soma de verificação atual do recurso na solicitação. Se duas ferramentas tentarem atualizar um recurso ao mesmo tempo, elas oferecem a mesma soma de verificação atual. A primeira solicitação a alcançar o Amazon Lex corresponde à soma de verificação atual do recurso. Quando a segunda solicitação chega, a soma de verificação é diferente. A segunda ferramenta recebe uma exceção `PreconditionFailedException` e a atualização é encerrada.
As operações `Get`, [GetBot](API_GetBot.md), [GetIntent](API_GetIntent.md) e [GetSlotType](API_GetSlotType.md), são eventualmente consistentes. Se você usar uma operação `Get` imediatamente após criar ou modificar um recurso com uma das operações `Put`, as alterações poderão não ser retornadas. Depois de uma operação `Get` retornar a atualização mais recente, ela sempre retornará esse recurso atualizado até que o recurso seja modificado novamente. Você pode determinar se um recurso atualizado foi retornado ao analisar a soma de verificação.
## Operações de API de runtime
Os aplicativos cliente usam as seguintes operações de API em runtime para se comunicar com o Amazon Lex:
+ [PostContent](API_runtime_PostContent.md) - Usa entrada de texto ou fala e retorna informações de intenção e uma mensagem de texto ou fala para expressar ao usuário. No momento, o Amazon Lex é oferece suporte aos seguintes formatos de áudio:
Formatos de áudio de entrada – LPCM e Opus
Formatos de áudio de saída – MPEG, OGG e PCM
A operação `PostContent` oferece suporte a entrada de áudio em 8 kHz e 16 kHz. Os aplicativos em que o usuário final se comunica com o Amazon Lex por telefone, como uma central de atendimento automatizada, podem passar áudio 8 kHz diretamente.
+ [PostText](API_runtime_PostText.md) - Usa texto como entrada e retorna informações de intenção e uma mensagem de texto para transmitir ao usuário.
Seu aplicativo cliente usa a API de runtime para chamar um determinado bot do Amazon Lex para processar declarações entrada de texto ou de fala do usuário. Por exemplo, suponha que um usuário diga "Quero pizza". O cliente envia essa entrada do usuário a um bot usando uma das operações da API de runtime do Amazon Lex. A partir da entrada do usuário, o Amazon Lex; reconhece que a solicitação do usuário destina-se à intenção `OrderPizza` definida no bot. O Amazon Lex engaja o usuário em uma conversa para obter as informações necessárias, ou dados de slot, como tamanho da pizza, cobertura e número de pizzas. Depois que o usuário fornece todos os dados necessários do slot, o Amazon Lex invoca o hook de código da função do Lambda para atender à intenção ou retorna os dados da intenção para o cliente, dependendo de como a intenção está configurada.
Use a operação [PostContent](API_runtime_PostContent.md) quando seu bot usa entrada de voz. Por exemplo, um aplicativo de call center automatizado pode enviar fala para um bot do Amazon Lex, e não para um atendente, para resolver indagações do cliente. Você pode usar o formato de áudio de 8 kHz para enviar áudio diretamente do telefone para o Amazon Lex.
A janela de teste no console do Amazon Lex usa a API [PostContent](API_runtime_PostContent.md) para enviar solicitações de texto e de fala para o Amazon Lex. Use esta janela de teste nos exercícios [Conceitos básicos do Amazon Lex](getting-started.md).
## Funções do Lambda como hooks de código
Você pode configurar seu bot do Amazon Lex para invocar uma função do Lambda como um hook de código. O hook de código pode servir para várias finalidades:
+ Personaliza a interação do usuário. Por exemplo, quando Joe pergunta pelas coberturas de pizza disponíveis, você pode usar o conhecimento anterior das opções de Joe para exibir um subconjunto de coberturas.
+ Valida a entrada do usuário. Suponha que Jen queira escolher flores depois do horário de funcionamento. Você pode validar o horário que Jen inseriu e enviar uma resposta adequada.
+ Atende à intenção do usuário. Depois de Joe fornecer todas as informações sobre seu pedido de pizza, o Amazon Lex pode invocar uma função do Lambda para fazer o pedido em uma pizzaria local.
Ao configurar uma intenção, você especifica funções do Lambda como hooks de código nos seguintes locais:
+ Hook de código de diálogo para inicialização e validação: essa função do Lambda é invocada em cada entrada do usuário, supondo que o Amazon Lex tenha entendido a intenção do usuário.
+ Hook de código de atendimento: essa função do Lambda;é invocada depois que o usuário fornece todos os dados de slot necessários para atender a intenção.
Você escolhe a intenção e define os hooks de código no console do Amazon Lex, conforme mostrado na captura de tela a seguir:
![\[O console do Amazon Lex mostrando hooks de código da função do Lambda.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/how-works-10.png)
Você também pode definir hooks de código usando os campos `dialogCodeHook` e `fulfillmentActivity` na operação [PutIntent](API_PutIntent.md).
Uma função do Lambda pode executar a inicialização, a validação e o atendimento. Os dados do evento que a função do Lambda recebe têm um campo que identifica o chamador como um hook de código de diálogo ou de atendimento. É possível usar essas informações para executar a parte adequada de seu código.
Você pode usar uma função do Lambda para criar um bot que pode navegar por diálogos complexos. Você usa o campo `dialogAction` na resposta da função do Lambda para direcionar o Amazon Lex para executar ações específicas. Por exemplo, você pode usar a ação do diálogo `ElicitSlot` para dizer ao Amazon Lex para solicitar ao usuário um valor de slot que não é necessário. Se você tiver um prompt de esclarecimento definido, poderá usar a ação de diálogo `ElicitIntent` para obter uma nova intenção quando o usuário terminar de usar a anterior.
Para obter mais informações, consulte [Uso de funções do Lambda](using-lambda.md).
# Gerenciamento de mensagens
**Topics**
+ [Tipos de mensagens](#msg-prompts-msg-types)
+ [Contextos para a configuração de mensagens](#msg-prompts-context-for-msgs)
+ [Formatos de mensagem suportados](#msg-prompts-formats)
+ [Grupos de mensagens](#message-groups)
+ [Cartões de resposta](#msg-prompts-resp-card)
Ao criar um bot, você pode configurar mensagens de esclarecimento ou informativas que deseja que ele envie ao cliente. Considere os seguintes exemplos:
+ Você pode configurar seu bot com a solicitação de esclarecimento a seguir:
```
I don't understand. What would you like to do?
```
O Amazon Lex envia essa mensagem para o cliente, caso não entenda a intenção do usuário.
+ Suponha que você crie um bot para oferecer suporte a uma intenção chamada `OrderPizza`. Para pedidos de pizza, você deseja que os usuários forneçam informações como tamanho da pizza, cobertura e tipo de massa. Você pode configurar as seguintes solicitações:
```
What size pizza do you want?
What toppings do you want?
Do you want thick or thin crust?
```
Assim que o Amazon Lex determina a intenção do usuário de pedir uma pizza, ele envia estas mensagens ao cliente para obter informações do usuário.
Esta seção explica como projetar interações do usuário em sua configuração de bot.
## Tipos de mensagens
A mensagem pode ser uma solicitação ou instrução.
+ Normalmente, o *prompt* é uma pergunta que presume uma resposta do usuário.
+ A *instrução* é apenas informativa. Ela não presume uma resposta.
Uma mensagem pode incluir referências a slot, atributos de sessão e atributos de solicitação. Em runtime, o Amazon Lex substitui essas referências com valores reais.
Para se referir a valores de slots que foram definidos, use a seguinte sintaxe:
```
{SlotName}
```
Para se referir a atributos de sessão, use a seguinte sintaxe:
```
[SessionAttributeName]
```
Para se referir a atributos de solicitação, use a seguinte sintaxe:
```
((RequestAttributeName))
```
As mensagens podem incluir valores de slot, atributos de sessão e atributos de solicitação.
Por exemplo, suponha que você configure a seguinte mensagem na OrderPizza intenção do seu bot:
```
"Hey [FirstName], your {PizzaTopping} pizza will arrive in [DeliveryTime] minutes."
```
Essa mensagem refere-se tanto ao slot (`PizzaTopping`) quanto aos atributos de sessão (`FirstName` e `DeliveryTime`). Em runtime, o Amazon Lex substitui estes espaços reservados por valores e retorna a seguinte mensagem para o cliente:
```
"Hey John, your cheese pizza will arrive in 30 minutes."
```
Para incluir colchetes ([]) ou chaves (\$1\$1) em uma mensagem, use o caractere de escape de barra invertida (\$1). Por exemplo, a seguinte mensagem inclui chaves e colchetes:
```
\{Text\} \[Text\]
```
O texto retornado ao aplicativo cliente é semelhante a este:
```
{Text} [Text]
```
Para obter mais informações sobre atributos de sessão, consulte as operações de API [PostText](API_runtime_PostText.md) e [PostContent](API_runtime_PostContent.md). Para ver um exemplo, consulte [Reservar uma viagem](ex-book-trip.md).
As funções do Lambda também podem gerar mensagens e retorná-las ao Amazon Lex para envio ao usuário. Se você adicionar funções do Lambda ao configurar sua intenção, poderá criar mensagens dinamicamente. Se fornecer as mensagens ao configurar o bot, você poderá eliminar a necessidade de criar um prompt na função do Lambda.
## Contextos para a configuração de mensagens
Ao criar um bot, você pode criar mensagens em contextos diferentes, como solicitações de esclarecimento no bot, prompts de valores de slot e mensagens de intenções. O Amazon Lex escolhe uma mensagem apropriada em cada contexto para retornar ao usuário. Você pode fornecer um grupo de mensagens para cada contexto. Se você fizer isso, o Amazon Lex selecionará aleatoriamente uma mensagem no grupo. Você pode também especificar o formato da mensagem ou agrupar as mensagens. Para obter mais informações, consulte [Formatos de mensagem suportados](#msg-prompts-formats).
Se tiver uma função do Lambda associada a uma intenção, você poderá substituir qualquer uma das mensagens configuradas no momento da compilação. No entanto, para usar qualquer uma dessas mensagens, não é preciso ter uma função do Lambda.
### Mensagens de bot
Você pode configurar seu bot com prompts de esclarecimento e mensagens de encerramento. Em runtime, o Amazon Lex usa o prompt de esclarecimento** quando não compreende a intenção do usuário. Você pode configurar o número de vezes que o Amazon Lex solicita esclarecimentos antes de enviar a mensagem de fim da sessão. Você configura as mensagens em nível de bot na seção **Tratamento de erros** do console do Amazon Lex, da seguinte forma:
![\[Seção Tratamento de erros na guia do editor do console. Prompts de esclarecimento e uma frase de encerramento podem ser especificadas.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/how-works-20.png)
Com a API, você configura mensagens definindo os campos `clarificationPrompt` e `abortStatement` na operação [PutBot](API_PutBot.md).
Se você usar uma função do Lambda com uma intenção, a função do Lambda pode retornar uma resposta direcionando o Amazon Lex a solicitar uma intenção do usuário. Se a função do Lambda; não fornecer essa mensagem, o Amazon Lex usará o prompt de esclarecimento.
### Prompts de slot
É necessário especificar pelo menos uma mensagem de prompt para os slots necessários em uma intenção. Em runtime, o Amazon Lex usa uma dessas mensagens para solicitar que o usuário forneça um valor para o slot. Por exemplo, para um slot `cityName`, o seguinte é um prompt válido:
```
Which city would you like to fly to?
```
Você pode definir uma ou mais solicitações para cada slot usando o console. Você pode também criar grupos de solicitações usando a operação [PutIntent](API_PutIntent.md). Para obter mais informações, consulte [Grupos de mensagens](#message-groups).
### Respostas
No console, use a seção **Respostas** para criar conversas dinâmicas e envolventes para seu bot. Você pode criar um ou mais grupos de mensagens para uma resposta. Em runtime, o Amazon Lex cria uma resposta selecionando uma mensagem de cada grupo de mensagens. Para obter mais informações sobre grupos de mensagens, consulte [Grupos de mensagens](#message-groups).
Por exemplo, o primeiro grupo de mensagens pode conter diferentes saudações: "OIá", "Oi" e "Saudações". O segundo grupo de mensagens pode conter diferentes formas de introdução: "Sou o bot de reserva" e "Este é o bot de reserva". Um terceiro grupo de mensagens pode informar os recursos do bot: "Posso ajudar com aluguel de carro e reservas de hotéis", "Você pode alugar carros e fazer reservas de hotel" e "Eu posso ajudar você a alugar um carro e reservar um hotel".
O Lex usa uma mensagem de cada um dos grupos de mensagens para criar as respostas dinamicamente em uma conversa. Por exemplo, uma interação pode ser:
![\[Uma possível conversa com um bot.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/default-response-10b.png)
Outro poderia ser o seguinte:
![\[Outra possível conversa com um bot.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/default-response-20c.png)
Em qualquer um dos casos, o usuário pode responder com uma nova intenção, como a intenção `BookCar` ou `BookHotel`.
Você pode configurar o bot para fazer uma pergunta complementar na resposta. Por exemplo, para a interação anterior, você pode criar um quarto grupo de mensagens com as seguintes perguntas: "Posso ajudar com um carro ou um hotel?", "Você gostaria de fazer uma reserva agora?" e "Há algo que possa fazer para você?". Para mensagens que incluam "Não" como resposta, você pode criar um prompt de acompanhamento. A imagem seguir fornece um exemplo:
![\[Prompt de acompanhamento em uma conversa com um bot.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/default-response-25a.png)
Para criar um prompt de acompanhamento, escolha **Aguardar resposta do usuário**. Em seguida, digite a mensagem ou as mensagens que você deseja enviar quando o usuário disser "Não". Ao criar uma resposta para usar como prompt de acompanhamento, você devem especificar também uma instrução apropriada quando a resposta para a instrução for "Não". Para obter um exemplo, veja a imagem a seguir.
![\[Configuração de mensagem para quando um usuário diz "não".\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/default-response-30b.png)
Para adicionar respostas a uma intenção com a API, use a operação `PutIntent`. Para especificar uma resposta, defina o campo `conclusionStatement` na solicitação `PutIntent`. Para definir uma solicitação de acompanhamento, defina o campo `followUpPrompt` e inclua a instrução a ser enviada quando o usuário disser "Não". Você não pode definir o campo `conclusionStatement` e o campo `followUpPrompt` na mesma intenção.
## Formatos de mensagem suportados
Quando você a operação [PostText](API_runtime_PostText.md) ou a operação [PostContent](API_runtime_PostContent.md) com o cabeçalho `Accept` definido como `text/plain;charset=utf8`, o Amazon Lex oferece suporte a mensagens nos seguintes formatos:
+ `PlainText`: a mensagem contém texto sem formatação UTF-8.
+ `SSML`: a mensagem contém texto formatado para saída de voz.
+ `CustomPayload`: a mensagem contém um formato personalizado que você criou para seu cliente. Você pode definir a carga útil para atender às necessidades de seu aplicativo.
+ `Composite`: a mensagem é uma coleção de mensagens, uma de cada grupo de mensagens. Para obter mais informações sobre grupos de mensagens, consulte [Grupos de mensagens](#message-groups).
Por padrão, o Amazon Lex retorna qualquer uma das mensagens definidas para determinado prompt. Por exemplo, se você definir cinco mensagens para obter um valor de slot, o Amazon Lex escolherá uma das mensagens aleatoriamente e a retornará para o cliente.
Se quiser que o Amazon Lex retorne um tipo específico de mensagem para o cliente em uma solicitação de runtime, defina o parâmetro de solicitação `x-amzn-lex:accept-content-types`. A resposta é limitada pelo tipo ou pelos tipos solicitados. Se houver mais de uma mensagem do tipo especificado, o Amazon Lex retornará uma aleatoriamente. Para obter mais informações sobre o cabeçalho `x-amz-lex:accept-content-types`, consulte [Como configurar o tipo de resposta](context-mgmt-request-attribs.md#special-response).
## Grupos de mensagens
Um *grupo de mensagens* é um conjunto de respostas adequadas para determinada solicitação. Use grupos de mensagens quando quiser que seu bot crie dinamicamente as respostas em uma conversa. Quando o Amazon Lex retorna uma resposta ao aplicativo cliente, ele escolhe aleatoriamente uma mensagem de cada grupo. Você pode criar no máximo cinco grupos de mensagens para cada resposta. Cada grupo pode conter no máximo cinco mensagens. Para obter exemplos de como criar grupos de mensagens no console, consulte [Respostas](#msg-prompts-response).
Para criar um grupo de mensagens, você pode usar o console ou as operações [PutBot](API_PutBot.md), [PutIntent](API_PutIntent.md) ou [PutSlotType](API_PutSlotType.md) para atribuir um número de grupo a uma mensagem. Se você não criar um grupo de mensagens ou se criar apenas um grupo, o Amazon Lex enviará uma única mensagem no campo `Message`. Os aplicativos cliente recebem várias mensagens em uma resposta somente quando você cria mais de um grupo de mensagens no console ou mais de um grupo de mensagens ao criar ou atualizar uma intenção com a operação [PutIntent](API_PutIntent.md).
Quando o Amazon Lex envia uma mensagem de um grupo, o campo `Message` da resposta contém um objeto JSON de escape que contém as mensagens. O exemplo a seguir mostra o conteúdo do campo `Message` quando ele contém várias mensagens.
**nota**
O exemplo é formatado por motivo de legibilidade. Uma resposta não contém retornos de carro (CR).
```
{\"messages\":[
{\"type\":\"PlainText\",\"group\":0,\"value\":\"Plain text\"},
{\"type\":\"SSML\",\"group\":1,\"value\":\"SSML text\"},
{\"type\":\"CustomPayload\",\"group\":2,\"value\":\"Custom payload\"}
]}
```
Você pode definir o formato das mensagens. O formato pode ser um dos seguintes:
+ PlainText—A mensagem está em texto UTF-8 simples.
+ SSML: o formato da mensagem é Linguagem de marcação de síntese de fala (SSML).
+ CustomPayload—A mensagem está em um formato personalizado que você especificou.
Para controlar o formato das mensagens que as operações `PostContent` e `PostText` retornam no campo `Message`, defina o atributo de solicitação `x-amz-lex:accept-content-types`. Por exemplo, se você definir o cabeçalho como a seguir, você receberá apenas texto sem formatação e mensagens SSML na resposta:
```
x-amz-lex:accept-content-types: PlainText,SSML
```
Se solicitar um formato específico de mensagem e um grupo de mensagens não contiver uma mensagem com esse formato, você obterá uma exceção `NoUsableMessageException`. Quando usar um grupo de mensagens para agrupar mensagens por tipo, não use o cabeçalho `x-amz-lex:accept-content-types`.
Para obter mais informações sobre o cabeçalho `x-amz-lex:accept-content-types`, consulte [Como configurar o tipo de resposta](context-mgmt-request-attribs.md#special-response).
## Cartões de resposta
**nota**
Os cartões de resposta não funcionam com o chat do Amazon Connect. No entanto, consulte [ Adicionar mensagens interativas ao chat](https://docs.aws.amazon.com/connect/latest/adminguide/interactive-messages.html) para obter uma funcionalidade semelhante.
Um *cartão de resposta* contém um conjunto de respostas adequadas a um prompt. Use cartões de resposta para simplificar interações para seus usuários e aumentar a precisão de seu bot ao reduzir erros tipográficos nas interações de texto. Você pode enviar um cartão de resposta para cada prompt que o Amazon Lex envia a seu aplicativo cliente. Você pode usar cartões de resposta com o Facebook Messenger, o Slack, o Twilio e seus próprios aplicativos clientes.
Por exemplo, em um aplicativo de táxi, você pode configurar uma opção no cartão de resposta para "Casa" e defina o valor para o endereço residencial do usuário. Quando o usuário seleciona essa opção, o Amazon Lex recebe o endereço inteiro como o texto de entrada. Veja a imagem a seguir:
![\[Um cartão de resposta de exemplo.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/resp-console-5.png)
Você pode definir um cartão de resposta para os seguintes prompts:
+ Declaração de conclusão
+ Prompt de confirmação
+ Prompt de acompanhamento
+ Declaração de rejeição
+ Declarações de tipo de slot
Você pode definir apenas um cartão de resposta para cada prompt.
Você configura cartões de resposta ao criar uma intenção. Você pode definir um cartão de resposta estático no momento da criação usando o console ou a operação [PutIntent](API_PutIntent.md). Ou você pode definir um cartão de resposta dinâmica em runtime em uma função do Lambda. Se você definir cartões de resposta estática e dinâmica, a o cartão de resposta dinâmica terá precedência.
O Amazon Lex envia cartões de resposta no formato que o cliente compreende. Ele transforma cartões de resposta para Facebook Messenger, Slack e Twilio. Para outros clientes, o Amazon Lex envia uma estrutura JSON na resposta [PostText](API_runtime_PostText.md). Por exemplo, se o cliente for o Facebook Messenger, o Amazon Lex transformará o cartão de resposta para um modelo genérico. Para obter mais informações sobre os modelos genéricos do Facebook Messenger, consulte [Modelo genérico](https://developers.facebook.com/docs/messenger-platform/send-api-reference/generic-template) no site do Facebook. Para ver um exemplo de estrutura JSON, consulte [Geração dinâmica de cartões de resposta](#msg-prompts-resp-card-dynamic).
Você pode usar cartões de resposta somente com a operação [PostText](API_runtime_PostText.md). Você não pode usar cartões de resposta com a operação [PostContent](API_runtime_PostContent.md).
### Definição de cartões de resposta estática
Defina cartões de resposta estática com a operação [PutBot](API_PutBot.md) ou o console do Amazon Lex ao criar uma intenção. Um cartão de resposta estática é definido ao mesmo tempo que a intenção. Use um cartão de resposta estática quando as respostas são fixas. Suponha que você está criando um bot com uma intenção que tem um slot para sabor. Ao definir o slot de sabor, você especifica prompts, como mostrado na seguinte captura de tela do console:
![\[O editor da intenção no console.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/resp-console-10a.png)
Ao definir prompts, você tem a opção de associar um cartão de resposta e definir detalhes na operação [PutBot](API_PutBot.md) ou no console do Amazon Lex, conforme mostrado no exemplo a seguir:
![\[O console mostrando o editor de cartão de resposta.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/resp-console-20a.png)
Agora, suponha que você integrou o bot ao Facebook Messenger. O usuário pode clicar nos botões para escolher uma sabor, como mostrado na ilustração a seguir:
![\[Um cartão de resposta no Facebook Messenger.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/resp-fb-exampleA.png)
Para personalizar o conteúdo de um cartão de resposta, você pode consultar atributos da sessão. Em runtime, o Amazon Lex substitui essas referências pelos valores adequados dos atributos de sessão. Para obter mais informações, consulte [Definição dos atributos da sessão](context-mgmt-session-attribs.md). Para ver um exemplo, consulte [Exemplo: uso de um cartão de resposta](ex-resp-card.md).
### Geração dinâmica de cartões de resposta
Para gerar cartões de resposta dinamicamente em runtime, use a função do Lambda de inicialização e validação para a intenção. Use um cartão de resposta dinâmica quando as respostas forem determinadas em runtime na função do Lambda. Em resposta à entrada do usuário, a função do Lambda gera um cartão de resposta e o retorna na seção `dialogAction` da resposta. Para obter mais informações, consulte [Formato de resposta](lambda-input-response-format.md#using-lambda-response-format).
A seguir, veja uma resposta de uma função do Lambda; parcial que mostra o elemento `responseCard`. Ele gera uma experiência do usuário semelhante à mostrada na seção anterior.
```
responseCard: {
"version": 1,
"contentType": "application/vnd.amazonaws.card.generic",
"genericAttachments": [
{
"title": "What Flavor?",
"subtitle": "What flavor do you want?",
"imageUrl": "Link to image",
"attachmentLinkUrl": "Link to attachment",
"buttons": [
{
"text": "Lemon",
"value": "lemon"
},
{
"text": "Raspberry",
"value": "raspberry"
},
{
"text": "Plain",
"value": "plain"
}
]
}
]
}
```
Para ver um exemplo, consulte [Agendar uma consulta](ex1-sch-appt.md).
# Gerenciar contexto da conversa
*Contexto de conversa* são as informações que um usuário, seu aplicativo ou uma função do Lambda fornece a um bot do Amazon Lex para atender a uma intenção. O contexto da conversa inclui dados de slot que o usuário fornece, atributos de solicitação definidos pelo aplicativo cliente e atributos de sessão que o aplicativo cliente e as funções do Lambda criam.
**Topics**
+ [Definir o contexto da intenção](context-mgmt-active-context.md)
+ [Usar valores de slot padrão](context-mgmt-default.md)
+ [Definição dos atributos da sessão](context-mgmt-session-attribs.md)
+ [Definição de atributos de solicitação](context-mgmt-request-attribs.md)
+ [Definição do tempo limite da sessão](context-mgmt-session-timeout.md)
+ [Compartilhamento de informações entre intenções](context-mgmt-cross-intent.md)
+ [Configuração de atributos complexos](context-mgmt-complex-attributes.md)
# Definir o contexto da intenção
Você pode fazer com que o Amazon Lex acione intenções com base no *contexto*. Um *contexto* é uma variável de estado que pode ser associada a uma intenção quando você define um bot.
Você configura os contextos de uma intenção ao criar a intenção usando o console ou usando a operação [PutIntent](API_PutIntent.md). Você só pode usar contextos na localidade em inglês (EUA) (en-US) e somente se definir o parâmetro `enableModelImprovements` para `true` quando criou o bot com a operação [PutBot](API_PutBot.md).
Existem dois tipos de relacionamentos para contextos: contextos de saída e contextos de entrada. Um *contexto de saída* se torna ativo quando uma intenção associada é cumprida. Um contexto de saída é retornado ao seu aplicativo na resposta da operação [PostText](API_runtime_PostText.md) ou [PostContent](API_runtime_PostContent.md), e é definido para a sessão atual. Depois que um contexto é ativado, ele permanece ativo pelo número de turnos ou limite de tempo configurado quando o contexto foi definido.
Um *contexto de entrada* especifica as condições sob as quais uma intenção pode ser reconhecida. Uma intenção só pode ser reconhecida durante uma conversa quando todos os contextos de entrada estão ativos. Uma intenção sem contextos de entrada é sempre elegível para reconhecimento.
O Amazon Lex gerencia automaticamente o ciclo de vida dos contextos que são ativados ao cumprir as intenções com contextos de saída. Você também pode definir contextos ativos em uma chamada para a operação `PostContent` ou `PostText`.
Também é possível definir o contexto de uma conversa usando a função do Lambda para a intenção. O contexto de saída do Amazon Lex é enviado para o evento de entrada da função do Lambda. A função do Lambda pode enviar contextos em sua resposta. Para obter mais informações, consulte [Evento de entrada de função do Lambda e formato de resposta](lambda-input-response-format.md).
Por exemplo, suponha que você tenha a intenção de reservar um carro alugado configurado para retornar um contexto de saída chamado "book\$1car\$1fulfilled". Quando a intenção é cumprida, o Amazon Lex define a variável de contexto de saída "book\$1car\$1fulfilled". Como "book\$1car\$1fulfilled" é um contexto ativo, uma intenção com o contexto "book\$1car\$1fulfilled" definido como um contexto de entrada agora é considerada para reconhecimento, desde que a declaração do usuário seja reconhecida como uma tentativa de obter essa intenção. Você pode usar isso para intenções que só façam sentido depois de reservar um carro, como enviar um recibo por e-mail ou modificar uma reserva.
## Contexto de saída
O Amazon Lex ativa os contextos de saída de uma intenção quando a intenção é cumprida. Você pode usar o contexto de saída para controlar as intenções elegíveis para acompanhar a intenção atual.
Cada contexto tem uma lista de parâmetros que são mantidos na sessão. Os parâmetros são os valores de slot para a intenção cumprida. Você pode usar esses parâmetros para preencher previamente os valores de slot para outras finalidades. Para obter mais informações, consulte [Usar valores de slot padrão](context-mgmt-default.md).
Você configura o contexto de saída ao criar uma intenção com o console ou com a operação [PutIntent](API_PutIntent.md). Você pode configurar uma intenção com mais de um contexto de saída. Quando a intenção é cumprida, todos os contextos de saída são ativados e retornados na resposta [PostText](API_runtime_PostText.md) ou [PostContent](API_runtime_PostContent.md).
Veja a seguir como atribuir um contexto de saída a uma intenção usando o console.
![\[Etiqueta de saída rotulada order_complete com um tempo de vida de 5 voltas ou 90 segundos.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/context-output.png)
Ao definir um contexto de saída, você também define seu *tempo de vida*, a duração ou o número de turnos em que o contexto é incluído nas respostas do Amazon Lex. Um *turno* é uma solicitação do seu aplicativo para o Amazon Lex. Depois que o número de turnos ou o tempo expirar, o contexto não ficará mais ativo.
Seu aplicativo pode usar o contexto de saída conforme necessário. Por exemplo, seu aplicativo pode usar o contexto de saída para:
+ Altere o comportamento do aplicativo com base no contexto. Por exemplo, um aplicativo de viagens pode ter uma ação diferente para o contexto "book\$1car\$1fulfilled" e "rental\$1hotel\$1fulfilled".
+ Retorne o contexto de saída para o Amazon Lex como contexto de entrada para a próxima declaração. Se o Amazon Lex reconhecer a declaração como uma tentativa de extrair uma intenção, ele usa o contexto para limitar as intenções que podem ser retornadas àquelas com o contexto especificado.
## Contexto de entrada
Você define um contexto de entrada para limitar os pontos da conversa em que a intenção é reconhecida. Intenções sem um contexto de entrada são sempre elegíveis para serem reconhecidas.
Você define os contextos de entrada aos quais uma intenção responde usando o console ou a operação `PutIntent`. Uma intenção pode ter mais de um contexto de entrada. Veja a seguir como atribuir um contexto de entrada a uma intenção usando o console.
![\[Tag de entrada denominada order_complete.\]](http://docs.aws.amazon.com/pt_br/lex/latest/dg/images/context-input.png)
Para uma intenção com mais de um contexto de entrada, todos os contextos devem estar ativos para acionar a intenção. Você pode definir um contexto de entrada ao chamar a operação [PostText](API_runtime_PostText.md), [PostContent](API_runtime_PostContent.md) ou [PutSession](API_runtime_PutSession.md).
Você pode configurar os slots em uma intenção para obter valores padrão do contexto ativo atual. Os valores padrão são usados quando o Amazon Lex reconhece uma nova intenção, mas não recebe um valor de slot. Você especifica o nome do contexto e o nome do slot no formulário `#context-name.parameter-name` ao definir o slot. Para obter mais informações, consulte [Usar valores de slot padrão](context-mgmt-default.md).
# Usar valores de slot padrão
Ao usar um valor padrão, você especifica uma fonte para um valor de slot a ser preenchido para novas intenções quando nenhum slot é fornecido pela entrada do usuário. Essa fonte pode ser uma caixa de diálogo anterior, atributos de solicitação ou sessão ou um valor fixo que você define no momento da criação.
Você pode usar o seguinte como fonte para seus valores padrão.
+ Caixa de diálogo anterior (contextos): \$1context-name.parameter-name
+ Atributos da sessão: [attribute-name]
+ Atributos de solicitação:
+ Valor fixo: qualquer valor que não corresponda ao anterior
Ao usar a operação [PutIntent](API_PutIntent.md) para adicionar slots a uma intenção, você pode adicionar uma lista de valores padrão. Os valores padrão são usados na ordem em que estão listados. Por exemplo, suponha que você tenha uma intenção com um slot com a seguinte definição:
```
"slots": [
{
"name": "reservation-start-date",
"defaultValueSpec": {
"defaultValueList": [
{
"defaultValue": "#book-car-fulfilled.startDate"
},
{
"defaultValue": "[reservationStartDate]"
}
]
},
Other slot configuration settings
}
]
```
Quando a intenção é reconhecida, o slot chamado "reservation-start-date" tem seu valor definido como um dos seguintes.
1. Se o contexto book-car-fulfilled "" estiver ativo, o valor do parâmetro “StartDate” será usado como o valor padrão.
1. Se o contexto book-car-fulfilled "" não estiver ativo ou se o parâmetro “StartDate” não estiver definido, o valor do atributo de sessão reservationStartDate "" será usado como o valor padrão.
1. Se nenhum dos dois primeiros valores padrão for usado, o slot não terá um valor padrão e o Amazon Lex obterá um valor como de costume.
Se um valor padrão for usado para o slot, o slot não será obtido, mesmo que seja necessário.
# Definição dos atributos da sessão
*Atributos da sessão* contêm informações específicas do aplicativo que são passadas entre o bot e o aplicativo cliente durante uma sessão. O Amazon Lex passa atributos da sessão para todas as funções função do Lambda configuradas para um bot. Se uma função do Lambda adicionar ou atualizar atributos da sessão, o Amazon Lex passará as novas informações de volta para o aplicativo cliente. Por exemplo:
+ No exemplo [Exercício 1: Criar um bot do Amazon Lex usando um esquema (Console).](gs-bp.md), o bot usa o atributo de sessão `price` para manter o preço das flores. A função do Lambda define esse atributo com base nos tipos de flores encomendados. Para obter mais informações, consulte [Etapa 5 (opcional): Revise os detalhes do fluxo de informações (console)](gs-bp-details-after-lambda.md).
+ No exemplo [Reservar uma viagem](ex-book-trip.md), o bot usa o atributo de sessão `currentReservation` para manter uma cópia dos dados do tipo de slot durante a conversa para fazer uma reserva em hotel ou alugar um carro. Para obter mais informações, consulte [Detalhes do fluxo de informações](book-trip-detail-flow.md).
Use atributos de sessão em suas funções do Lambda para inicializar um bot e personalizar prompts e cartões de resposta. Por exemplo:
+ Inicialização: em um bot de pedido de pizza, o aplicativo cliente passa o local do usuário como um atributo de sessão na primeira chamada à operação [PostContent](API_runtime_PostContent.md) ou [PostText](API_runtime_PostText.md). Por exemplo, .`"Location": "111 Maple Street"` A função do Lambda usa essas informações para encontrar a pizzaria mais próxima para fazer o pedido.
+ Personalizar prompts: configure prompts e cartões de resposta para fazer referência a atributos de sessão. Por exemplo, “Ei [FirstName], quais coberturas você gostaria?” Se você passar o nome do usuário como um atributo de sessão (`{"FirstName": "Jo"}`), o Amazon Lex substituirá o nome pelo espaço reservado. Em seguida, ele envia um prompt personalizado para o usuário: "Oi, Jo, quais coberturas você quer?"
Os atributos da sessão permanecem durante a vigência da sessão. Eles são criptografados e armazenados pelo Amazon Lex até que o final da sessão. O cliente pode criar atributos de sessão em uma solicitação usando a operação [PostContent](API_runtime_PostContent.md) ou [PostText](API_runtime_PostText.md) com o campo `sessionAttributes` definido como um valor. Uma função do Lambda pode criar um atributo de sessão em uma resposta. Depois que o cliente ou uma função do Lambda cria um atributo de sessão, o valor do atributo armazenado é usado sempre que o aplicativo cliente não incluir o campo `sessionAttribute` em uma solicitação para o Amazon Lex.
Por exemplo, suponha que você tenha dois atributos de sessão `{"x": "1", "y": "2"}`. Se o cliente chamar a operação `PostContent` ou `PostText` sem especificar o campo `sessionAttributes`, o Amazon Lex chamará a função do Lambda com os atributos de sessão armazenados (`{"x": 1, "y": 2}`). Se a função do Lambda não retornar atributos de sessão, o Amazon Lex retornará os atributos de sessão armazenados ao aplicativo cliente.
Se o aplicativo cliente ou uma função do Lambda passar atributos de sessão, o Amazon Lex atualizará as informações dos atributos de sessão armazenados. Passar um valor existente, como ` {"x": 2}`, atualiza o valor armazenado. Se você inserir um novo conjunto de atributos de sessão, como `{"z": 3}`, os valores existentes serão removidos e apenas o novo valor será mantido. Quando um mapa vazio, `{}`, é passado, os valores armazenados são apagados.
Para enviar atributos de sessão para o Amazon Lex, você cria um string-to-string mapa dos atributos. As considerações a seguir mostram como mapear atributos de sessão:
```
{
"attributeName": "attributeValue",
"attributeName": "attributeValue"
}
```
Para a operação `PostText`, insira o mapa no corpo da solicitação usando o campo `sessionAttributes`, como a seguir:
```
"sessionAttributes": {
"attributeName": "attributeValue",
"attributeName": "attributeValue"
}
```
Para a operação `PostContent`, codifique o mapa em base64 e o envie como o cabeçalho `x-amz-lex-session-attributes`.
Se você estiver enviando dados binários ou estruturados em um atributo de sessão, deve primeiro transformar os dados em uma string simples. Para obter mais informações, consulte [Configuração de atributos complexos](context-mgmt-complex-attributes.md).
# Definição de atributos de solicitação
*Atributos de solicitação contêm informações específicas da solicitação e aplicam-se apenas à solicitação atual.* Um aplicativo cliente envia essas informações ao Amazon Lex. Use atributos de solicitação para passar informações que não precisam ser mantidas durante toda a sessão. Você pode criar seus próprios atributos de solicitação ou usar atributos predefinidos. Para enviar atributos de solicitação, use o cabeçalho `x-amz-lex-request-attributes` em uma [PostContent](API_runtime_PostContent.md) ou no campo `requestAttributes` em uma solicitação [PostText](API_runtime_PostText.md). Como os atributos de solicitação não são persistentes entre as solicitações como os atributos de sessão, eles não são retornados em respostas `PostContent` ou `PostText`.
**nota**
Para enviar informações que são mantidas nas solicitações, use atributos de sessão.
O namespace `x-amz-lex:` é reservado para os atributos de solicitação predefinidos. Não crie atributos de solicitação com o prefixo `x-amz-lex:`.
## Definição de atributos de solicitação predefinidos
O Amazon Lex fornece atributos de solicitação predefinidos para gerenciar a maneira como ele processa as informações enviadas a seu bot. Os atributos não são mantidos durante toda a sessão. Por isso, você deve enviar os atributos predefinidos em cada solicitação. Todos os atributos predefinidos estão no namespace `x-amz-lex:`.
Além dos atributos predefinidos a seguir, o Amazon Lex fornece atributos predefinidos para plataformas de sistemas de mensagens. Para obter uma lista desses atributos, consulte [Implantação de um bot do Amazon Lex em uma plataforma de sistema de mensagens](example1.md).
### Como configurar o tipo de resposta
Se tiver dois aplicativos clientes com diferentes recursos, talvez seja necessário restringir o formato das mensagens em uma resposta. Por exemplo, talvez você queira restringir as mensagens enviadas a um cliente web a textos sem formatação, mas permitir que um cliente móvel use o texto sem formatação e Speech Synthesis Markup Language (SSML). Para definir o formato das mensagens retornadas pelas operações [PostContent](API_runtime_PostContent.md) e [PostText](API_runtime_PostText.md), use o atributo de solicitação `x-amz-lex:accept-content-types"`.
Você pode definir o atributo para qualquer combinação dos seguintes tipos de mensagem:
+ `PlainText`: a mensagem contém texto sem formatação UTF-8.
+ `SSML`: a mensagem contém texto formatado para saída de voz.
+ `CustomPayload`: a mensagem contém um formato personalizado que você criou para seu cliente. Você pode definir a carga útil para atender às necessidades de seu aplicativo.
O Amazon Lex retorna apenas mensagens com o tipo especificado no campo `Message` da resposta. Você pode definir mais de um valor. Para isso, separe os valores com uma vírgula. Se estiver usando grupos de mensagens, cada um deverá conter pelo menos uma mensagem do tipo especificado. Do contrário, você receberá um erro `NoUsableMessageException`. Para obter mais informações, consulte [Grupos de mensagens](howitworks-manage-prompts.md#message-groups).
**nota**
O atributo de solicitação `x-amz-lex:accept-content-types` não tem efeito sobre o conteúdo do corpo HTML. O conteúdo da resposta de uma operação `PostText` sempre é texto sem formatação UTF-8. O corpo da resposta de uma operação `PostContent` contém dados no formato definido no cabeçalho `Accept` da solicitação.
### Definição do fuso horário preferido
Para definir o fuso horário usado para resolver datas de forma que seja relativo ao fuso horário do usuário, use o atributo de solicitação `x-amz-lex:time-zone`. Se um fuso horário não está especificado no atributo `x-amz-lex:time-zone`, o padrão depende da região que você está usando para o seu bot.
| Região | Fuso horário padrão |
| --- | --- |
| Leste dos EUA (N. da Virgínia) | America/New\$1York |
| Oeste dos EUA (Oregon) | America/Los\$1Angeles |
| Ásia-Pacífico (Singapura) | Asia/Singapore |
| Ásia-Pacífico (Sydney) | Australia/Sydney |
| Ásia-Pacífico (Tóquio) | Asia/Tokyo |
| Europa (Frankfurt) | Europe/Berlin |
| Europa (Irlanda) | Europe/Dublin |
| Europa (Londres) | Europe/London |
Por exemplo, se o usuário responde `tomorrow` em resposta ao prompt "Quando você gostaria que seu pacote fosse entregue?" a *data* em que o pacote será entregue depende do fuso horário do usuário. Por exemplo, quando ele é 01:00 de 16 de setembro em Nova York, são 22:00 de 15 de setembro em Los Angeles. Se uma pessoa no Leste dos EUA (Norte da Virgínia) encomendar um pacote a ser entregue "amanhã" usando o fuso horário padrão, o pacote será entregue no dia 17, e não no dia 16. No entanto, se você definir o atributo de solicitação `x-amz-lex:time-zone` para `America/Los_Angeles`, o pacote será entregue no dia 16.
Você pode definir o atributo para qualquer um nomes de fuso horário IANA (Internet Assigned Number Authority). Para ver a lista de nomes de fuso horário, consulte a [Lista de fusos horários do banco de dados tz](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) na Wikipédia.
## Definição de atributos de solicitação definidos pelo usuário
O *atributo de solicitação definido pelo usuário* são os dados que você envia para seu bot em cada solicitação. Você enviar as informações no cabeçalho `amz-lex-request-attributes` de uma solicitação `PostContent` ou no campo `requestAttributes` de uma solicitação `PostText`.
Para enviar atributos de solicitação para o Amazon Lex, você cria um string-to-string mapa dos atributos. As considerações a seguir mostram como mapear atributos de solicitação:
```
{
"attributeName": "attributeValue",
"attributeName": "attributeValue"
}
```
Para a operação `PostText`, insira o mapa no corpo da solicitação usando o campo `requestAttributes`, como a seguir:
```
"requestAttributes": {
"attributeName": "attributeValue",
"attributeName": "attributeValue"
}
```
Para a operação `PostContent`, codifique o mapa em base64 e o envie como o cabeçalho `x-amz-lex-request-attributes`.
Se você está enviando dados binários ou estruturados em um atributo de solicitação, você deve primeiro transformar os dados em uma string simples. Para obter mais informações, consulte [Configuração de atributos complexos](context-mgmt-complex-attributes.md).
# Definição do tempo limite da sessão
O Amazon Lex retém informações de contexto (dados de slot e atributos de sessão) até o fim de uma sessão de conversa. Para controlar o tempo de duração de uma sessão em um bot, defina o tempo limite da sessão. Por padrão, a duração da sessão é de 5 minutos, mas você pode especificar qualquer duração entre 0 e 1.440 minutos (24 horas).
Por exemplo, suponha que você crie um bot `ShoeOrdering` que seja compatível com intenções como `OrderShoes` e `GetOrderStatus`. Quando o Amazon Lex detecta que a intenção do usuário é encomendar sapatos, ele pede os dados do slot. Por exemplo, ele pergunta o tamanho, a cor, a marca, etc. Se o usuário fornecer alguns dados do slot, mas não finalizar a compra de sapato, o Amazon Lex memorizará todos os dados do slot e os atributos da sessão inteira. Se o usuário retornar para a sessão antes que ela expire, ele ou ela pode fornecer os dados de slot restantes e concluir a compra.
No console do Amazon Lex, você define o tempo limite de sessão ao criar um bot. Com a interface de linha de comando da AWS (AWS CLI) ou a API, você define o tempo limite ao criar ou atualizar um bot com a [PutBot](API_PutBot.md) operação definindo o campo [TTLInIdleSession](https://docs.aws.amazon.com/lex/latest/dg/API_PutBot.html#lex-PutBot-request-idleSessionTTLInSeconds) Seconds.
# Compartilhamento de informações entre intenções
O Amazon Lex é compatível com o compartilhamento de informações entre intenções. Para compartilhar entre intenções, use atributos de sessão.
Por exemplo, um usuário do bot `ShoeOrdering` começa a pedir sapatos. O bot inicia uma conversa com o usuário, coletando dados de slot como tamanho, cor e marca do sapato. Quando o usuário faz um pedido, a função do Lambda; que atende ao pedido define o atributo de sessão `orderNumber`, que contém o número do pedido. Para obter o status do pedido, o usuário usa a intenção `GetOrderStatus`. O bot pode solicitar dados de slot ao usuário, como número do pedido e data do pedido. Quando o bot tem as informações necessárias, ele retorna o status do pedido.
Se você acha que seus usuários podem mudar de intenção durante uma sessão, você pode projetar seu bot para retornar o status do pedido mais recente. Em vez de pedir ao usuário as informações do pedido novamente, você usa o atributo de sessão `orderNumber` para compartilhar informações entre intenções e cumprir a intenção `GetOrderStatus`. O bot faz isso ao retornar o status do último pedido feito pelo usuário.
Para obter um exemplo de compartilhamento de informações entre intenções, consulte [Reservar uma viagem](ex-book-trip.md).
# Configuração de atributos complexos
Os atributos de sessão e solicitação são string-to-string mapas de atributos e valores. Em muitos casos, você pode usar o mapa de string para transferir valores de atributo entre o aplicativo cliente e o bot. Em alguns casos, no entanto, pode ser necessário transferir uma estrutura complexa ou dados binários que não podem ser facilmente convertidos em um mapa de string. Por exemplo, o seguinte objeto JSON representa um arranjo com as três cidades mais populosas dos Estados Unidos:
```
{
"cities": [
{
"city": {
"name": "New York",
"state": "New York",
"pop": "8537673"
}
},
{
"city": {
"name": "Los Angeles",
"state": "California",
"pop": "3976322"
}
},
{
"city": {
"name": "Chicago",
"state": "Illinois",
"pop": "2704958"
}
}
]
}
```
Essa matriz de dados não se traduz bem em um string-to-string mapa. Nesse caso, você pode transformar um objeto em uma string simples para que você possa enviá-lo ao seu bot com as operações [PostContent](API_runtime_PostContent.md) e [PostText](API_runtime_PostText.md).
Por exemplo, se você estiver usando JavaScript, você pode usar a `JSON.stringify` operação para converter um objeto em JSON e a `JSON.parse` operação para converter texto JSON em um JavaScript objeto:
```
// To convert an object to a string.
var jsonString = JSON.stringify(object, null, 2);
// To convert a string to an object.
var obj = JSON.parse(JSON string);
```
Para enviar atributos de sessão com a `PostContent` operação, você deve codificar os atributos em base64 antes de adicioná-los ao cabeçalho da solicitação, conforme mostrado no código a seguir: JavaScript
```
var encodedAttributes = new Buffer(attributeString).toString("base64");
```
Você pode enviar dados binários para as operações `PostContent` e `PostText` convertendo os dados para uma string codificada em base64 e, em seguida, enviando a string como o valor nos atributos de sessão:
```
"sessionAttributes" : {
"binaryData": "base64 encoded data"
}
```
# Usar pontuações de confiança
Quando um usuário faz uma declaração, o Amazon Lex usa a compreensão de linguagem natural (NLU) para entender a solicitação do usuário e retornar a intenção correta. Por padrão, o Amazon Lex retorna a intenção mais provável definida pelo seu bot.
Em alguns casos, pode ser difícil para o Amazon Lex determinar a intenção mais provável. Por exemplo, o usuário pode fazer uma declaração ambígua ou pode haver duas intenções semelhantes. Para ajudar a determinar a intenção correta, você pode combinar seu conhecimento de domínio com as *pontuações de confiança* de uma lista de intenções alternativas. Uma pontuação de confiança é uma classificação fornecida pelo Amazon Lex que mostra o grau de confiança de que uma intenção é a intenção correta.
Para determinar a diferença entre duas intenções alternativas, você pode comparar suas pontuações de confiança. Por exemplo, se uma intenção tem uma pontuação de confiança de 0,95 e outra tem uma pontuação de 0,65, a primeira intenção provavelmente está correta. No entanto, se uma intenção tiver uma pontuação de 0,75 e outra tiver uma pontuação de 0,72, haverá ambiguidade entre as duas intenções que você poderá discriminar usando o conhecimento do domínio em seu aplicativo.
Você também pode usar pontuações de confiança para criar aplicativos de teste que determinam se as mudanças nas declarações de uma intenção fazem diferença no comportamento do bot. Por exemplo, você pode obter as pontuações de confiança das intenções de um bot usando um conjunto de declarações e, em seguida, atualizar as intenções com novas declarações. Em seguida, você pode verificar as pontuações de confiança para ver se houve uma melhora.
As pontuações de confiança que o Amazon Lex retorna são valores comparativos. Você não deve confiar neles como uma pontuação absoluta. Os valores podem mudar com base em melhorias no Amazon Lex.
Quando você usa pontuações de confiança, o Amazon Lex retorna a intenção mais provável e até 4 intenções alternativas com suas pontuações associadas em cada resposta. Se todas as pontuações de confiança forem menores que um limite, o Amazon Lex incluirá o `AMAZON.FallbackIntent`, o `AMAZON.KendraSearchIntent`, o ou ambos, se você os tiver configurado. É possível usar o limite padrão ou definir seu próprio limite.
O código JSON a seguir mostra o `alternativeIntents` campo na resposta da [PostText](API_runtime_PostText.md) operação.
```
"alternativeIntents": [
{
"intentName": "string",
"nluIntentConfidence": {
"score": number
},
"slots": {
"string" : "string"
}
}
],
```
Defina o limite ao criar ou atualizar um bot. Você pode usar a API ou o console do Amazon Lex. Para as regiões listadas abaixo, você precisa se inscrever para permitir melhorias de precisão e pontuações de confiança. No console, escolha pontuações de confiança na seção **Opções avançadas**. Usando a API, defina o parâmetro `enableModelImprovements` ao chamar a operação [PutBot](API_PutBot.md).
+ Leste dos EUA (Norte da Virgínia) (us-east-1)
+ Oeste dos EUA (Oregon) (us-west-2)
+ Ásia-Pacífico (Sydney) (ap-southeast-2)
+ Europa (Irlanda) (eu-west-1)
Em todas as outras regiões, melhorias na precisão e suporte à pontuação de confiança estão disponíveis por padrão.
Para alterar o limite de confiança, defina-o no console ou usando a operação [PutBot](API_PutBot.md). O limite deve ser um número entre 1,00 e 0,00.
Para usar o console, defina o limite de confiança ao criar ou atualizar seu bot.
**Para definir o limite de confiança ao criar um bot (Console)**
+ Em **Criar seu bot**, insira um valor no campo **Limite da pontuação de confiança**.
**Para atualizar o limite de confiança (Console)**
1. Na lista de bots, escolha o bot a ser atualizado.
1. Escolha a guia **Configurações**.
1. Na barra de navegação à esquerda, selecione **Geral**.
1. Atualize o valor no campo **Limite da pontuação de confiança**.
**Para definir ou atualizar o limite de confiança (SDK)**
+ Defina o parâmetro `nluIntentConfidenceThreshold` da operação [PutBot](API_PutBot.md). O código JSON a seguir mostra o parâmetro que está sendo definido.
```
"nluIntentConfidenceThreshold": 0.75,
```
## Gerenciamento de sessões
Para alterar a intenção que o Amazon Lex usa em uma conversa com o usuário, você pode usar a resposta da função Lambda do gancho de código de diálogo ou usar o APIs gerenciamento de sessões em seu aplicativo personalizado.
### Usar um URL da função do Lambda
Quando você usa uma função do Lambda, o Amazon Lex a chama com uma estrutura JSON que contém a entrada para a função. A estrutura JSON contém um campo chamado `currentIntent` que contém a intenção que o Amazon Lex identificou como a intenção mais provável para a declaração do usuário. A estrutura JSON também inclui um campo `alternativeIntents` que contém até quatro intenções adicionais que podem satisfazer a intenção do usuário. Cada intenção inclui um campo chamado `nluIntentConfidenceScore` que contém a pontuação de confiança que o Amazon Lex atribuiu à intenção.
Para usar uma intenção alternativa, você a especifica na ação de diálogo `ConfirmIntent` ou `ElicitSlot` na função do Lambda.
Para obter mais informações, consulte [Uso de funções do Lambda](using-lambda.md).
### Usar a API de gerenciamento de sessões
Para usar uma intenção diferente da intenção atual, utilize a operação [PutSession](API_runtime_PutSession.md). Por exemplo, se você decidir que a primeira alternativa é preferível à intenção escolhida pelo Amazon Lex, use a operação `PutSession` para alterar as intenções de modo que a próxima intenção com a qual o usuário vai interagir seja aquela que você selecionou.
Para obter mais informações, consulte [Gerenciamento de sessões com a API do Amazon Lex](how-session-api.md).
# Logs de conversa
Você habilita *logs de conversa* para armazenar interações com o bot. Você pode usar esses logs para examinar o desempenho do bot e solucionar problemas com conversas. Você pode criar logs de texto para a operação [PostText](API_runtime_PostText.md). É possível criar logs de texto e áudio para a operação [PostContent](API_runtime_PostContent.md). Ao habilitar os logs de conversa, você obtém uma visão detalhada das conversas que os usuários têm com seu bot.
Por exemplo, uma sessão com seu bot tem um ID de sessão. É possível usar esse ID para obter a transcrição da conversa, incluindo declarações do usuário e as respostas correspondentes do bot. Você também obtém metadados, como nome de intenção e valores de slot para uma declaração.
**nota**
Não é possível usar logs de conversa com um bot sujeito à Lei de Proteção de Privacidade Online das Crianças (COPPA).
Os logs de conversa são configurados para um alias. Cada alias pode ter configurações diferentes para seus logs de texto e áudio. É possível habilitar logs de texto, logs de áudio ou os dois para cada alias. Os registros de texto armazenam entradas de texto, transcrições de entrada de áudio e metadados associados nos registros. CloudWatch Os logs de áudio armazenam entrada de áudio no Amazon S3. Você pode ativar a criptografia de registros de texto e áudio usando o gerenciamento de AWS KMS clientes CMKs.
Para configurar o registro em log, use o console ou a operação [PutBotAlias](API_PutBotAlias.md). Não é possível criar logs de conversas para o alias `$LATEST` do seu bot ou para o bot de teste disponível no console do Amazon Lex. Depois de ativar os registros de conversação para um alias, [PostContent](API_runtime_PostContent.md) ou a [PostText](API_runtime_PostText.md) operação desse alias, registra as declarações de texto ou áudio no grupo de registros de CloudWatch registros configurado ou no bucket do S3.
**Topics**
+ [Políticas do IAM para logs de conversa](conversation-logs-policies.md)
+ [Configurar logs de conversa](conversation-logs-configure.md)
+ [Criptografar logs de conversa](conversation-logs-encrypting.md)
+ [Visualização de registros de texto no Amazon CloudWatch Logs](conversation-logs-cw.md)
+ [Acessar logs de áudio no Amazon S3](conversation-logs-s3.md)
+ [Monitorando o status do registro de conversas com CloudWatch métricas](conversation-logs-monitoring.md)
# Políticas do IAM para logs de conversa
Dependendo do tipo de registro selecionado, o Amazon Lex exige permissão para usar os buckets Amazon CloudWatch Logs e Amazon Simple Storage Service (S3) para armazenar seus registros. Você deve criar AWS Identity and Access Management funções e permissões para permitir que o Amazon Lex acesse esses recursos.
## Criar um perfil e políticas do IAM para logs de conversa
Para habilitar registros de conversas, você deve conceder permissão de gravação para CloudWatch Logs e Amazon S3. Se você habilitar a criptografia de objetos para seus objetos do S3, precisará conceder permissão de acesso às AWS KMS chaves usadas para criptografar os objetos.
Você pode usar o IAM Console de gerenciamento da AWS, a API do IAM ou o AWS Command Line Interface para criar a função e as políticas. Essas instruções usam o AWS CLI para criar a função e as políticas. Para obter informações sobre como criar uma política com o console, consulte [Criar políticas na guia JSON](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) no *Guia do usuário do AWS Identity and Access Management*.
**nota**
O código a seguir é formatado para Linux e MacOS. Para Windows, substitua o caractere de continuação de linha do Linux (\$1) pelo circunflexo (^).
**Para criar um perfil do IAM para logs de conversa**
1. Crie um documento no diretório atual chamado **LexConversationLogsAssumeRolePolicyDocument.json**, adicione o código a seguir a ele e salve-o. Esse documento de política adiciona o Amazon Lex como uma entidade confiável ao perfil. Isso permite que o Lex assuma o perfil para entregar logs aos recursos configurados para logs de conversa.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lex.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. No AWS CLI, execute o comando a seguir para criar a função do IAM para registros de conversas.
```
aws iam create-role \
--role-name role-name \
--assume-role-policy-document file://LexConversationLogsAssumeRolePolicyDocument.json
```
Em seguida, crie e anexe uma política à função que permite que o Amazon Lex grave em CloudWatch Logs.
**Para criar uma política do IAM para registrar o texto da conversa no CloudWatch Logs**
1. Crie um documento no diretório atual chamado **LexConversationLogsCloudWatchLogsPolicy.json**, adicione a ele a política do IAM a seguir e salve-o.
1. No AWS CLI, crie a política do IAM que concede permissão de gravação ao grupo de CloudWatch registros de registros.
```
aws iam create-policy \
--policy-name cloudwatch-policy-name \
--policy-document file://LexConversationLogsCloudWatchLogsPolicy.json
```
1. Associe a política ao perfil do IAM criada para logs de conversa.
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::account-id:policy/cloudwatch-policy-name \
--role-name role-name
```
Se você estiver criando logs de áudio em um bucket do S3, crie uma política que permita ao Amazon Lex gravar no bucket.
**Como criar uma política do IAM para criar logs de áudio em um bucket do S3**
1. Crie um documento no diretório atual chamado **LexConversationLogsS3Policy.json**, adicione a ele a política a seguir e salve-o.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:PutObject"
],
"Resource": "arn:aws:s3:::bucket-name/*"
}
]
}
```
------
1. No AWS CLI, crie a política do IAM que concede permissão de gravação ao seu bucket do S3.
```
aws iam create-policy \
--policy-name s3-policy-name \
--policy-document file://LexConversationLogsS3Policy.json
```
1. Associe a política ao perfil criado para logs de conversa.
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::account-id:policy/s3-policy-name \
--role-name role-name
```
## Conceder permissão para passar um perfil do IAM
Quando você usa o console AWS Command Line Interface, o ou um AWS SDK para especificar uma função do IAM a ser usada para registros de conversas, o usuário que especifica a função IAM dos registros de conversas deve ter permissão para passar a função para o Amazon Lex. Para permitir que o usuário passe o perfil ao Amazon Lex, é necessário conceder a permissão de `PassRole` ao usuário, ao perfil ou ao grupo.
A política a seguir define a permissão que será concedida ao usuário, ao perfil ou ao grupo. É possível usar as chaves de condição `iam:AssociatedResourceArn` e `iam:PassedToService` para limitar o escopo da permissão. Para obter mais informações, consulte [Conceder permissões a um usuário para passar uma função para um AWS serviço](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html) e [IAM e chaves de contexto de AWS STS condição](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html) no *Guia do AWS Identity and Access Management usuário*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/role-name",
"Condition": {
"StringEquals": {
"iam:PassedToService": "lex.amazonaws.com"
},
"StringLike": {
"iam:AssociatedResourceARN": "arn:aws:lex:region:123456789012:bot:bot-name:bot-alias"
}
}
}
]
}
```
------
# Configurar logs de conversa
Habilite e desabilite os logs de conversa usando o console ou o campo `conversationLogs` da operação `PutBotAlias`. É possível ativar ou desativar logs de áudio, logs de texto ou ambos. O registro em log começa em novas sessões do bot. As alterações nas configurações de log não são refletidas nas sessões ativas.
Para armazenar registros de texto, use um grupo de CloudWatch registros do Amazon Logs em sua AWS conta. É possível usar qualquer grupo de logs válido. O grupo de logs deve estar na mesma região que o bot do Amazon Lex. Para obter mais informações sobre a criação de um grupo de CloudWatch registros de registros, consulte Como [trabalhar com grupos de registros e fluxos](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html) de registros no *Guia do usuário do Amazon CloudWatch Logs*.
Para armazenar registros de áudio, use um bucket do Amazon S3 em sua AWS conta. É possível usar qualquer bucket válido do S3. O bucket deve estar na mesma região que o bot do Amazon Lex. Para obter mais informações sobre como criar um bucket do Amazon S3, consulte [Criar um bucket](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html) no *Guia de conceitos básicos do Amazon Simple Storage Service*.
É necessário fornecer um perfil do IAM com políticas que permitam ao Amazon Lex gravar no grupo de logs ou no bucket configurado. Para obter mais informações, consulte [Criar um perfil e políticas do IAM para logs de conversa](conversation-logs-policies.md#conversation-logs-role-and-policy).
Se você criar uma função vinculada ao serviço usando o AWS Command Line Interface, deverá adicionar um sufixo personalizado à função usando a `custom-suffix` opção a seguir:
```
aws iam create-service-linked-role \
--aws-service-name lex.amazon.aws.com \
--custom-suffix suffix
```
O perfil do IAM utilizado para habilitar logs de conversa deve ter a permissão `iam:PassRole`. A política a seguir deve ser anexada ao perfil.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/role"
}
]
}
```
------
## Ativar logs de conversa
**Para ativar os logs usando o console**
1. Abra o console do Amazon Lex [https://console.aws.amazon.com/lex](https://console.aws.amazon.com/lex).
1. Na lista, escolha um bot.
1. Selecione a guia **Configurações** e, no menu esquerdo, selecione **Logs de conversa**.
1. Na lista de aliases, escolha o ícone de configurações para o alias para o qual você deseja configurar logs de conversa.
1. Selecione se deseja registrar texto, áudio ou ambos.
1. Para registro de texto, insira o nome do grupo de CloudWatch registros do Amazon Logs.
1. Para registro de áudio em log, insira as informações do bucket do S3.
1. Opcional. Para criptografar registros de áudio, escolha a AWS KMS chave a ser usada para criptografia.
1. Escolha uma perfil do IAM com as permissões necessárias.
1. Escolha **Salvar** para iniciar o registro em log de conversas.
**Como ativar logs de texto usando a API**
1. Chame a operação [PutBotAlias](API_PutBotAlias.md) com uma entrada no membro `logSettings` do campo `conversationLogs`
+ Defina o membro `destination` como `CLOUDWATCH_LOGS`
+ Defina o membro `logType` como `TEXT`
+ Defina o `resourceArn` membro como o Amazon Resource Name (ARN) do grupo de CloudWatch registros de registros que é o destino dos registros
1. Defina o membro `iamRoleArn` do campo `conversationLogs` como o nome do recurso da Amazon (ARN) de um perfil do IAM que tenha as permissões necessárias para habilitar logs de conversa nos recursos especificados.
**Como ativar logs de áudio usando a API**
1. Chame a operação [PutBotAlias](API_PutBotAlias.md) com uma entrada no membro `logSettings` do campo `conversationLogs`
+ Defina o membro `destination` como `S3`
+ Defina o membro `logType` como `AUDIO`
+ Defina o membro `resourceArn` como o ARN do bucket do Amazon S3 onde os logs de áudio são armazenados
+ Opcional. Para criptografar registros de áudio com uma AWS KMS chave específica, defina o `kmsKeyArn` membro do ARN da chave usada para criptografia.
1. Defina o membro `iamRoleArn` do campo `conversationLogs` como o nome do recurso da Amazon (ARN) de um perfil do IAM que tenha as permissões necessárias para habilitar logs de conversa nos recursos especificados.
## Desativar logs de conversa
**Como desativar os logs usando o console**
1. Abra o console do Amazon Lex [https://console.aws.amazon.com/lex](https://console.aws.amazon.com/lex).
1. Na lista, escolha um bot.
1. Selecione a guia **Configurações** e, no menu esquerdo, selecione **Logs de conversa**.
1. Na lista de aliases, escolha o ícone de configurações para o alias para o qual você deseja configurar logs de conversa.
1. Desmarque a verificação de texto, áudio ou ambos para desativar o registro em log.
1. Escolha **Salvar** para interromper o registro em log de conversas.
**Como desativar os logs usando a API**
+ Chame a operação `PutBotAlias` sem o campo `conversationLogs`.
**Como desativar os logs de texto usando a API**
+
+ Se você estiver registrando áudio
+ Chame a operação [PutBotAlias](API_PutBotAlias.md) com uma entrada `logSettings` somente para `AUDIO`.
+ A chamada para a operação `PutBotAlias` não deve ter uma entrada `logSettings` para `TEXT`.
+ Se você não estiver registrando áudio em log
+ Chame a operação [PutBotAlias](API_PutBotAlias.md) sem o campo `conversationLogs`.
**Como desativar os logs de áudio usando a API**
+
+ Se você estiver registrando texto em log
+ Chame a operação [PutBotAlias](API_PutBotAlias.md) com uma entrada `logSettings` somente para `TEXT`.
+ A chamada para a operação `PutBotAlias` não deve ter uma entrada `logSettings` para `AUDIO`.
+ Se você não estiver registrando texto em log
+ Chame a operação [PutBotAlias](API_PutBotAlias.md) sem o campo `conversationLogs`.
# Criptografar logs de conversa
É possível usar criptografia para ajudar a proteger o conteúdo dos logs de conversa. Para registros de texto e áudio, você pode usar o gerenciamento AWS KMS do cliente CMKs para criptografar dados no seu grupo de registros de CloudWatch registros e no bucket do S3.
**nota**
O Amazon Lex oferece suporte somente para sistemas simétricos CMKs. Não use uma CMK assimétrica para criptografar dados.
Você ativa a criptografia usando uma AWS KMS chave no grupo de CloudWatch registros de registros que o Amazon Lex usa para registros de texto. Você não pode fornecer uma AWS KMS chave nas configurações de registro para ativar a AWS KMS criptografia do seu grupo de registros. Para obter mais informações, consulte [Criptografar dados de log em CloudWatch registros usando AWS KMS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/encrypt-log-data-kms.html) o *Guia do usuário do Amazon CloudWatch Logs*.
Para registros de áudio, você usa a criptografia padrão em seu bucket do S3 ou especifica uma AWS KMS chave para criptografar seus objetos de áudio. Mesmo que seu bucket do S3 use criptografia padrão, você ainda pode especificar uma AWS KMS chave diferente para criptografar seus objetos de áudio. Para obter mais informações, consulte [ Criptografia padrão do Amazon S3 para buckets do S3 ](https://docs.aws.amazon.com/AmazonS3/latest/dev/bucket-encryption.html) no *Guia do desenvolvedor do Amazon Simple Storage Service*.
O Amazon Lex exige AWS KMS permissões se você optar por criptografar seus registros de áudio. É necessário associar políticas adicionais ao perfil do IAM usado para logs de conversa. Se você usa criptografia padrão em seu bucket do S3, sua política deve conceder acesso à AWS KMS chave configurada para esse bucket. Se você especificar uma AWS KMS chave nas configurações do registro de áudio, deverá conceder acesso a essa chave.
Se você não criou uma função para logs de conversa, consulte [Políticas do IAM para logs de conversa](conversation-logs-policies.md).
**Para criar uma política do IAM para usar uma AWS KMS chave para criptografar registros de áudio**
1. Crie um documento no diretório atual chamado **LexConversationLogsKMSPolicy.json**, adicione a ele a política a seguir e salve-o.
1. No AWS CLI, crie a política do IAM que concede permissão para usar a AWS KMS chave para criptografar registros de áudio.
```
aws iam create-policy \
--policy-name kms-policy-name \
--policy-document file://LexConversationLogsKMSPolicy.json
```
1. Associe a política ao perfil criado para logs de conversa.
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::account-id:policy/kms-policy-name \
--role-name role-name
```
# Visualização de registros de texto no Amazon CloudWatch Logs
O Amazon Lex armazena registros de texto para suas conversas no Amazon CloudWatch Logs. Para ver os registros, você pode usar o console de CloudWatch registros ou a API. Para obter mais informações, consulte [Pesquisar dados de log usando padrões de filtro](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/SearchDataFilterPattern.html) e [sintaxe de consulta do CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html) no *Guia do usuário do Amazon CloudWatch Logs*.
**Para visualizar os logs usando o console do Amazon Lex**
1. Abra o console do Amazon Lex [https://console.aws.amazon.com/lex](https://console.aws.amazon.com/lex).
1. Na lista, escolha um bot.
1. Escolha a guia **Configurações** e, no menu esquerdo, selecione **Logs de conversa**.
1. Escolha o link em **Registros de texto** para ver os registros do alias no CloudWatch console.
Você também pode usar o CloudWatch console ou a API para visualizar suas entradas de registro. Para localizar as entradas de log, navegue até o grupo de logs configurado para o alias. Localize o prefixo de fluxo de log para seus logs no console do Amazon Lex ou usando a operação [GetBotAlias](API_GetBotAlias.md).
As entradas de log para uma declaração de usuário estão em vários fluxos de log. Uma declaração na conversa tem uma entrada em um dos fluxos de log com o prefixo especificado. Uma entrada no fluxo de log contém as seguintes informações.
```
{
"messageVersion": "1.0",
"botName": "bot name",
"botAlias": "bot alias",
"botVersion": "bot version",
"inputTranscript": "text used to process the request",
"botResponse": "response from the bot",
"intent": "matched intent",
"nluIntentConfidence": "number",
"slots": {
"slot name": "slot value",
"slot name": null,
"slot name": "slot value"
...
},
"alternativeIntents": [
{
"name": "intent name",
"nluIntentConfidence": "number",
"slots": {
"slot name": slot value,
"slot name": null,
"slot name": slot value
...
}
},
{
"name": "intent name",
"nluIntentConfidence": number,
"slots": {}
}
],
"developerOverride": "true" | "false",
"missedUtterance": true | false,
"inputDialogMode": "Text" | "Speech",
"requestId": "request ID",
"s3PathForAudio": "S3 path to audio file",
"userId": "user ID",
"sessionId": "session ID",
"sentimentResponse": {
"sentimentScore": "{Positive: number, Negative: number, Neutral: number, Mixed: number}",
"sentimentLabel": "Positive" | "Negative" | "Neutral" | "Mixed"
},
"slotToElicit": "slot name",
"dialogState": "ElicitIntent" | "ConfirmIntent" | "ElicitSlot" | "Fulfilled" | "ReadyForFulfillment" | "Failed",
"responseCard": {
"genericAttachments": [
...
],
"contentType": "application/vnd.amazonaws.card.generic",
"version": 1
},
"locale": "locale",
"timestamp": "ISO 8601 UTC timestamp",
"kendraResponse": {
"totalNumberOfResults": number,
"resultItems": [
{
"id": "query ID",
"type": "DOCUMENT" | "QUESTION_ANSWER" | "ANSWER",
"additionalAttributes": [
{
...
}
],
"documentId": "document ID",
"documentTitle": {
"text": "title",
"highlights": null
},
"documentExcerpt": {
"text": "text",
"highlights": [
{
"beginOffset": number,
"endOffset": number,
"topAnswer": true | false
}
]
},
"documentURI": "URI",
"documentAttributes": []
}
],
"facetResults": [],
"sdkResponseMetadata": {
"requestId": "request ID"
},
"sdkHttpMetadata": {
"httpHeaders": {
"Content-Length": "number",
"Content-Type": "application/x-amz-json-1.1",
"Date": "date and time",
"x-amzn-RequestId": "request ID"
},
"httpStatusCode": 200
},
"queryId": "query ID"
},
"sessionAttributes": {
"attribute name": "attribute value"
...
},
"requestAttributes": {
"attribute name": "attribute value"
...
}
}
```
O conteúdo da entrada de log depende do resultado de uma transação e da configuração do bot e da solicitação.
+ Os campos `intent`, `slots` e `slotToElicit` não aparecerão em uma entrada se o campo `missedUtterance` for `true`.
+ O campo `s3PathForAudio` não aparecerá se os logs de áudio estiverem desativados ou se o campo `inputDialogMode` for `Text`.
+ O campo `responseCard` só aparecerá quando você tiver definido um cartão de resposta para o bot.
+ O mapa `requestAttributes` só aparecerá se você tiver especificado atributos de solicitação na solicitação.
+ O campo `kendraResponse` só está presente quando o `AMAZON.KendraSearchIntent` faz uma solicitação para pesquisar um índice do Amazon Kendra.
+ O campo `developerOverride` é verdadeiro quando uma intenção alternativa foi especificada na função do Lambda do bot.
+ O mapa `sessionAttributes` só aparecerá se você tiver especificado atributos de sessão na solicitação.
+ O mapa `sentimentResponse` só aparecerá se você configurar o bot para retornar valores de sentimento.
**nota**
O formato de entrada pode mudar sem uma alteração correspondente em `messageVersion`. Seu código não deve gerar um erro se novos campos estiverem presentes.
Você deve ter uma função e uma política definidas para permitir que o Amazon Lex grave em CloudWatch Logs. Para obter mais informações, consulte [Políticas do IAM para logs de conversa](conversation-logs-policies.md).
# Acessar logs de áudio no Amazon S3
O Amazon Lex armazena logs de áudio para suas conversas em um bucket do S3.
**Para acessar logs de áudio usando o console**
1. Abra o console do Amazon Lex [https://console.aws.amazon.com/lex](https://console.aws.amazon.com/lex).
1. Na lista, escolha um bot.
1. Escolha a guia **Configurações** e, no menu esquerdo, selecione **Logs de conversa**.
1. Escolha o link em **Logs de áudio** para acessar os logs do alias no console do Amazon S3.
Também é possível usar o console ou a API do Amazon S3 para acessar logs de áudio. Você pode ver o prefixo de chaves de objeto do S3 dos arquivos de áudio no console do Amazon Lex ou no campo `resourcePrefix` na resposta da operação `GetBotAlias`.
# Monitorando o status do registro de conversas com CloudWatch métricas
Use CloudWatch a Amazon para monitorar as métricas de entrega dos seus registros de conversas. É possível definir alarmes em métricas para que você esteja ciente de problemas com o registro em log se eles ocorrerem.
O Amazon Lex fornece quatro métricas no namespace `AWS/Lex` para logs de conversa:
+ `ConversationLogsAudioDeliverySuccess`
+ `ConversationLogsAudioDeliveryFailure`
+ `ConversationLogsTextDeliverySuccess`
+ `ConversationLogsTextDeliveryFailure`
Para obter mais informações, consulte [CloudWatch Métricas para registros de conversas](monitoring-aws-lex-cloudwatch.md#cloudwatch-metrics-for-logging).
As métricas de sucesso mostram que o Amazon Lex gravou com êxito seus logs de áudio ou texto em seus destinos.
As métricas de falha mostram que o Amazon Lex não conseguiu entregar os logs de áudio ou texto ao destino especificado. Normalmente, isso é um erro de configuração. Quando suas métricas de falha estiverem acima de zero, verifique o seguinte:
+ Certifique-se de que o Amazon Lex seja uma entidade confiável para o perfil do IAM.
+ Para registro de texto, verifique se o grupo CloudWatch Registros existe. Para criar log de áudio, certifique-se de que o bucket do S3 exista.
+ Certifique-se de que a função do IAM que o Amazon Lex usa para acessar o grupo de CloudWatch logs de registros ou o bucket do S3 tenha permissão de gravação para o grupo de logs ou bucket.
+ Certifique-se de que o bucket do S3 exista na mesma região que o bot do Amazon Lex e pertença à sua conta.
+ Se você estiver usando uma AWS KMS chave para criptografia S3, certifique-se de que não haja políticas que impeçam o Amazon Lex de usar sua chave e certifique-se de que a função do IAM fornecida tenha as AWS KMS permissões necessárias. Para obter mais informações, consulte [Políticas do IAM para logs de conversa](conversation-logs-policies.md).
# Gerenciamento de sessões com a API do Amazon Lex
Quando um usuário começa uma conversa com o bot, o Amazon Lex cria uma *sessão*. As informações trocadas entre o aplicativo e o Amazon Lex compõem o estado da sessão para a conversa. Quando você faz uma solicitação, a sessão é identificada por uma combinação do nome do bot e um identificador de usuário especificado por você. Para obter mais informações sobre o identificador de usuário, consulte o campo `userId` na operação [PostContent](API_runtime_PostContent.md) ou [PostText](API_runtime_PostText.md).
A resposta de uma operação de sessão inclui um identificador exclusivo que identifica uma sessão específica com um usuário. Você pode usar esse identificador durante o teste ou para ajudar a solucionar problemas no bot.
É possível modificar o estado da sessão enviado entre o aplicativo e o bot. Por exemplo, você pode criar e modificar os atributos que contêm informações personalizadas sobre a sessão e alterar o fluxo da conversa definindo o contexto de diálogo para interpretar a próxima declaração.
Há duas maneiras de atualizar o estado da sessão. A primeira é usar uma função do Lambda com a operação `PostContent` ou `PostText` que é chamada após cada turno da conversa. Para obter mais informações, consulte [Uso de funções do Lambda](using-lambda.md). A outra é usar a API de runtime do Amazon Lex no seu aplicativo para fazer alterações no estado da sessão.
A API de runtime do Amazon Lex oferece operações que permitem gerenciar informações da sessão para uma conversa com o bot. As operações são [PutSession](API_runtime_PutSession.md), [GetSession](API_runtime_GetSession.md) e [DeleteSession](API_runtime_DeleteSession.md). Você pode usar essas operações para obter informações sobre o estado da sessão do seu usuário com o bot e ter um controle apurado sobre o estado.
Use a operação `GetSession` quando desejar obter o estado atual da sessão. A operação retorna o estado atual da sessão, incluindo o estado do diálogo com o usuário, todos os atributos de sessão que foram definidos e valores de slot das três últimas intenções com as quais o usuário interagiu.
A operação `PutSession` permite manipular diretamente o estado da sessão atual. Você pode definir o tipo de ação de diálogo que o bot realizará em seguida. Isso oferece a você controle sobre o fluxo da conversa com o bot. Defina o campo de ação de diálogo `type` como `Delegate` para que o Amazon Lex determine a próxima ação do bot.
Você pode usar a operação `PutSession` para criar uma nova sessão com um bot e definir a intenção com a qual ele deve começar. Também é possível usar a operação `PutSession` para mudar de uma intenção para outra. Ao criar uma sessão ou alterar a intenção, você também pode definir o estado da sessão, como valores de slot e atributos de sessão. Quando a nova intenção é concluída, você tem a opção de reiniciar a intenção anterior. É possível usar a operação `GetSession` para obter o estado do diálogo da intenção anterior do Amazon Lex e usar as informações para definir o estado do diálogo da intenção.
A resposta da operação `PutSession` contém as mesmas informações que a operação `PostContent`. Você pode usar essas informações para solicitar a próxima informação ao usuário, da mesma forma que faria com a resposta da operação `PostContent`.
Use a operação `DeleteSession` para remover uma sessão existente e começar de novo com uma nova sessão. Por exemplo, ao testar seu bot, você pode usar a operação `DeleteSession` para remover as sessões de teste do seu bot.
As operações de sessão trabalham com as funções do Lambda de atendimento. Por exemplo, se sua função do Lambda retornar `Failed` como o estado de atendimento, você poderá usar a operação `PutSession` para definir o tipo de ação de diálogo como `close` e `fulfillmentState` como `ReadyForFulfillment` para repetir a etapa de atendimento.
Veja a seguir algumas ações que você pode executar com as operações de sessão:
+ Fazer com que o bot inicie uma conversa em vez de esperar pelo usuário.
+ Alternar entre as intenções durante uma conversa.
+ Voltar para uma intenção anterior.
+ Iniciar ou reiniciar uma conversa no meio da interação.
+ Validar valores de slot e fazer com que o bot solicite novamente valores que não são válidos.
Cada uma delas é descrita com mais detalhes a seguir.
## Alternância entre intenções
Você pode usar a operação `PutSession` para alternar de uma intenção para outra. Também é possível usá-la para voltar para uma intenção anterior. Você pode usar a operação `PutSession` para definir atributos de sessão ou valores de slot para a nova intenção.
+ Chame a operação `PutSession`. Defina o nome da intenção como o nome da nova intenção e defina a ação de diálogo como `Delegate`. Você também pode definir quaisquer valores de slot ou atributos de sessão necessários para a nova intenção.
+ O Amazon Lex iniciará uma conversa com o usuário utilizando a nova intenção.
## Como retomar uma intenção anterior
Para retomar uma intenção anterior, use a operação `GetSession` para obter o resumo da intenção e, depois, use a operação `PutSession` para definir a intenção como seu estado de diálogo anterior.
+ Chame a operação `GetSession`. A resposta da operação inclui um resumo do estado de diálogo das últimas três intenções com as quais o usuário interagiu.
+ Usando as informações do resumo de intenção, chame a operação `PutSession`. Isso retornará o usuário para a intenção anterior no mesmo local na conversa.
Em alguns casos, pode ser necessário retomar a conversa do usuário com o bot. Por exemplo, digamos que você tenha criado um bot de atendimento ao cliente. Seu aplicativo determina que o usuário precisa conversar com um representante de atendimento ao cliente. Depois de falar com o usuário, o representante poderá direcionar a conversa de volta para o bot com as informações coletadas.
Para retomar uma sessão, use etapas semelhantes a estas:
+ Seu aplicativo determina que o usuário precisa falar com um representante de atendimento ao cliente.
+ Use a operação `GetSession` para obter o estado de diálogo atual da intenção.
+ O representante de atendimento ao cliente se comunica com o usuário e resolve o problema.
+ Use a operação `PutSession` para definir o estado de diálogo da intenção. Isso pode incluir definir valores de slot, definir atributos de sessão ou alterar a intenção.
+ O bot retoma a conversa com o usuário.
É possível usar o parâmetro `checkpointLabel` da operação `PutSession` a fim de rotular uma intenção para que seja possível localizá-la mais tarde. Por exemplo, um bot que solicita informações a um cliente pode entrar em uma intenção `Waiting` enquanto o cliente coleta as informações. O bot cria um rótulo de ponto de verificação para a intenção atual e inicia a intenção `Waiting`. Quando o cliente retornar, o bot poderá encontrar a intenção anterior usando o rótulo de ponto de verificação e alternar de volta.
A intenção deve estar presente na estrutura `recentIntentSummaryView` retornada pela operação `GetSession`. Se você especificar um rótulo de ponto de verificação na solicitação da operação `GetSession`, ele retornará um máximo de três intenções com esse rótulo de ponto de verificação.
+ Use a operação `GetSession` para obter o estado atual da sessão.
+ Use a operação `PutSession` para adicionar um rótulo de ponto de verificação à última intenção. Se necessário, é possível usar esta chamada `PutSession` para alternar para uma intenção diferente.
+ Quando for o momento de retornar à intenção rotulada, chame a operação `GetSession` para retornar uma lista de intenções recente. É possível usar o parâmetro `checkpointLabelFilter` para que o Amazon Lex retorne somente as intenções com o rótulo do ponto de verificação especificado.
## Como iniciar uma nova sessão
Se você desejar que o bot inicie a conversa com o usuário, use a operação `PutSession`.
+ Crie uma intenção de boas-vindas sem slots e uma mensagem de conclusão solicitando que o usuário indique uma intenção. Por exemplo, "O que você gostaria de pedir? Você pode dizer "Pedir uma bebida" ou "Pedir uma pizza".
+ Chame a operação `PutSession`. Defina o nome da intenção como o nome da intenção de boas-vindas e defina a ação de diálogo como `Delegate`.
+ O Amazon Lex responderá com o prompt da sua intenção de boas-vindas para iniciar a conversa com o usuário.
## Validação de valores de slot
Você pode validar as respostas ao bot usando seu aplicativo cliente. Se a resposta não for válida, use a operação `PutSession` para obter uma nova resposta do usuário. Por exemplo, suponha que seu bot de pedido de flores só possa vender tulipas, rosas e lírios. Se o usuário pedir cravos, o aplicativo poderá fazer o seguinte:
+ Examinar o valor do slot retornado pela resposta `PostText` ou `PostContent`.
+ Se o valor do slot não for válido, chame a operação `PutSession`. Seu aplicativo deve limpar o valor do slot, definir o campo `slotToElicit` e definir o valor `dialogAction.type` como `elicitSlot`. Você também poderá definir os campos `message` e `messageFormat` se desejar alterar a mensagem usada pelo Amazon Lex para obter o valor de slot.
# Opções de implantação de bot
No momento, o Amazon Lex fornece as seguintes opções de implantação do bot:
+ [SDK móvel da AWS](https://aws.amazon.com/mobile/sdk/) — Você pode criar aplicativos móveis que se comunicam com o Amazon Lex usando o AWS Mobile SDKs.
+ Facebook Messenger: você pode integrar sua página do Facebook Messenger ao bot do Amazon Lex para que os usuários finais no Facebook possam se comunicar com o bot. Na implementação atual, essa integração oferece suporte apenas as mensagens de entrada de texto.
+ Slack: você pode integrar seu bot Amazon Lex a um aplicativo de mensagens Slack.
+ Twilio: você pode integrar seu bot do Amazon Lex ao serviço Twilio Simple Messaging Service (SMS).
Para obter exemplos, consulte [Implantação de bots do Amazon Lex](examples.md).
# Intenções integradas e tipos de slot
Para facilitar a criação dos bots, o Amazon Lex permite que você use as intenções integradas e os tipos de slot padrão.
**Topics**
+ [Intenções integradas](howitworks-builtins-intents.md)
+ [Tipos de slot integrados](howitworks-builtins-slots.md)
# Intenções integradas
Para ações comuns, você pode usar a biblioteca de intenções integradas padrão. Para criar uma intenção de uma intenção integrada, escolha uma intenção no console e forneça um novo nome. A nova intenção tem a configuração de intenção básica, como a amostra de declarações.
Na implementação atual, você não pode:
+ Adicionar ou remover amostra de declarações da intenção básica
+ Configurar slots para intenções integradas
**Para adicionar uma intenção integrada a um bot**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha o bot ao qual adicionar a intenção integrada.
1. No painel de navegação, escolha o sinal de adição (\$1) ao lado de **Intenções**.
1. Em **Adicionar intenção**, escolha **Pesquisar intenções existentes**.
1. Na caixa **Intenções de pesquisa**, insira o nome da intenção integrada a ser adicionada ao seu bot.
1. Em **Copiar intenção integrada**, dê um nome à intenção e escolha **Adicionar**.
1. Configure a intenção conforme necessário para o seu bot.
**Topics**
+ [AMAZON.CancelIntent](built-in-intent-cancel.md)
+ [AMAZON.FallbackIntent](built-in-intent-fallback.md)
+ [AMAZON.HelpIntent](built-in-intent-help.md)
+ [AMAZON.KendraSearchIntent](built-in-intent-kendra-search.md)
+ [AMAZON.PauseIntent](built-in-intent-pause.md)
+ [AMAZON.RepeatIntent](built-in-intent-repeat.md)
+ [AMAZON.ResumeIntent](built-in-intent-resume.md)
+ [AMAZON.StartOverIntent](built-in-intent-start-over.md)
+ [AMAZON.StopIntent](built-in-intent-stop.md)
**nota**
Para a localidade em inglês (EUA) (en-US), o Amazon Lex oferece suporte a intenções integradas padrão da Alexa. Para obter uma lista de intenções integradas, consulte [Intenções integradas padrão](https://developer.amazon.com/docs/custom-skills/standard-built-in-intents.html) no *Alexa Skills Kit*.
O Amazon Lex não oferece suporte às seguintes intenções:
`AMAZON.YesIntent`
`AMAZON.NoIntent`
As intenções na [Biblioteca de intenções integradas](https://developer.amazon.com/docs/custom-skills/built-in-intent-library.html) do *Alexa Skills Kit*
# AMAZON.CancelIntent
Responde a palavras e frases que indicam que o usuário deseja cancelar a interação atual. Seu aplicativo pode usar essa intenção para remover valores do tipo de slot e outros atributos antes de encerrar a interação com o usuário.
Declarações comuns:
+ cancelar
+ não se preocupe
+ esqueça
# AMAZON.FallbackIntent
Quando a entrada de um usuário em uma intenção não é o que um bot espera, você pode configurar o Amazon Lex para invocar uma *intenção de fallback*. Por exemplo, se a entrada do usuário "Eu gostaria de pedir doce" não corresponder a uma intenção em seu bot `OrderFlowers`, o Amazon Lex invocará a intenção de fallback para lidar com a resposta.
Inclua uma intenção de fallback adicionando o tipo de intenção `AMAZON.FallbackIntent` integrada ao bot. Você pode especificar a intenção usando a operação [PutBot](API_PutBot.md) ou escolhendo a intenção na lista de intenções integradas no console.
A invocação de uma intenção de fallback usa duas etapas. Na primeira etapa, a intenção de fallback é correspondida com base na entrada do usuário. Quando a intenção de fallback é correspondida, a maneira como o bot se comporta depende do número de novas tentativas configuradas para um prompt. Por exemplo, se o número máximo de tentativas para determinar uma intenção for 2, o bot retornará o prompt de esclarecimento do bot duas vezes antes de invocar a intenção de fallback.
O Amazon Lex corresponde à intenção de fallback nestas situações:
+ A entrada do usuário para uma intenção não corresponde à entrada esperada pelo bot
+ A entrada de áudio é ruído ou a entrada de texto não é reconhecida como palavras.
+ A entrada do usuário é ambígua, e o Amazon Lex não consegue determinar qual intenção invocar.
A intenção de fallback é invocada quando:
+ O bot não reconhece a entrada do usuário como uma intenção após o número configurado de tentativas para esclarecimento quando a conversa é iniciada.
+ Uma intenção não reconhece a entrada do usuário como um valor de slot após o número configurado de tentativas.
+ Uma intenção não reconhece a entrada do usuário como uma resposta a um prompt de confirmação após o número configurado de tentativas.
Você pode usar o seguinte com uma intenção de fallback:
+ Uma função do Lambda de atendimento
+ Uma declaração de conclusão
+ Um prompt de acompanhamento
Você não pode adicionar o seguinte a uma intenção de fallback:
+ Enunciados
+ Slots
+ Uma função do Lambda de inicialização e validação
+ Um prompt de confirmação
Se você tiver configurado uma instrução de anulação e uma intenção de fallback para um bot, o Amazon Lex usará a intenção de fallback. Se você precisar que seu bot tenha uma instrução de cancelamento, use a função de atendimento para que a intenção de fallback forneça o mesmo comportamento que uma instrução de cancelamento. Para obter mais informações, consulte o parâmetro `abortStatement` da operação [PutBot](API_PutBot.md).
## Usar prompts de esclarecimento
Se você fornecer ao bot um prompt de esclarecimento, o prompt será usado para solicitar uma intenção válida do usuário. O prompt de esclarecimento será repetido o número de vezes que você configurou. Depois disso, a intenção de fallback será invocada.
Se você não definir um prompt de esclarecimento ao criar um bot e o usuário não iniciar a conversa com uma intenção válida, o Amazon Lex chamará imediatamente sua intenção de fallback.
Quando você usa uma intenção de fallback sem um prompt de esclarecimento, o Amazon Lex não chama o fallback nestas circunstâncias:
+ Quando o usuário responde a um prompt de acompanhamento, mas não fornece uma intenção. Por exemplo, em resposta a um prompt de acompanhamento que diz "Você quer mais alguma coisa hoje?", o usuário diz "Sim". O Amazon Lex retorna uma exceção 400 Bad Request porque não tem um prompt de esclarecimento para enviar ao usuário e obter uma intenção.
+ Ao usar uma AWS Lambda função, você retorna um tipo `ElicitIntent` de diálogo. Como o Amazon Lex não tem um prompt de esclarecimento para obter uma intenção do usuário, ele retorna uma exceção 400 Bad Request.
+ Ao usar a operação `PutSession`, envie um tipo de diálogo `ElicitIntent`. Como o Amazon Lex não tem um prompt de esclarecimento para obter uma intenção do usuário, ele retorna uma exceção 400 Bad Request.
## Usar uma função do Lambda com uma intenção de fallback
Quando uma intenção de fallback é invocada, a resposta depende da configuração do parâmetro `fulfillmentActivity` para a operação [PutIntent](API_PutIntent.md). O bot realiza uma das seguintes ações:
+ Retorna as informações de intenção para o aplicativo cliente.
+ Chama a função do Lambda de atendimento. Ele chama a função com as variáveis de sessão que são definidas para a sessão.
Para obter mais informações sobre como definir a resposta quando uma intenção de fallback é invocada, consulte o parâmetro `fulfillmentActivity` da operação [PutIntent](API_PutIntent.md).
Se você usar a função do Lambda de atendimento em sua intenção de fallback, poderá usar essa função para chamar outra intenção ou executar alguma forma de comunicação com o usuário, como coletar um número de retorno de chamada ou abrir uma sessão com um representante de atendimento ao cliente.
É possível executar qualquer ação em uma função do Lambda de intenção de fallback que possa ser executada na função de cumprimento para qualquer outra intenção. Para obter mais informações sobre como criar uma função de atendimento usando AWS Lambda, consulte[Uso de funções do Lambda](using-lambda.md).
Uma intenção de fallback pode ser invocada várias vezes na mesma sessão. Por exemplo, imagine que a função do Lambda usa a ação de diálogo `ElicitIntent` para solicitar ao usuário uma intenção diferente. Se o Amazon Lex não conseguir inferir a intenção do usuário após o número configurado de tentativas, ele invocará a intenção de fallback novamente. Ele também invoca a intenção de fallback quando o usuário não responde com um valor de slot válido após o número configurado de tentativas.
É possível configurar uma função do Lambda para controlar o número de vezes que a intenção de fallback é chamada usando uma variável de sessão. Sua função do Lambda poderá executar uma ação diferente se for chamada mais vezes do que o limite definido na função do Lambda. Para mais informações sobre variáveis de sessão, consulte [Definição dos atributos da sessão](context-mgmt-session-attribs.md).
# AMAZON.HelpIntent
Responde a palavras ou frases que indicam que o usuário precisa de ajuda ao interagir com seu bot. Quando essa intenção é invocada, você pode configurar o aplicativo ou a função do Lambda para fornecer informações sobre os recursos do seu bot, fazer perguntas de acompanhamento sobre áreas de ajuda ou entregar a interação a um atendente humano.
Declarações comuns:
+ ajuda
+ ajude-me
+ você pode me ajudar
# AMAZON.KendraSearchIntent
Para pesquisar documentos indexados com o Amazon Kendra, use a intenção `AMAZON.KendraSearchIntent`. Quando o Amazon Lex não consegue determinar a próxima ação em uma conversa com o usuário, ele aciona a intenção de pesquisa.
O `AMAZON.KendraSearchIntent` está disponível somente em inglês (EUA) (en-US) e nas regiões Leste dos EUA (Norte da Virgínia), Oeste dos EUA (Oregon) e Europa (Irlanda).
O Amazon Kendra é machine-learning-based um serviço de pesquisa que indexa documentos em linguagem natural, como documentos PDF ou arquivos do Microsoft Word. Ele pode pesquisar documentos indexados e retornar os seguintes tipos de respostas a uma pergunta:
+ Uma resposta
+ Uma entrada de uma pergunta frequente que pode responder à pergunta
+ Um documento relacionado à pergunta
Para ver um exemplo de uso de `AMAZON.KendraSearchIntent`, consulte [Exemplo: criar um bot de perguntas frequentes para um índice do Amazon Kendra](faq-bot-kendra-search.md).
Se você configurar uma intenção `AMAZON.KendraSearchIntent` para o bot, o Amazon Lex chamará a intenção sempre que não conseguir determinar a declaração do usuário para um slot ou uma intenção. Por exemplo, se o bot estiver provocando uma resposta para um tipo de slot chamado "cobertura de pizza" e o usuário disser "O que é pizza?", o Amazon Lex chamará `AMAZON.KendraSearchIntent` para lidar com a pergunta. Se não houver resposta do Amazon Kendra, a conversa continuará conforme configurado no bot.
Quando `AMAZON.KendraSearchIntent` e `AMAZON.FallbackIntent` são usadas no mesmo bot, o Amazon Lex usa as intenções da seguinte forma:
1. O Amazon Lex chama `AMAZON.KendraSearchIntent`. A intenção chama a operação `Query` do Amazon Kendra.
1. Se o Amazon Kendra retornar uma resposta, o Amazon Lex exibirá o resultado para o usuário.
1. Se não houver resposta do Amazon Kendra, o Amazon Lex avisará novamente o usuário. A próxima ação depende da resposta do usuário.
+ Se a resposta do usuário contiver uma declaração reconhecida pelo Amazon Lex, como preencher um valor de slot ou confirmar uma intenção, a conversa com o usuário prosseguirá conforme configurado para o bot.
+ Se a resposta do usuário não contiver uma declaração reconhecida pelo Amazon Lex, o Amazon Lex fará outra chamada para a operação `Query`.
1. Se não houver resposta após o número configurado de novas tentativas, o Amazon Lex chamará `AMAZON.FallbackIntent` e encerrará a conversa com o usuário.
Há três maneiras de usar `AMAZON.KendraSearchIntent` para fazer uma solicitação ao Amazon Kendra:
+ Deixe que a intenção da pesquisa faça a solicitação por você. O Amazon Lex chama o Amazon Kendra com a declaração do usuário como a string de pesquisa. Ao criar a intenção, você pode definir uma string de filtro de consulta que limite o número de respostas retornadas pelo Amazon Kendra. O Amazon Lex usa o filtro na solicitação de consulta.
+ Adicione outros parâmetros de consulta à solicitação para restringir os resultados da pesquisa usando a função do Lambda do diálogo. Adicione um campo `kendraQueryFilterString` que contém parâmetros de consulta do Amazon Kendra à ação de diálogo `delegate`. Quando parâmetros de consulta são adicionados à solicitação com a função do Lambda, eles têm precedência sobre o filtro de consulta definido quando a intenção foi criada.
+ Crie uma consulta usando a função do Lambda do diálogo. É possível criar uma solicitação de consulta completa do Amazon Kendra enviada pelo Amazon Lex. Especifique a consulta no campo `kendraQueryRequestPayload` na ação de diálogo `delegate`. O campo `kendraQueryRequestPayload` tem precedência sobre o campo `kendraQueryFilterString`.
Para especificar o parâmetro `queryFilterString` ao criar um bot ou especificar o campo `kendraQueryFilterString` ao chamar a ação `delegate` em uma função do Lambda do diálogo, especifique uma string usada como filtro de atributo para a consulta do Amazon Kendra. Se a string não for um filtro de atributo válido, você receberá uma exceção `InvalidBotConfigException` em runtime. Para obter mais informações sobre filtros de atributo, consulte [Usar atributos de documento para filtrar consultas](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering) no *Guia do desenvolvedor do Amazon Kendra*.
Para ter controle sobre a consulta enviada pelo Amazon Lex para o Amazon Kendra, é possível especificar uma consulta no campo `kendraQueryRequestPayload` na função do Lambda do diálogo. Se a consulta não for válida, o Amazon Lex retornará uma exceção `InvalidLambdaResponseException`. Para obter mais informações, consulte a [Operação de consulta](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html) no *Guia do desenvolvedor do Amazon Kendra*.
Para obter um exemplo de como usar a `AMAZON.KendraSearchIntent`, consulte [Exemplo: criar um bot de perguntas frequentes para um índice do Amazon Kendra](faq-bot-kendra-search.md).
## Política do IAM para pesquisa Amazon Kendra
Para usar a `AMAZON.KendraSearchIntent` intenção, você deve usar uma função que forneça políticas AWS Identity and Access Management (IAM) que permitam ao Amazon Lex assumir uma função de tempo de execução que tenha permissão para chamar a intenção do Amazon Kendra`Query`. As configurações do IAM que você usa dependem de você criar o `AMAZON.KendraSearchIntent` usando o console Amazon Lex ou usando um SDK da AWS ou o AWS Command Line Interface (AWS CLI). Quando o console é usado, é possível escolher entre adicionar permissão para chamar o Amazon Kendra para a função vinculada ao serviço do Amazon Lex ou usar uma função especificamente para chamar a operação `Query` do Amazon Kendra. Ao usar o AWS CLI ou um SDK para criar a intenção, você deve usar uma função específica para chamar a `Query` operação.
### Anexar permissões
É possível usar o console para anexar permissões para acessar a operação `Query` do Amazon Kendra à função vinculada ao serviço padrão do Amazon Lex. Quando você anexa permissões à função vinculada ao serviço, não precisa criar e gerenciar uma função de runtime especificamente para se conectar ao índice do Amazon Kendra.
O usuário, a função ou o grupo usado para acessar o console do Amazon Lex deve ter permissões para gerenciar políticas de função. Anexe a política do IAM à função de acesso do console. Quando essas permissões são concedidas, a função tem permissões para alterar a política de função vinculada ao serviço existente.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:PutRolePolicy",
"iam:GetRolePolicy"
],
"Resource": "arn:aws:iam::*:role/aws-service-role/lex.amazonaws.com/AWSServiceRoleForLexBots"
},
{
"Effect": "Allow",
"Action": "iam:ListRoles",
"Resource": "*"
}
]
}
```
------
### Especificar uma função
Você pode usar o console AWS CLI, o ou a API para especificar uma função de tempo de execução a ser usada ao chamar a operação Amazon `Query` Kendra.
O usuário, a função ou o grupo utilizado para especificar a função de runtime deve ter a permissão `iam:PassRole`. A política a seguir define a permissão. É possível usar as chaves de contexto de condição `iam:AssociatedResourceArn` e `iam:PassedToService` para limitar ainda mais o escopo das permissões. Para obter mais informações, consulte [IAM e AWS STS Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html) no *Guia AWS Identity and Access Management do usuário*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/role"
}
]
}
```
------
A função de runtime que o Amazon Lex precisa usar para chamar o Amazon Kendra deve ter as permissões `kendra:Query`. Quando você usa um perfil do IAM existente para obter permissão para chamar a operação `Query` do Amazon Kendra, a função deve ter a política a seguir anexada.
É possível usar o console do IAM, a API do IAM ou a AWS CLI para criar uma política e anexá-la a uma função. Essas instruções usam a CLI da AWS para criar a função e as políticas.
**nota**
O código a seguir é formatado para Linux e MacOS. Para Windows, substitua o caractere de continuação de linha do Linux (\$1) pelo circunflexo (^).
**Como adicionar permissão de operação de consulta a uma função**
1. Crie um documento chamado **KendraQueryPolicy.json** no diretório atual, adicione a ele o código a seguir e salve-o.
1. No AWS CLI, execute o comando a seguir para criar a política do IAM para executar a operação Amazon `Query` Kendra.
```
aws iam create-policy \
--policy-name query-policy-name \
--policy-document file://KendraQueryPolicy.json
```
1. Anexe a política ao perfil do IAM utilizado para chamar a operação `Query`.
```
aws iam attach-role-policy \
--policy-arn arn:aws:iam::account-id:policy/query-policy-name
--role-name role-name
```
É possível optar por atualizar a função vinculada ao serviço do Amazon Lex ou usar uma função que você criou ao criar o `AMAZON.KendraSearchIntent` para o bot. O procedimento a seguir mostra como escolher o perfil do IAM a ser usado.
**Para especificar a função de tempo de execução da AMAZON. KendraSearchIntent**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha o bot ao qual você deseja adicionar a `AMAZON.KendraSearchIntent`.
1. Escolha o sinal de adição (\$1) ao lado de **Intenções**.
1. Em **Adicionar intenção**, escolha **Pesquisar intenções existentes**.
1. Em **Intenções de pesquisa**, insira **AMAZON.KendraSearchIntent** e escolha **Adicionar**.
1. Em **Copiar intenção interna**, insira um nome para a intenção, como **KendraSearchIntent**, e escolha **Adicionar**.
1. Abra a seção **Consulta do Amazon Kendra**.
1. Para **Perfil do IAM**, escolha uma das seguintes opções:
+ Para atualizar a função vinculada ao serviço do Amazon Lex para permitir que o bot consulte índices do Amazon Kendra, escolha **Adicionar permissões do Amazon Kendra**.
+ Para usar uma função que tenha permissão para chamar a operação `Query` do Amazon Kendra, escolha **Usar uma função existente**.
## Usar atributos de solicitação e sessão como filtros
Para filtrar a resposta do Amazon Kendra a itens relacionados à conversa atual, use atributos de sessão e solicitação como filtros adicionando o parâmetro `queryFilterString` ao criar o bot. Especifique um espaço reservado para o atributo ao criar a intenção e, depois, o Amazon Lex V2 substituirá um valor antes de chamar o Amazon Kendra. Para mais informações sobre atributos de solicitação, consulte [Definição de atributos de solicitação](context-mgmt-request-attribs.md). Para mais informações sobre atributos de sessão, consulte [Definição dos atributos da sessão](context-mgmt-session-attribs.md).
Veja a seguir um exemplo de parâmetro `queryFilterString` que usa uma string para filtrar a consulta do Amazon Kendra.
```
"{"equalsTo": {"key": "City", "value": {"stringValue": "Seattle"}}}"
```
Veja a seguir um exemplo de um parâmetro `queryFilterString` que usa um atributo de sessão chamado `"SourceURI"` para filtrar a consulta do Amazon Kendra.
```
"{"equalsTo": {"key": "SourceURI","value": {"stringValue": "[FileURL]"}}}"
```
Veja a seguir um exemplo de parâmetro `queryFilterString` que usa um atributo de solicitação chamado `"DepartmentName"` para filtrar a consulta do Amazon Kendra.
```
"{"equalsTo": {"key": "Department","value": {"stringValue": "((DepartmentName))"}}}"
```
Os filtros `AMAZON.KendraSearchInteng` usam o mesmo formato dos filtros de pesquisa do Amazon Kendra. Para obter mais informações, consulte [Usar atributos de documento para filtrar os resultados da pesquisa](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering) no *Guia do desenvolvedor do Amazon Kendra*.
A string do filtro de consulta usada com o `AMAZON.KendraSearchIntent` deve usar letras minúsculas para a primeira letra de cada filtro. Por exemplo, veja a seguir um filtro de consulta válido para o `AMAZON.KendraSearchIntent`.
```
{
"andAllFilters": [
{
"equalsTo": {
"key": "City",
"value": {
"stringValue": "Seattle"
}
}
},
{
"equalsTo": {
"key": "State",
"value": {
"stringValue": "Washington"
}
}
}
]
}
```
## Usar a resposta da pesquisa
O Amazon Kendra retorna a resposta a uma pesquisa na instrução `conclusion` da intenção. A intenção deve ter uma instrução `conclusion`, a menos que uma função do Lambda de atendimento produza uma mensagem de conclusão.
O Amazon Kendra tem quatro tipos de respostas.
+ `x-amz-lex:kendra-search-response-question_answer-question-`: a pergunta de uma pergunta frequente correspondente à pesquisa.
+ `x-amz-lex:kendra-search-response-question_answer-answer-`: a resposta de uma pergunta frequente correspondente à pesquisa.
+ `x-amz-lex:kendra-search-response-document-`: um trecho de um documento no índice relacionado ao texto da declaração.
+ `x-amz-lex:kendra-search-response-document-link-`: o URL de um documento no índice relacionado ao texto da declaração.
+ `x-amz-lex:kendra-search-response-answer-`: um trecho de um documento no índice que responde à pergunta.
As respostas são retornadas em atributos `request`. Pode haver até cinco respostas para cada atributo, numeradas de 1 a 5. Para obter mais informações sobre respostas, consulte [Tipos de resposta](https://docs.aws.amazon.com/kendra/latest/dg/response-types.html) no *Guia do desenvolvedor do Amazon Kendra*.
A instrução `conclusion` deve ter um ou mais grupos de mensagens. Cada grupo de mensagens contém uma ou mais mensagens. Cada mensagem pode conter uma ou mais variáveis de espaço reservado que são substituídas por atributos de solicitação na resposta do Amazon Kendra. Deve haver pelo menos uma mensagem no grupo de mensagens em que todas as variáveis na mensagem são substituídas por valores de atributo de solicitação na resposta de runtime, ou deve haver uma mensagem no grupo sem variáveis de espaço reservado. Os atributos de solicitação são ativados com parênteses duplos ("((" "))"). As mensagens do grupo de mensagens a seguir correspondem a qualquer resposta do Amazon Kendra:
+ “Encontrei uma pergunta de FAQ para você: ((x-amz-lex: kendra-search-response-question \$1resposta-pergunta-1)), e a resposta é ((x-amz-lex: \$1resposta-resposta-1))” kendra-search-response-question
+ “Encontrei um trecho de um documento útil: ((x-amz-lex: kendra-search-response-document -1))”
+ “Acho que a resposta às suas perguntas é ((x-amz-lex: kendra-search-response-answer -1))”
## Usar uma função do Lambda para gerenciar a solicitação e a resposta
A intenção `AMAZON.KendraSearchIntent` pode usar o hook de código de diálogo e o hook de código de atendimento para gerenciar a solicitação ao Amazon Kendra e a resposta. Utilize a função do Lambda do hook de código de diálogo quando quiser modificar a consulta enviada ao Amazon Kendra e a função do Lambda de hook de código de atendimento quando quiser modificar a resposta.
### Criar uma consulta com o hook de código de diálogo
É possível usar o hook de código de diálogo para criar uma consulta para enviar ao Amazon Kendra. O uso do hook de código de diálogo é opcional. Se você não especificar um hook de código de diálogo, o Amazon Lex criará uma consulta a partir da declaração do usuário e usará a `queryFilterString` fornecida quando você configurou a intenção, se você a tiver fornecido.
É possível usar dois campos na resposta do hook de código de diálogo para modificar a solicitação ao Amazon Kendra:
+ `kendraQueryFilterString`: use essa string para especificar filtros de atributo para a solicitação do Amazon Kendra. É possível filtrar a consulta usando qualquer um dos campos de índice definidos no índice. Para obter a estrutura da string de filtro, consulte [Usar atributos de documento para filtrar consultas](https://docs.aws.amazon.com/kendra/latest/dg/filtering.html#search-filtering) no *Guia do desenvolvedor do Amazon Kendra*. Se a string de filtro especificada não for válida, você receberá uma exceção `InvalidLambdaResponseException`. A string `kendraQueryFilterString` substitui qualquer string de consulta especificada na `queryFilterString` configurada para a intenção.
+ `kendraQueryRequestPayload`: use essa string para especificar uma consulta do Amazon Kendra. Sua consulta pode usar qualquer um dos atributos do Amazon Kendra. Se você não especificar uma consulta válida, receberá uma exceção `InvalidLambdaResponseException`. Para obter mais informações, configura [Consulta](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html) no *Guia do desenvolvedor do Amazon Kendra*.
Depois de criar o filtro ou a sequência de caracteres de consulta, você envia a resposta para o Amazon Lex com o `dialogAction` campo da resposta definido como`delegate`. O Amazon Lex envia a consulta para a Amazon Kendra e, em seguida, retorna a resposta da consulta ao hook do código de atendimento.
### Usar o hook de código de atendimento para a resposta
Depois que o Amazon Lex envia uma consulta ao Amazon Kendra, a resposta da consulta é retornada para a função do Lambda de cumprimento `AMAZON.KendraSearchIntent`. O evento de entrada para o hook de código contém a resposta completa do Amazon Kendra. Os dados da consulta estão na mesma estrutura que os retornados pela operação `Query` do Amazon Kendra. Para obter mais informações, consulte [Sintaxe de resposta de consulta](https://docs.aws.amazon.com/kendra/latest/dg/API_Query.html#API_Query_ResponseSyntax) no *Guia do desenvolvedor do Amazon Kendra*.
O hook de código de atendimento é opcional. Se não houver nenhum ou se o hook de código não retornar uma mensagem na resposta, o Amazon Lex usará a instrução `conclusion` para respostas.
# Exemplo: criar um bot de perguntas frequentes para um índice do Amazon Kendra
Este exemplo cria um bot do Amazon Lex que usa um índice do Amazon Kendra para fornecer respostas às perguntas dos usuários. O bot de perguntas frequentes gerencia a caixa de diálogo para o usuário. Ele usa a intenção `AMAZON.KendraSearchIntent` para consultar o índice e apresentar a resposta ao usuário. Para criar o bot, você deve:
1. Criar um bot com o qual seus clientes vão interagir para obter respostas do bot.
1. Criar uma intenção personalizada. O bot requer pelo menos uma intenção com pelo menos uma declaração. Essa intenção permite que o bot crie, mas não seja usado de outra forma.
1. Adicionar a intenção `KendraSearchIntent` ao bot e configurá-lo para trabalhar com o índice do Amazon Kendra.
1. Testar o bot fazendo perguntas que são respondidas por documentos armazenados no índice do Amazon Kendra.
Antes de usar este exemplo, é necessário criar um índice do Amazon Kendra. Para obter mais informações, consulte [Começar a usar um bucket do S3 (console)](https://docs.aws.amazon.com/kendra/latest/dg/gs-console.html) no *Guia do desenvolvedor do Amazon Kendra*.
**Como criar um bot de perguntas frequentes**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. No painel de navegação, escolha **Bots**.
1. Escolha **Criar**.
1. Selecione **Custom bot (Bot personalizado)**. Configure o bot da seguinte forma:
+ **Nome do bot**: dê ao bot um nome que indique sua finalidade, como **KendraTestBot**.
+ **Voz de saída**: escolha **Nenhuma**.
+ **Tempo limite da sessão**: insira **5**.
+ **Análise de sentimento**: escolha **Não**.
+ **COPPA**: escolha **Não**.
+ **Armazenamento da declaração do usuário**: escolha **Não armazenar**.
1. Escolha **Criar**.
Para criar um bot com êxito, é necessário criar pelo menos uma intenção com pelo menos uma amostra de declaração. Essa intenção é necessária para criar o bot do Amazon Lex, mas não é usada para a resposta de perguntas frequentes. A declaração para a intenção não deve se aplicar a nenhuma das perguntas feitas pelo cliente.
**Como criar a intenção necessária**
1. Na página **Começar a usar o bot**, escolha **Criar intenção**.
1. Em **Adicionar intenção**, escolha **Criar intenção**.
1. Na caixa de diálogo **Criar intenção**, dê um nome à intenção, como **RequiredIntent**.
1. Em **Amostra de declarações**, digite uma declaração, como **Required utterance**.
1. Selecione **Salvar intenção**.
Agora, crie a intenção de pesquisar um índice do Amazon Kendra e as mensagens de resposta que devem ser retornadas.
**Para criar uma AMAZON. KendraSearchIntent mensagem de intenção e resposta**
1. No painel de navegação, escolha o sinal de adição (\$1) ao lado de **Intenções**.
1. Em **Adicionar intenção**, escolha **Pesquisar intenções existentes**.
1. Na caixa **Pesquisar intenções**, insira **AMAZON.KendraSearchIntent** e escolha-a na lista.
1. Em **Copiar intenção interna**, dê um nome à intenção, como **KendraSearchIntent**, e escolha **Adicionar**.
1. No editor de intenções, escolha **Consulta do Amazon Kendra** para abrir as opções de consulta.
1. No menu **Índice do Amazon Kendra**, escolha o índice que a intenção deve pesquisar.
1. Na seção **Resposta**, adicione as três seguintes mensagens:
```
I found a FAQ question for you: ((x-amz-lex:kendra-search-response-question_answer-question-1)) and the answer is ((x-amz-lex:kendra-search-response-question_answer-answer-1)).
I found an excerpt from a helpful document: ((x-amz-lex:kendra-search-response-document-1)).
I think the answer to your questions is ((x-amz-lex:kendra-search-response-answer-1)).
```
1. Escolha **Salvar intenção** e selecione **Criar** para criar o bot.
Por fim, use a janela de teste do console para testar as respostas do bot. Suas perguntas devem estar no domínio compatível com o índice.
**Como testar o bot de perguntas frequentes**
1. Na janela de teste do console, digite uma pergunta para o índice.
1. Verifique a resposta na seção de resposta da janela de teste.
1. Para redefinir a janela de teste para outra pergunta, escolha **Limpar histórico de conversas**.
# AMAZON.PauseIntent
Responde a palavras e frases que permitem ao usuário pausar uma interação com um bot para que ele possa retornar a ela mais tarde. Seu aplicativo ou função do Lambda precisa salvar dados de intenção em variáveis de sessão, ou você precisa usar a operação [GetSession](API_runtime_GetSession.md) para recuperar dados de intenção ao retomar a intenção atual.
Declarações comuns:
+ pausar
+ pausar esse item
# AMAZON.RepeatIntent
Responde a palavras e frases que permitem ao usuário repetir a mensagem anterior. Seu aplicativo precisa usar uma função do Lambda para salvar as informações da intenção anterior nas variáveis da sessão, ou você precisa usar a [GetSession](API_runtime_GetSession.md) operação para obter as informações da intenção anterior.
Declarações comuns:
+ repetir
+ dizer isso de novo
+ repetir isso
# AMAZON.ResumeIntent
Responde a palavras e frases que permitem ao usuário retomar uma intenção anteriormente pausada. Seu aplicativo ou função do Lambda deve gerenciar as informações necessárias para retomar a intenção anterior.
Declarações comuns:
+ retomar
+ continuar
+ prosseguir
# AMAZON.StartOverIntent
Responde a palavras e frases que permitem ao usuário parar de processar a intenção atual e recomeçar do início. Você pode usar sua função do Lambda ou a operação `PutSession` para obter novamente o valor do primeiro slot.
Declarações comuns:
+ começar de novo
+ reiniciar
+ começar novamente
# AMAZON.StopIntent
Responde a palavras e frases que indicam que o usuário deseja parar de processar a intenção atual e encerrar a interação com um bot. Seu aplicativo ou função do Lambda deve limpar todos os atributos e valores do tipo de slot existentes e, em seguida, encerrar a interação.
Declarações comuns:
+ parar
+ desligar
+ cale-se
# Tipos de slot integrados
O Amazon Lex oferece suporte a tipos de slots integrados que definem como os dados no slot são reconhecidos e tratados. É possível criar slots desses tipos em suas intenções. Isso elimina a necessidade de criar valores de enumeração para dados de slot comumente usados, como data, hora e local. Os tipos de slot integrados não têm versões.
| Tipo de slot | Descrição breve | Localidades compatíveis |
| --- | --- | --- |
| [AMAZON.Airport](built-in-slot-airport.md) | Reconhece palavras que representam um aeroporto. | Todas as localidades |
| [AMAZÔNIA. AlphaNumeric](built-in-slot-alphanumeric.md) | Reconhece palavras compostas de letras e números. | Todas as localidades, exceto coreano (ko-KR) |
| [AMAZON.City](built-in-slot-city.md) | Reconhece palavras que representam uma cidade. | Todas as localidades |
| [AMAZON.Country](built-in-slot-country.md) | Reconhece palavras que representam um país. | Todas as localidades |
| [AMAZON.DATE](built-in-slot-date.md) | Reconhece palavras que representam uma data e as converte em um formato padrão. | Todas as localidades |
| [AMAZON.DURATION](built-in-slot-duration.md) | Reconhece palavras que representam duração e as converte em um formato padrão. | Todas as localidades |
| [AMAZÔNIA. EmailAddress](built-in-slot-email.md) | Converte palavras que representam um endereço de e-mail em um endereço de e-mail padrão. | Todas as localidades |
| [AMAZÔNIA. FirstName](built-in-slot-first-name.md) | Reconhece palavras que representam um nome. | Todas as localidades |
| [AMAZÔNIA. LastName](built-in-slot-last-name.md) | Reconhece palavras que representam um sobrenome. | Todas as localidades |
| [AMAZON.NUMBER](built-in-slot-number.md) | Reconhece palavras numéricas e as converte em dígitos. | Todas as localidades |
| [AMAZON.Percentage](built-in-slot-percent.md) | Converte palavras que representam uma porcentagem em um número e um sinal de porcentagem (%). | Todas as localidades |
| [AMAZÔNIA. PhoneNumber](built-in-slot-phone.md) | Converte palavras que representam um número de telefone em uma string numérica. | Todas as localidades |
| [AMAZÔNIA. SpeedUnit](built-in-slot-speed.md) | Converte palavras que representam uma unidade de velocidade em uma abreviatura padrão. | Inglês (EUA) (en-US) |
| [AMAZON.State](built-in-slot-state.md) | Reconhece palavras que representam um estado. | Todas as localidades |
| [AMAZÔNIA. StreetName](built-in-slot-street-name.md) | Reconhece palavras que representam o nome de uma rua. | Todas as localidades, exceto inglês (EUA) (en-US) |
| [AMAZON.TIME](built-in-slot-time.md) | Converte palavras que indicam horários em um formato de hora. | Todas as localidades |
| [AMAZÔNIA. WeightUnit](built-in-slot-weight.md) | Converte palavras que representam uma unidade de peso em uma abreviatura padrão | Inglês (EUA) (en-US) |
**nota**
Para a localidade em inglês (EUA) (en-US), o Amazon Lex oferece suporte aos tipos de slots do Alexa Skill Kit. Para obter uma lista de tipos de slot integrados disponíveis, consulte [Referência do tipo de slot](https://developer.amazon.com/docs/custom-skills/slot-type-reference.html) na documentação do Alexa Skills Kit.
O Amazon Lex não oferece suporte ao tipo de slot integrado `AMAZON.LITERAL` ou ao `AMAZON.SearchQuery`.
# AMAZON.Airport
Fornece uma lista de aeroportos. Os exemplos incluem:
+ Aeroporto Internacional John F. Kennedy
+ Aeroporto de Melbourne
# AMAZÔNIA. AlphaNumeric
Reconhece strings compostas de letras e números, como **APQ123**.
Esse tipo de slot não está disponível na localidade coreana (ko-KR).
Você pode usar o tipo de slot `AMAZON.AlphaNumeric` para strings que contenham:
+ Caracteres alfabéticos, como **ABC**
+ Caracteres numéricos, como **123**
+ Uma combinação de caracteres alfanuméricos, como **ABC123**
Você pode adicionar uma expressão regular ao tipo de slot `AMAZON.AlphaNumeric` para validar os valores inseridos para o slot. Por exemplo, é possível usar uma expressão regular para validar:
+ Códigos postais do Reino Unido ou do Canadá
+ Números de carteira de motorista
+ Números de identificação de veículo
Use uma expressão regular padrão. O Amazon Lex suporta os seguintes caracteres na expressão regular:
+ A-Z, a-z
+ 0-9
O Amazon Lex também oferece suporte a caracteres Unicode em expressões regulares. O formato é `\uUnicode`. Use quatro dígitos para representar caracteres Unicode. Por exemplo, `[\u0041-\u005A]` é equivale a [A-Z].
Os seguintes operadores de expressão regular não são aceitos:
+ Repetidores infinitos: \$1, \$1 ou \$1x,\$1 sem limite superior.
+ Curinga (.)
O comprimento máximo da expressão regular é de 300 caracteres. O comprimento máximo de uma string armazenada em uma AMAZON. AlphaNumeric o tipo de slot que usa uma expressão regular é de 30 caracteres.
A seguir estão alguns exemplos de expressões regulares.
+ Strings alfanuméricas, como **APQ123** ou **APQ1**: `[A-Z]{3}[0-9]{1,3}` ou um `[A-DP-T]{3} [1-5]{1,3}` mais restrito
+ Formato internacional de correio prioritário do Serviço Postal dos EUA, como **CP123456789US**: `CP[0-9]{9}US`
+ Números de roteamento bancário, como **123456789**: `[0-9]{9}`
Para definir a expressão regular para um tipo de slot, use o console ou a operação [PutSlotType](API_PutSlotType.md). A expressão regular é validada quando você salva o tipo de slot. Se a expressão não for válida, o Amazon Lex retornará uma mensagem de erro.
Quando você usa uma expressão regular em um tipo de slot, o Amazon Lex verifica a entrada em slots desse tipo em relação à expressão regular. Se a entrada corresponder à expressão, o valor será aceito para o slot. Se a entrada não corresponder, o Amazon Lex solicitará que o usuário repita a entrada.
# AMAZON.City
Fornece uma lista de cidades locais e mundiais. O tipo de slot reconhece variações comuns de nomes de cidades. O Amazon Lex não faz a conversão de uma variação para um nome oficial.
Exemplos:
+ Nova York
+ Reykjavik
+ Tóquio
+ Versalhes
# AMAZON.Country
Os nomes dos países de todo o mundo. Exemplos:
+ Austrália
+ Alemanha
+ Japão
+ Estados Unidos
+ Uruguai
# AMAZON.DATE
Converte palavras que representam datas em um formato de data.
A data é fornecida de acordo com sua intenção no formato de data ISO-8601. A data em que sua intenção é recebida no slot pode variar dependendo da frase específica proferida pelo usuário.
+ Declaraçoes mapeadas para uma data específica, como "hoje", "agora" ou "vinte e cinco de novembro", são convertidas em uma data completa: `2020-11-25`. O padrão é datas iguais *ou posteriores à* data atual.
+ Declarações mapeadas para uma semana específica, como "esta semana" ou "semana que vem", são convertidas na data do primeiro dia da semana. No formato ISO-8601, a semana começa na segunda-feira e termina no domingo. Por exemplo, se hoje for 25/11/2020, a "próxima semana" será convertida em `2020-11-30`.
+ Declarações mapeadas para um mês, mas não para um dia específico, como "próximo mês", são convertidas no último dia do mês. Por exemplo, se hoje for 25/11/2020, o "próximo mês" será convertido em `2020-12-31`.
+ Declarações mapeadas para um ano, mas não para um mês ou dia específico, como "ano que vem", são convertidas no último dia do ano seguinte. Por exemplo, se hoje for 25/11/2020, o "próximo ano" será convertido em `2021-12-31`.
# AMAZON.DURATION
Converte palavras que indicam durações em uma duração numérica.
A duração é resolvida em um formato baseado no formato de duração [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Durations), `PnYnMnWnDTnHnMnS`. O `P` indica que essa é uma duração, `n` é um valor numérico e a letra maiúscula após `n` é o elemento específico de data ou hora. Por exemplo, `P3D` significa 3 dias. O `T` é usado para indicar que os valores restantes representam elementos de tempo em vez de elementos de data.
Exemplos:
+ "dez minutos": `PT10M`
+ "cinco horas": `PT5H`
+ "três dias": `P3D`
+ "quarenta e cinco segundos": `PT45S`
+ "oito semanas": `P8W`
+ "sete anos": `P7Y`
+ "cinco horas e dez minutos": `PT5H10M`
+ "dois anos três horas dez minutos": `P2YT3H10M`
# AMAZÔNIA. EmailAddress
Reconhece palavras que representam um endereço de e-mail fornecido, como nomedeusuário@domínio. Os endereços podem incluir os seguintes caracteres especiais em um nome de usuário: sublinhado (\$1), hífen (-), ponto (.) e o sinal de mais (\$1).
# AMAZÔNIA. FirstName
Nomes próprios comumente usados. Esse tipo de slot reconhece tanto nomes formais quanto apelidos informais. O nome enviado para sua intenção é o valor enviado pelo usuário. O Amazon Lex não converte do apelido para o nome formal.
Para nomes que soam parecidos, mas com grafia diferente, o Amazon Lex envia sua intenção em um único formulário comum.
Na localidade em inglês (EUA) (en-US), use o nome do slot Amazon.US\$1FIRST\$1NAME.
Exemplos:
+ Emily
+ John
+ Sophie
# AMAZÔNIA. LastName
Sobrenomes comumente usados. Para nomes com sons parecidos e escritos de forma diferente, o Amazon Lex envia sua intenção em um único formulário comum.
Na localidade em inglês (EUA) (en-US), use o nome do slot Amazon.US\$1last\$1name.
Exemplos:
+ Brosky
+ Dasher
+ Evers
+ Parres
+ Welt
# AMAZON.NUMBER
Converte palavras ou números que expressam um número em dígitos, incluindo números decimais. A tabela a seguir mostra como o tipo de slot `AMAZON.NUMBER` captura palavras numéricas.
| Input | Resposta |
| --- | --- |
| cento e vinte e três ponto quatro cinco | 123.45 |
| cento e vinte e três ponto quatro cinco | 123.45 |
| ponto quatro dois | 0.42 |
| ponto quarenta e dois | 0.42 |
| 232.998 | 232.998 |
| 50 | 50 |
# AMAZON.Percentage
Converte palavras e símbolos que representam uma porcentagem em um valor numérico com um sinal de porcentagem (%).
Se o usuário inserir um número sem um sinal de porcentagem ou as palavras "por cento", o valor do slot será definido para o número. A tabela a seguir mostra como o tipo de slot `AMAZON.Percentage` captura porcentagens.
| Input | Resposta |
| --- | --- |
| 50% | 50% |
| 0,4% | 0.4% |
| 23,5% | 23,5% |
| vinte e cinco por cento | 25% |
# AMAZÔNIA. PhoneNumber
Converte os números ou as palavras que representam um número de telefone em um formato de string sem a pontuação da seguinte forma.
| Tipo | Description | Input | Resultado |
| --- | --- | --- | --- |
| Número internacional com sinal de mais (\$1) no começo | Número de 11 dígitos com sinal de mais no começo. | \$161 7 4445 1061 1 (509) 555-1212 | `+61744431061` `+15095551212` |
| Número internacional sem sinal de mais (\$1) no começo | Número de 11 dígitos sem sinal de mais no começo | 1 (509) 555-1212 61 7 4445 1061 | `15095551212` `61744451061` |
| Número nacional | Número de 10 dígitos sem código internacional | (03) 5115 4444 (509) 555-1212 | `0351154444` `5095551212` |
| Número local | Número de 7 dígitos sem código internacional ou código de área | 555-1212 | 5551212 |
# AMAZÔNIA. SpeedUnit
Converte palavras que representam unidades de velocidade na abreviatura correspondente. Por exemplo, "milhas por hora" é convertido em `mph`.
Esse tipo de slot está disponível somente na localidade em inglês (EUA) (en-US).
Os exemplos a seguir mostram como o tipo de slot `AMAZON.SpeedUnit` captura unidades de velocidade.
| Unidade de velocidade | Abreviação |
| --- | --- |
| milhas por hora, mph, MPH, m/h | mph |
| quilômetros por hora, km por hora, kmph, KMPH, km/h | kmph |
| metros por segundo, mps, MPS, m/s | mps |
| milhas náuticas por hora, nós, nó | nó |
# AMAZON.State
Os nomes das regiões geográficas e políticas dos países.
Exemplos:
+ Baviera
+ Prefeitura de Fukushima
+ Noroeste do Pacífico
+ Queensland
+ Gales
# AMAZÔNIA. StreetName
Os nomes das ruas dentro de um endereço típico. Isso inclui apenas o nome da rua, não o número da casa.
Esse tipo de slot não está disponível na localidade em inglês (EUA) (en-US).
Exemplos:
+ Avenida Canberra
+ Rua da frente
+ Estrada do Mercado
# AMAZON.TIME
Converte palavras que representam horários em valores de hora. Inclui resoluções para tempos ambíguos. Quando o usuário insere um horário ambíguo, o Amazon Lex usa o atributo `slotDetails` de um evento do Lambda para passar resoluções para horários ambíguos à função do Lambda. Por exemplo, se seu bot solicitar um horário de entrega, o usuário poderá responder: "10 horas". Esse horário é ambíguo. Pode ser 10h ou 22h. Nesse caso, o valor no mapa `slots` é `null`, e a entidade `slotDetails` contém as duas possíveis resoluções de horário. O Amazon Lex insere o seguinte na função do Lambda.
```
"slots": {
"deliveryTime": null
},
"slotDetails": {
"deliveryTime": {
"resolutions": [
{
"value": "10:00"
},
{
"value": "22:00"
}
]
}
}
```
Quando o usuário responde com um horário não ambíguo, o Amazon Lex envia o horário para a função do Lambda no atributo `slots` do evento do Lambda, e o atributo `slotDetails` fica vazio. Por exemplo, se o usuário responder ao prompt para um horário de entrega com "10:00 PM (22h)", o Amazon Lex inserirá o seguinte na função do Lambda:
```
"slots": {
"deliveryTime": "22:00"
}
```
Para obter mais informações sobre os dados enviados do Amazon Lex para uma função do Lambda, consulte [Formato de eventos de entrada](lambda-input-response-format.md#using-lambda-input-event-format).
# AMAZÔNIA. WeightUnit
Converte palavras que representam uma unidade de peso na abreviatura correspondente. Por exemplo, "quilograma" é convertido para `kg`.
Esse tipo de slot está disponível somente na localidade em inglês (EUA) (en-US).
Os exemplos a seguir mostram como o tipo de slot `AMAZON.WeightUnit` captura unidades de peso:
| Unidade de peso | Abreviação |
| --- | --- |
| quilogramas, quilos, kg, KG | kg |
| gramas, g, g, G, g | g |
| miligramas, mg, mg | mg |
| libras, lb, LB | lb |
| onças, oz, OZ | oz |
| tonelada, tonelada, t | t |
| quilotonelada, kt | kt |
# Tipos de slot personalizados
Para cada intenção, você pode especificar parâmetros que indicam as informações de que a intenção precisa para atender a solicitação do usuário. Esses parâmetros ou slots têm um tipo. Um *tipo de slot* é uma lista de valores que o Amazon Lex usa para treinar o modelo de machine learning para reconhecer os valores de um slot. Por exemplo, você pode definir um tipo de slot chamado "`Genres.`" Cada valor no tipo de slot é o nome de um gênero, "comédia", "aventura", "documentário", etc. Você pode definir um sinônimo para um valor de tipo de slot. Por exemplo, você pode definir os sinônimos "engraçado" e "humor" para o valor "comédia".
Você pode configurar o tipo de slot para restringir a resolução aos valores do slot. Os valores do slot serão usados como uma enumeração e o valor inserido pelo usuário será resolvido para o slot valor somente se ele for o mesmo que um dos valores de slot ou um sinônimo. Um sinônimo é resolvido para o valor de slot correspondente. Por exemplo, se o usuário inserir "engraçado", isso será definido como o valor do slot "comédia".
Como alternativa, você pode configurar o tipo de slot para expandir os valores. Os valores do slot serão usados como dados de treinamento e o slot será resolvido para o valor fornecido pelo usuário se ele for semelhante aos valores e sinônimos do slot. Esse é o comportamento padrão.
O Amazon Lex mantém uma lista de possíveis resoluções para um slot. Cada entrada na lista fornece um *valor de resolução* que o Amazon Lex reconhece como possibilidades adicionais para o slot. Um valor de resolução é o melhor esforço para corresponder ao valor do slot. A lista contém até cinco valores.
Quando o valor inserido pelo usuário é um sinônimo, a primeira entrada na lista de valores de resolução é o valor do tipo do slot. Por exemplo, se o usuário insere "engraçado", o campo `slots` contém "engraçado" e a primeira entrada no campo `slotDetails` é "comédia". Você pode configurar o `valueSelectionStrategy` quando cria ou atualiza um tipo de slot com a operação [PutSlotType](API_PutSlotType.md) para que o valor do slot seja preenchido com o primeiro valor na lista de resolução.
Se você estiver usando uma função do Lambda, o evento de entrada para a função incluirá uma lista de resoluções chamada `slotDetails`. O exemplo a seguir mostra o slot e a seção de detalhes do slot da entrada para uma função do Lambda:
```
"slots": {
"MovieGenre": "funny";
},
"slotDetails": {
"Movie": {
"resolutions": [
"value": "comedy"
]
}
}
```
Para cada tipo de slot, você pode definir um máximo de 10.000 valores e sinônimos. Cada bot pode ter um número total de 50.000 valores e sinônimos do tipo de slots. Por exemplo, você pode ter cinco tipos de slot, cada um com 5.000 valores e 5.000 sinônimos ou pode ter 10 tipos de slot, cada um com 2.500 valores e 2.500 sinônimos. Se exceder esses limites, você receberá um `LimitExceededException` quando chamar a operação [PutBot](API_PutBot.md).
# Ofuscação de slot
O Amazon Lex permite ofuscar ou ocultar o conteúdo dos slots para que não fique visível. Para proteger dados confidenciais capturados como valores de slot, é possível ativar a ofuscação de slot para mascarar esses valores para os logs de conversa.
Ao optar por ofuscar valores de slot, o Amazon Lex substitui o valor de slot pelo nome do slot nos logs de conversa. Para um slot chamado `full_name`, o valor do slot seria ofuscado da seguinte forma:
```
Before obfuscation:
My name is John Stiles
After obfuscation:
My name is {full_name}
```
Se uma declaração contiver caracteres de colchete (\$1\$1), o Amazon Lex insere um caractere de escape nos caracteres de colchete com duas barras invertidas (\$1\$1). Por exemplo, o texto `{John Stiles}` é ofuscado da seguinte forma:
```
Before obfuscation:
My name is {John Stiles}
After obfuscation:
My name is \\{{full_name}\\}
```
Os valores de slot são ofuscados nos logs de conversa. Os valores de slot ainda estão disponíveis na resposta das operações `PostContent` e `PostText`, e os valores de slot estão disponíveis para suas funções do Lambda de validação e atendimento. Se você estiver usando valores de slot em seus prompts ou respostas, eles não serão ofuscados nos logs de conversa.
No primeiro turno de uma conversa, o Amazon Lex ofuscará valores de slot se ele reconhecer um slot e um valor de slot na declaração. Se nenhum valor de slot for reconhecido, o Amazon Lex não ofuscará a declaração.
No segundo turno e nos posteriores, o Amazon Lex sabe qual slot elicitar e se o valor de slot deve ser ofuscado. Se o Amazon Lex reconhecer o valor de slot, o valor será ofuscado. Se o Amazon Lex não reconhecer um valor, toda a declaração será ofuscada. Nenhum valor de slot em declarações perdidas será ofuscado.
O Amazon Lex também não ofusca valores de slot armazenados em atributos de solicitação ou sessão. Se você estiver armazenando valores de slot que devem ser ofuscados como um atributo, deverá criptografar ou ofuscar o valor.
O Amazon Lex não ofusca o valor de slot no áudio. Ele ofusca o valor de slot na transcrição de áudio.
Não é necessário ofuscar todos os slots em um bot. Você pode escolher quais slots ofuscar usando o console ou a API do Amazon Lex. No console, escolha **Ofuscação de slot** nas configurações de um slot. Se você estiver usando a API, defina o campo `obfuscationSetting` do slot como `DEFAULT_OBFUSCATION` ao chamar a operação [PutIntent](API_PutIntent.md).
# Análise de sentimento
É possível usar a análise de sentimento para determinar os sentimentos expressos em uma declaração do usuário. Com as informações de sentimento, é possível gerenciar o fluxo da conversa ou realizar a análise pós-chamada. Por exemplo, se o sentimento do usuário for negativo, você pode criar um fluxo para passar uma conversa a um atendente humano.
O Amazon Lex integra-se ao Amazon Comprehend para detectar o sentimento do usuário. A resposta do Amazon Comprehend indica se o sentimento geral do texto é positivo, neutro, negativo ou misto. A resposta contém o sentimento mais provável da declaração do usuário e as pontuações para cada uma das categorias de sentimento. A pontuação representa a probabilidade de o sentimento ter sido detectado corretamente.
Ative a análise de sentimento para um bot usando o console ou usando a API do Amazon Lex. No console do Amazon Lex, selecione a guia **Configurações** do bot e defina a opção **Análise de Sentimento** como **Sim**. Se você estiver usando a API, chame a operação [PutBot](API_PutBot.md) com o campo `detectSentiment` definido como `true`.
Quando a análise de sentimento está ativada, a resposta das operações [PostContent](API_runtime_PostContent.md) e [PostText](API_runtime_PostText.md) retorna um campo chamado `sentimentResponse` na resposta do bot com outros metadados. O campo `sentimentResponse` tem dois campos, `SentimentLabel` e `SentimentScore`, que contêm o resultado da análise de sentimento. Se você estiver usando uma função do Lambda, o campo `sentimentResponse` será incluído nos dados do evento enviados para a função.
Veja a seguir um exemplo do campo `sentimentResponse` retornado como parte da resposta `PostText` ou `PostContent`. O campo `SentimentScore` é uma string que contém as pontuações para a resposta.
```
{
"SentimentScore":
"{
Mixed: 0.030585512690246105,
Positive: 0.94992071056365967,
Neutral: 0.0141543131828308,
Negative: 0.00893945890665054
}",
"SentimentLabel": "POSITIVE"
}
```
O Amazon Lex chama o Amazon Comprehend em seu nome para determinar o sentimento em cada declaração processada pelo bot. Ao ativar a análise de sentimento, você concorda com os termos e acordos de serviço do Amazon Comprehend. Para obter mais informações sobre a definição de preço do Amazon Comprehend, consulte [Definição de preço do Amazon Comprehend](https://aws.amazon.com/comprehend/pricing/).
Para obter mais informações sobre como funciona a análise de sentimento do Amazon Comprehend, consulte [Determinar o sentimento](https://docs.aws.amazon.com/comprehend/latest/dg/how-sentiment.html) no *Guia do desenvolvedor do Amazon Comprehend*.
# Marcação de seus recursos do Amazon Lex
Para ajudar você a gerenciar os aliases de bot, canais de bot e bots do Amazon Lex, é possível atribuir metadados a cada recurso como *tags.* Uma tag é um rótulo que você atribui a um AWS recurso. Cada tag consiste em uma chave e um valor.
As tags permitem categorizar seus recursos da AWS de diferentes formas, por exemplo, por finalidade, proprietário ou aplicativo. As tags ajudam a:
+ Identifique e organize seus AWS recursos. Muitos AWS recursos oferecem suporte à marcação, então você pode atribuir a mesma tag a recursos em serviços diferentes para indicar que os recursos estão relacionados. Por exemplo, é possível marcar um bot e as funções do Lambda que ele usa com a mesma tag.
+ Alocar custos. Você ativa as tags no Gerenciamento de Faturamento e Custos da AWS painel. AWS usa as tags para categorizar seus custos e entregar um relatório mensal de alocação de custos para você. Para o Amazon Lex, é possível alocar custos para cada alias usando tags específicas para o alias, exceto para o alias `$LATEST`. Aloque custos para o alias `$LATEST` usando tags para o bot do Amazon Lex. Para obter mais informações, consulte [ Usar tags de alocação de custos ](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) no *Guia do usuário do Gerenciamento de Faturamento e Custos da AWS *.
+ Controle o acesso aos seus recursos. É possível usar tags no Amazon Lex para criar políticas para controlar o acesso aos recursos do Amazon Lex. Essas políticas podem ser anexadas a um perfil do IAM ou um usuário para habilitar o controle de acesso baseado em tags. Para obter mais informações, consulte [ABAC com o Amazon Lex](security_iam_service-with-iam.md#security_iam_service-with-iam-tags). Para visualizar um exemplo de política baseada em identidade para limitar o acesso a um recurso baseado em tags desse recurso, consulte [Uso de uma tag para acessar um recurso](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-tag).
Você pode trabalhar com tags usando a Console de gerenciamento da AWS AWS Command Line Interface, a ou a API Amazon Lex.
## Marcação de recursos
Se estiver usando o console do Amazon Lex, é possível marcar recursos ao criá-los ou adicionar as tags mais tarde. Também é possível usar o console para atualizar ou remover tags existentes.
Se você estiver usando a API AWS CLI ou a Amazon Lex API, você usa as seguintes operações para gerenciar tags para seus recursos:
+ [ListTagsForResource](API_ListTagsForResource.md): visualizar as tags associadas a um recurso.
+ [PutBot](API_PutBot.md) e [PutBotAlias](API_PutBotAlias.md): aplicar as tags ao criar um bot ou alias de bot.
+ [TagResource](API_TagResource.md): adicionar e modificar tags em um recurso existente.
+ [UntagResource](API_UntagResource.md): remover as tags de um recurso.
Os seguintes recursos do Amazon Lex são compatíveis com a marcação:
+ Bots: use um nome do recurso da Amazon (ARN) como o seguinte:
+ `arn:${partition}:lex:${region}:${account}:bot:${bot-name}`
+ Aliases de bot – use um ARN como o seguinte:
+ `arn:${partition}:lex:${region}:${account}:bot:${bot-name}:${bot-alias}`
+ Canais de bot – use um ARN como o seguinte:
+ `arn:${partition}:lex:${region}:${account}:bot-channel:${bot-name}:${bot-alias}:${channel-name}`
## Restrições de tag
As restrições básicas a seguir aplicam-se às tags nos recursos do Amazon Lex:
+ Número máximo de tags – 50
+ Tamanho máximo da chave: 128 caracteres
+ Tamanho máximo do valor: 256 caracteres
+ Caracteres válidos de chave e valor: a–z, A–Z, 0–9, espaço, e os seguintes caracteres: \$1 . : / = \$1 - e @
+ As chaves e os valores diferenciam letras maiúsculas de minúsculas.
+ Não use `aws:` como prefixo para chaves, pois ele é reservado para uso da AWS.
# Marcação de recursos (console)
É possível usar o console para gerenciar tags em um bot, alias de bot ou recurso de canal de bot. É possível adicionar tags ao criar um recurso ou adicionar, modificar ou remover tags de recursos existentes.
**Como adicionar uma tag ao criar um bot**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha **Criar** para criar um novo bot.
1. Na parte inferior da página **Criar seu bot**, escolha **Tags**.
1. Escolha **Adicionar tag** e adicione uma ou mais tags ao bot. É possível adicionar até 50 tags.
**Como adicionar uma tag ao criar um alias de bot**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha o bot ao qual você deseja adicionar o alias de bot.
1. Escolha **Configurações**.
1. Adicione o nome do alias, escolha a versão do bot e escolha **Adicionar tags**.
1. Escolha **Adicionar tag** e adicione uma ou mais tags ao alias de bot. É possível adicionar até 50 tags.
**Como adicionar uma tag ao criar um canal de bot**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha o bot ao qual você deseja adicionar o canal de bot.
1. Escolha **Canais** e escolha o canal que deseja adicionar.
1. Adicione os detalhes do canal de bot e escolha **Tags**.
1. Escolha **Adicionar tag** e adicione uma ou mais tags ao canal de bot. É possível adicionar até 50 tags.
**Como adicionar uma tag ao importar um bot**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. Escolha **Ações** e **Importar**.
1. Escolha o arquivo zip para importar o bot.
1. Escolha **Tags** e escolha **Adicionar Tags** para adicionar uma ou mais tags ao bot. É possível adicionar até 50 tags.
**Como adicionar, remover ou modificar uma tag em um bot existente**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. No menu esquerdo, escolha **Bots** e escolha o bot que deseja modificar.
1. Escolha **Configurações** e, no menu esquerdo, escolha **Geral**.
1. Escolha **Tags** e adicione, modifique ou remova tags para o bot.
**Como adicionar, remover ou modificar uma tag em um alias de bot**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. No menu esquerdo, escolha **Bots** e escolha o bot que deseja modificar.
1. Escolha **Configurações** e, no menu esquerdo, escolha **Aliases**.
1. Escolha **Gerenciar tags** para o alias que você deseja modificar e adicione, modifique ou remova tags para o alias de bot.
**Como adicionar, remover ou modificar uma tag em um canal de bot existente**
1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon Lex em [https://console.aws.amazon.com/lex/](https://console.aws.amazon.com/lex/).
1. No menu esquerdo, escolha **Bots** e escolha o bot que deseja modificar.
1. Escolha **Canais**.
1. Escolha **Tags** e adicione, modifique ou remova tags para o canal de bot.
# Marcação de recursos (AWS CLI)
Você pode usar o AWS CLI para gerenciar tags em um bot, um alias de bot ou um recurso de canal de bot. É possível adicionar tags ao criar um bot ou um alias de bot ou adicionar, modificar ou remover tags de um bot, alias de bot ou canal de bot.
Todos os exemplos são formatados para Linux e macOS. Para usar o comando no Windows, substitua o caractere de continuação do Linux (\$1) por um acento circunflexo (^).
**Como adicionar uma tag ao criar um bot**
+ O `put-bot` AWS CLI comando abreviado a seguir mostra os parâmetros que você deve usar para adicionar uma tag ao criar um bot. Para realmente criar um bot, é necessário fornecer outros parâmetros. Para obter mais informações, consulte [Etapa 4: Conceitos básicos (AWS CLI)](gs-cli.md).
```
aws lex-models put-bot \
--tags '[{"key": "key1", "value": "value1"}, \
{"key": "key2", "value": "value2"}]'
```
**Como adicionar uma tag ao criar um alias de bot**
+ O `put-bot-alias` AWS CLI comando abreviado a seguir mostra os parâmetros que você deve usar para adicionar uma tag ao criar um alias de bot. Para criar um alias de bot, é necessário fornecer outros parâmetros. Para obter mais informações, consulte [Exercício 5: Criar um alias (AWS CLI)](gs-cli-create-alias.md).
```
aws lex-models put-bot \
--tags '[{"key": "key1", "value": "value1"}, \
{"key": "key2", "value": "value2"}]"
```
**Como listar as tags em um recurso**
+ Use o `list-tags-for-resource` AWS CLI comando para mostrar os recursos associados a um bot, alias de bot e canal de bot.
```
aws lex-models list-tags-for-resource \
--resource-arn bot, bot alias, or bot channel ARN
```
**Como adicionar ou modificar as tags em um recurso**
+ Use o `tag-resource` AWS CLI comando para adicionar ou modificar um bot, um alias de bot ou um canal de bot.
```
aws lex-models tag-resource \
--resource-arn bot, bot alias, or bot channel ARN \
--tags '[{"key": "key1", "value": "value1"}, \
{"key": "key2", "value": "value2"}]'
```
**Como remover as tags de um recurso**
+ Use o `untag-resource` AWS CLI comando para remover tags de um bot, alias de bot ou canal de bot.
```
aws lex-models untag-resource \
--resource-arn bot, bot alias, or bot channel ARN \
--tag-keys '["key1", "key2"]'
```