Sintaxe da Solicitação Parâmetros da Solicitação de URI Corpo da Solicitação Sintaxe da Resposta Elementos de Resposta Erros Consulte Também

PostText

Envia a entrada do usuário ao Amazon Lex. Os aplicativos clientes podem usar essa API para enviar solicitações ao Amazon Lex em runtime. Em seguida, o Amazon Lex interpreta a entrada do usuário usando o modelo de machine learning criado para o bot.

Em resposta, o Amazon Lex retorna a próxima message para transmitir um responseCard opcional ao usuário para exibir. Considere as seguintes mensagens de exemplo:

Para uma entrada do usuário “Eu gostaria de uma pizza”, o Amazon Lex pode retornar uma resposta com uma mensagem gerando dados do slot (por exemplo, PizzaSize): “Qual tamanho de pizza você gostaria?”
Depois que o usuário fornece todas as informações do pedido de pizza, o Amazon Lex pode retornar uma resposta com uma mensagem para obter a confirmação do usuário: “Continuar com o pedido de pizza?”.
Depois que o usuário responder o prompt de confirmação com “Sim”, o Amazon Lex poderá retornar uma declaração de conclusão: “Obrigado, sua pizza de queijo foi pedida.”.

Nem todas as mensagens do Amazon Lex exigem uma resposta do usuário. Por exemplo, uma declaração de conclusão não exige uma resposta. Algumas mensagens exigem apenas uma resposta “sim” ou “não” do usuário. Além do message, o Amazon Lex fornece contexto adicional sobre a mensagem na resposta que você pode usar para aprimorar o comportamento do cliente, por exemplo, para exibir a interface de usuário apropriada do cliente. Esses são os campos slotToElicit, dialogState, intentName e slots na resposta. Considere os seguintes exemplos:

Se a mensagem for para obter dados de slots, o Amazon Lex retornará as seguintes informações de contexto:
- dialogStatedefinido como ElicitSlot
- intentName definido como o nome da intenção no contexto atual
- slotToElicit definido como o nome do slot para o qual message está obtendo informações
- slots definido como um mapa de slots configurados para a intenção com valores atuais conhecidos
Se a mensagem for um prompt de confirmação, o dialogState será definido como ConfirmIntent e SlotToElicit definido como nulo.
Se a mensagem for um prompt de esclarecimento (configurado para a intenção) que indica que a intenção do usuário não foi compreendida, a dialogState é definida como ElicitIntent e definida como slotToElicit nula.

Além disso, o Amazon Lex também retorna seu aplicativo específicosessionAttributes. Para obter mais informações, consulte Gerenciar o contexto de conversação.

Sintaxe da Solicitação


POST /bot/botName/alias/botAlias/user/userId/text HTTP/1.1
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "inputText": "string",
   "requestAttributes": { 
      "string" : "string" 
   },
   "sessionAttributes": { 
      "string" : "string" 
   }
}

Parâmetros da Solicitação de URI

A solicitação usa os seguintes parâmetros de URI:

botAlias

O alias do bot do Amazon Lex.

Obrigatório: Sim

botName

O nome do bot do Amazon Lex.

Obrigatório: Sim

userId

O ID do usuário do aplicativo cliente. O Amazon Lex usa isso para identificar a conversa de um usuário com seu bot. No runtime, cada solicitação deve conter o campo userID.

Para decidir o ID de usuário a ser usado em seu aplicativo, considere os seguintes fatores.

O campo userID não deve conter nenhuma informação de identificação pessoal do usuário, por exemplo, nome, números de identificação pessoal ou outras informações pessoais do usuário final.
Se você quiser que um usuário inicie uma conversa em um dispositivo e continue em outro, use um identificador específico do usuário.
Se você quiser que o mesmo usuário possa ter duas conversas independentes em dois dispositivos diferentes, escolha um identificador específico do dispositivo.
Um usuário não pode ter duas conversas independentes com duas versões diferentes do mesmo bot. Por exemplo, um usuário não pode conversar com as versões PROD e BETA do mesmo bot. Se você prevê que um usuário precisará conversar com duas versões diferentes, por exemplo, durante o teste, inclua o alias do bot no ID do usuário para separar as duas conversas.

Restrições de tamanho: tamanho mínimo 2. Comprimento máximo de 100.

Padrão: [0-9a-zA-Z._:-]+

Exigido: Sim

Corpo da Solicitação

A solicitação aceita os dados a seguir no formato JSON.

activeContexts

Uma lista de contextos ativos para a solicitação. Um contexto pode ser ativado quando uma intenção anterior é atendida ou incluindo o contexto na solicitação,

Se você não especificar uma lista de contextos, o Amazon Lex usará a lista atual de contextos para a sessão. Se você especificar uma lista vazia, todos os contextos da sessão serão apagados.

Tipo: matriz de objetos ActiveContext

Membros da Matriz: número mínimo de 0 itens. Número máximo de 20 itens.

Obrigatório: não

inputText

O texto que o usuário inseriu (o Amazon Lex interpreta esse texto).

Ao usar a AWS CLI, você não pode passar uma URL no parâmetro --input-text. Em vez disso, passe o URL usando o parâmetro --cli-input-json.

Tipo: String

Restrições de tamanho: tamanho mínimo 1. Tamanho máximo de 1.024.

Obrigatório: Sim

requestAttributes

Informações específicas da solicitação passadas entre o Amazon Lex e um aplicativo cliente.

O namespace x-amz-lex: é reservado para atributos especiais. Não crie atributos de solicitação com o prefixo x-amz-lex:.

Para obter mais informações, consulte Definição de atributos de solicitação.

Tipo: mapa de string para string

Obrigatório: não

sessionAttributes

Informações específicas do aplicativo passadas entre o Amazon Lex e um aplicativo cliente.

Para obter mais informações, consulte Definição de atributos de sessão.

Tipo: mapa de string para string

Obrigatório: Não

Sintaxe da Resposta


HTTP/1.1 200
Content-type: application/json

{
   "activeContexts": [ 
      { 
         "name": "string",
         "parameters": { 
            "string" : "string" 
         },
         "timeToLive": { 
            "timeToLiveInSeconds": number,
            "turnsToLive": number
         }
      }
   ],
   "alternativeIntents": [ 
      { 
         "intentName": "string",
         "nluIntentConfidence": { 
            "score": number
         },
         "slots": { 
            "string" : "string" 
         }
      }
   ],
   "botVersion": "string",
   "dialogState": "string",
   "intentName": "string",
   "message": "string",
   "messageFormat": "string",
   "nluIntentConfidence": { 
      "score": number
   },
   "responseCard": { 
      "contentType": "string",
      "genericAttachments": [ 
         { 
            "attachmentLinkUrl": "string",
            "buttons": [ 
               { 
                  "text": "string",
                  "value": "string"
               }
            ],
            "imageUrl": "string",
            "subTitle": "string",
            "title": "string"
         }
      ],
      "version": "string"
   },
   "sentimentResponse": { 
      "sentimentLabel": "string",
      "sentimentScore": "string"
   },
   "sessionAttributes": { 
      "string" : "string" 
   },
   "sessionId": "string",
   "slots": { 
      "string" : "string" 
   },
   "slotToElicit": "string"
}

Elementos de Resposta

Se a ação tiver êxito, o serviço enviará de volta uma resposta HTTP 200.

Os dados a seguir são retornados no formato JSON pelo serviço.

activeContexts

Uma lista de contextos ativos para a sessão. Um contexto pode ser definido quando uma intenção é cumprida ou chamando a operação PostContent, PostText ou PutSession.

Você pode usar um contexto para controlar as intenções que podem acompanhar uma intenção ou para modificar a operação do seu aplicativo.

Tipo: matriz de objetos ActiveContext

Membros da Matriz: número mínimo de 0 itens. Número máximo de 20 itens.

alternativeIntents

Uma a quatro intenções alternativas que podem ser aplicáveis à intenção do usuário.

Cada alternativa inclui uma pontuação que indica o grau de confiança do Amazon Lex de que a intenção corresponde à intenção do usuário. As intenções são classificadas pela pontuação de confiança.

Tipo: matriz de objetos PredictedIntent

Membros da matriz: número máximo de seis itens.

botVersion

A versão do bot que respondeu à conversa. Você pode usar essas informações para ajudar a determinar se uma versão de um bot tem um desempenho melhor do que outra versão.

Tipo: String

Restrições de tamanho: tamanho mínimo 1. Comprimento máximo de 64.

Padrão: [0-9]+|\$LATEST

dialogState

Identifica o estado atual da interação do usuário. O Amazon Lex retorna um dos seguintes valores como dialogState. Opcionalmente, o cliente pode usar essas informações para personalizar a interface do usuário.

ElicitIntent - O Amazon Lex quer obter a intenção do usuário.

Por exemplo, um usuário pode expressar uma intenção (“Quero pedir uma pizza”). Se o Amazon Lex não puder deduzir a intenção do usuário a partir desse enunciado, ele retornará esse dialogState.
ConfirmIntent - O Amazon Lex espera uma resposta “sim” ou “não”.

Por exemplo, o Amazon Lex quer a confirmação do usuário antes de atender uma intenção.

Em vez de um “sim” ou “não”, um usuário pode responder com informações adicionais. Por exemplo, “sim, mas peça uma pizza de massa grossa” ou “não, quero pedir uma bebida”. O Amazon Lex pode processar essas informações adicionais (nesses exemplos, atualizar o valor do slot do tipo de crosta ou alterar a intenção de OrderPizza para OrderDrink).
ElicitSlot - O Amazon Lex espera um valor de slot para a intenção atual.

Por exemplo, suponha que, na resposta, o Amazon Lex envie esta mensagem: “Qual tamanho de pizza você gostaria?”. Um usuário pode responder com o valor do slot (por exemplo, “média”). O usuário também pode fornecer informações adicionais na resposta (por exemplo, “pizza média de massa grossa”). O Amazon Lex pode processar essas informações adicionais de forma adequada.
Fulfilled - Transmite que a função do Lambda configurada para a intenção atendeu com sucesso a intenção.
ReadyForFulfillment - Transmite que o cliente deve atender à solicitação.
Failed - Transmite que a conversa com o usuário falhou.

Isso pode acontecer por vários motivos, incluindo o fato de o usuário não ter fornecido uma resposta adequada aos prompts do serviço (você pode configurar quantas vezes o Amazon Lex pode solicitar informações específicas a um usuário) ou se a função do Lambda não atendeu à intenção.

Tipo: String

intentName

A intenção atual do usuário que o Amazon Lex conhece.

Tipo: String

message

A mensagem a ser transmitida ao usuário. A mensagem pode vir da configuração do bot ou de uma função do Lambda.

Se a intenção não estiver configurada com uma função do Lambda, ou se a função do Lambda tiver retornado Delegate como dialogAction.type em sua resposta, o Amazon Lex decide o próximo curso de ação e seleciona uma mensagem apropriada da configuração do bot com base no contexto de interação atual. Por exemplo, se o Amazon Lex não conseguir entender a entrada do usuário, ele usa uma mensagem de prompt de esclarecimento.

Ao criar uma intenção, você pode atribuir mensagens a grupos. Quando as mensagens são atribuídas a grupos, o Amazon Lex retorna uma mensagem de cada grupo na resposta. O campo de mensagem é uma string JSON de escape que contém as mensagens. Para obter mais informações sobre a estrutura da string JSON retornada, consulte Formatos de mensagem suportados.

Se a função do Lambda retornar uma mensagem, o Amazon Lex a enviará para o cliente em sua resposta.

Tipo: String

Restrições de tamanho: tamanho mínimo 1. Tamanho máximo de 1.024.

messageFormat

O formato da mensagem de resposta. Um dos seguintes valores:

PlainText - A mensagem contém texto sem formatação UTF-8.
CustomPayload - A mensagem é um formato personalizado definido pela função do Lambda.
SSML - A mensagem contém texto formatado para saída de voz.
Composite - A mensagem contém um objeto JSON de escape que contém uma ou mais mensagens dos grupos aos quais as mensagens foram atribuídas quando a intenção foi criada.

Tipo: String

Valores Válidos: PlainText | CustomPayload | SSML | Composite

nluIntentConfidence

Fornece uma pontuação que indica o quanto o Amazon Lex tem certeza de que a intenção retornada é aquela que corresponde à intenção do usuário. A pontuação está entre 0,0 e 1,0. Para obter mais informações, consulte Pontuações de confiança.

A pontuação é relativa, não absoluta. A pontuação pode mudar com base nas melhorias no Amazon Lex.

Tipo: objeto IntentConfidence

responseCard

Representa as opções que o usuário tem para responder ao prompt atual. O cartão de resposta pode vir da configuração do bot (no console Amazon Lex, escolha o botão de configurações ao lado de um slot) ou de um hook de código (função do Lambda).

Tipo: objeto ResponseCard

sentimentResponse

O sentimento expresso em um enunciado.

Quando o bot está configurado para enviar declarações ao Amazon Comprehend para análise de sentimentos, esse campo contém o resultado da análise.

Tipo: objeto SentimentResponse

sessionAttributes

Um mapa de pares de chaves/valores que representam as informações de contexto específicas da sessão.

Tipo: mapa de string para string

sessionId

Um identificador exclusivo da sessão.

Tipo: String

slots

Os slots de intenção que o Amazon Lex detectou a partir da entrada do usuário na conversa.

O Amazon Lex cria uma lista de resolução que contém valores prováveis para um slot. O valor que ele retorna é determinado pelo valueSelectionStrategy selecionado quando o tipo de slot foi criado ou atualizado. Se valueSelectionStrategy for definido como ORIGINAL_VALUE, o valor fornecido pelo usuário será retornado, se o valor do usuário for semelhante ao valor do slot. Se valueSelectionStrategy estiver definido como TOP_RESOLUTION, o Amazon Lex retornará o primeiro valor na lista de resolução ou, se não houver lista de resolução, nulo. Se valueSelectionStrategy não for especificado, o padrão será ORIGINAL_VALUE.

Tipo: mapa de string para string

slotToElicit

Se o valor dialogState for ElicitSlot, retornará o nome do slot para o qual o Amazon Lex está obtendo um valor.

Tipo: string

Erros

BadGatewayException

Ou o bot do Amazon Lex ainda está sendo construído ou um dos serviços dependentes (Amazon Polly, AWS Lambda) falhou com um erro interno de serviço.

Código de status HTTP: 502

BadRequestException

A validação da solicitação falhou, não há mensagem utilizável no contexto ou a compilação do bot falhou, ainda está em andamento ou contém alterações não criadas.

Código de Status HTTP: 400

ConflictException

Dois clientes estão usando a mesma conta da AWS, o bot do Amazon Lex e o mesmo ID de usuário.

Código de Status HTTP: 409

DependencyFailedException

Uma das dependências, como AWS Lambda ou Amazon Polly, gerou uma exceção. Por exemplo,

Se o Amazon Lex não tiver permissões suficientes para chamar uma função do Lambda.
Se uma função do Lambda levar mais de 30 segundos para ser executada.
Se uma função do Lambda de atendimento retornar uma ação Delegate de diálogo sem remover nenhum valor de slot.

Código de status HTTP: 424

InternalFailureException

Erro de serviço interno. Tente a chamada novamente.

Código de Status HTTP: 500

LimitExceededException

Excedeu um limite.

Código de Status HTTP: 429

LoopDetectedException

Essa exceção não é usada.

Código de status HTTP: 508

NotFoundException

O atributo (como o bot Amazon Lex ou um alias) mencionado não foi encontrado.

Código de Status HTTP: 404

Consulte Também

Para obter mais informações sobre como usar essa API em um dos AWS SDKs específicos da linguagem, consulte o seguinte:

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

PostContent

PutSession