StartBotConversation

La acción StartBotConversation establece una conversación de voz entre un usuario final y su bot de Amazon Lex v2. El usuario proporciona la información requerida al bot. A continuación, el bot devuelve la información a la función de Lambda de audio de la red telefónica pública conmutada (PSTN) y la función realiza las tareas solicitadas.

Por ejemplo, el bot puede reproducir un mensaje de bienvenida opcional al inicio de una conversación para describir brevemente la tarea que puede realizar la función de Lambda de audio PSTN. La conversación va y viene entre el usuario y el bot hasta que el bot recopila la información requerida. Una vez finalizada la conversación, Amazon Chime SDK invoca la función de Lambda de audio PSTN con un evento de acción exitosa, que contiene la información recopilada por el bot. La función de Lambda de audio PSTN procesa la información y realiza la tarea solicitada.

El servicio de audio proporciona una interacción conversacional realista con sus usuarios. Por ejemplo, los usuarios pueden interrumpir el bot y responder a una pregunta antes de que finalice el mensaje de audio. Además, los usuarios pueden usar cualquier combinación de dígitos de voz y DTMF para proporcionar información. El bot espera a que el usuario introduzca información antes de responder. Puede configurar cuánto tiempo espera el bot a que el usuario termine de hablar antes de interpretar cualquier entrada de voz. El usuario también puede indicar al bot que espere si necesita tiempo para recuperar información adicional durante una llamada, como números de tarjetas de crédito.

La acción StartBotConversation utiliza Amazon Lex y Amazon Polly durante la conversación del bot. Se aplican los costos estándar de Amazon Lex y Amazon Polly. Para obtener más información sobre los precios, consulte las páginas de precios de las conversaciones en transmisión de Amazon Lex y de precios de Amazon Polly.

nota

No puede ejecutar esta acción en una llamada puente ni en una llamada que se haya unido a una reunión de Amazon Chime SDK.

importante

El uso de Amazon Lex y Amazon Polly está sujeto a las Condiciones del AWS servicio, incluidas las condiciones específicas de los Servicios de AWS Machine Learning e Inteligencia Artificial.

Sintaxis de StartBotConversation

A continuación se muestra un ejemplo típico de sintaxis de StartBotConversation.

{
  "SchemaVersion": "1.0",
  "Actions":[
    {
      "Type": "StartBotConversation",
      "Parameters": {
        "CallId": "string",
        "ParticipantTag": "string",
        "BotAliasArn": "string",
        "LocaleId": "string",
        "Configuration": {
          "SessionState": {
             "SessionAttributes": {
                "string": "string" 
             },
             "DialogAction" : {
               "Type": "string"
             }
          },
          "WelcomeMessages": [
            {
              "Content": "string",
              "ContentType": "string" 
            }
          ]
        }
      }
    }
  ]
}

CallId

Descripción: la CallID de un participante en la invocación CallDetails de la AWS Lambda función. La acción StartBotConversation usa este ID como el de la SessionId del bot. Todas las conversaciones de bots que tienen lugar en una llamada comparten la misma sesión de conversación. Puede modificar el estado de la sesión entre su usuario y su bot mediante la PutSession API Amazon Lex. Para obtener más información, consulte Gestión de sesiones con la API Amazon Lex v2 en la Guía para desarrolladores de Amazon Lex.

Valores permitidos: un identificador de llamada válido.

Obligatorio: no, si ParticipantTag está presente.

Valor predeterminado: ninguno.

ParticipantTag

Descripción: la ParticipantTag de uno de los participantes conectados en los CallDetails.

Valores permitidos: LEG-A.

Obligatorio: no, si CallId está presente.

Valor predeterminado: ParticipantTag del callLeg invocado. Se omite si se especifica CallDetails.

BotAliasArn

Descripción: el alias de bot ARN de su bot Lex. Debe crear el bot en la misma región de AWS que la aplicación de audio de PSTN. Un alias de bot de Amazon Lex válido tiene este formato: arn:aws:lex:region:awsAccountId:bot-alias/botId/botAliasId, donde region se encuentra la región de AWS en la que reside el bot. El awsAccountId es el ID de cuenta de AWS en el que se creó el bot de Amazon Lex. El valor botId es el identificador asignado al bot cuando se creó. Puede encontrar el ID del bot en la consola Amazon Lex, en la página de detalles del bot. El botAliasId es el identificador asignado al alias del bot cuando se creó. Puede ver el ID del alias del bot en la consola de Amazon Lex en la página Alias.

Valores permitidos: un ARN de bot válido.

Obligatorio: sí.

Valor predeterminado: ninguno.

LocaleId

Descripción: el identificador de la configuración regional que utilizó para su bot. Para obtener una lista de las configuraciones regionales y los códigos de idioma, consulte Idiomas y configuraciones regionales compatibles con Amazon Lex.

Valores permitidos: lenguajes y configuraciones regionales compatibles con Amazon Lex.

Obligatorio: no.

Valor predeterminado: en_US.

Configuration

Descripción: la configuración de la conversación, incluidos el estado de la sesión y los mensajes de bienvenida. El tamaño total de la representación en cadena JSON del objeto de Configuration está limitado a 10 KB.

Valores permitidos: Configuration objeto.

Obligatorio: no.

Valor predeterminado: ninguno.

Configuration.SessionState

Descripción: el estado de la sesión del usuario con Amazon Lex v2.

Valores permitidos: SessionState objeto.

Obligatorio: no.

Valor predeterminado: ninguno.

Configuration.SessionState.SessionAttributes

Descripción: una asignación de pares clave-valor que representa la información de contexto específica de la sesión. Este mapa contiene la información de la aplicación que se transmite entre Amazon Lex v2 y una aplicación cliente.

Valores permitidos: mapa de cadena a cadena.

Obligatorio: no.

Valor predeterminado: ninguno.

Configuration.SessionState.DialogAction.Type

Descripción: la siguiente acción que realiza el bot en sus interacciones con el usuario. Valores posibles:

• Delegado: Amazon Lex v2 determina la siguiente acción.

• ElicitIntentLa siguiente acción suscita una intención por parte del usuario.

Valores permitidos: Delegate | ElicitIntent.

Obligatorio: no.

Valor predeterminado: ninguno.

Configuration.WelcomeMessages

Descripción: lista de mensajes para enviar al usuario al inicio de la conversación. Si establece el campo welcomeMessage, debe establecer el valor DialogAction.Type como ElicitIntent.

Valores permitidos: objeto de mensaje

Obligatorio: no.

Valor predeterminado: ninguno.

Configuration.WelcomeMessages.Content

Descripción: el texto del mensaje de bienvenida.

Valores permitidos: cadena.

Obligatorio: no.

Valor predeterminado: ninguno.

Configuration.WelcomeMessages.ContentType

Descripción: indica el tipo de mensaje de bienvenida.

Valores permitidos: PlainText | SSML

• PlainText— El mensaje contiene texto UTF-8 plano.

• SSML: el mensaje contiene texto con formato para salida de voz.

Obligatorio: sí.

Valor predeterminado: ninguno.

Uso de la acción StartBotConversation

A continuación se muestra una acción típica de StartBotConversation.

{
  "SchemaVersion": "1.0",
  "Actions":[
    {
      "Type": "StartBotConversation",
      "Parameters": {
        "CallId": "call-id-1",
        "BotAliasArn": "arn:aws:lex:us-east-1:123456789012:bot-alias/ABCDEFGHIH/MNOPQRSTUV",
        "LocaleId": "en_US",
        "Configuration": {
          "SessionState": {
             "SessionAttributes": {
                "mykey1": "myvalue1" 
             },
             "DialogAction" : {
               "Type": "ElicitIntent"
             }
          },
          "WelcomeMessages": [
            {
              "Content": "Welcome. How can I help you?",
              "ContentType": "PlainText" 
            }
          ]
        }
      }
    }
  ]
}

Manejo de ACTION_SUCCESSFUL eventos

En el ejemplo siguiente se muestra un evento ACTION_SUCCESSFUL típico para la acción StartBotConversation.

{
    "SchemaVersion": "1.0",
    "Sequence": number,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData":
    {
        "CallId": "string",
        "Type": "StartBotConversation",
        "Parameters": {
            // parameters provided in the StartBotConversation action.
        },
        "CallDetails": {
            // Information about the call associated with the AWS Lambda invocation.
        },
        "IntentResult": {
            "SessionId": "string",
            "SessionState": {
                "SessionAttributes": {
                    "string": "string"
                },
                "Intent": {
                    "Name": "string",
                    "Slots":  {
                        "string": {
                            "Value": {
                                "OriginalValue": "string",
                                "InterpretedValue": "string",
                                "ResolvedValues": ["string"]
                            },
                            "Values": []
                        }
                    },
                    "State": "string",
                    "ConfirmationState": "string"
                }
            },
            "Interpretations": [
                {
                    "NluConfidence": {
                        "Score": number
                    },
                    "Intent": {
                        "Name": "string",
                        "Slots": {
                            "string": {
                                "Value": {
                                    "OriginalValue": "string",
                                    "InterpretedValue": "string",
                                    "ResolvedValues": ["string"]
                                },
                                "Values": []
                            }
                        },
                        "State": "string",
                        "ConfirmationState": "string"
                    }
                }
            ]
        }
    }
}

IntentResult

El resultado de la conversación entre el usuario y el bot.

SessionId

Identificador de la sesión de conversación del bot. Cuando un usuario inicia una conversación con un bot, Amazon Lex crea una sesión. Una sesión encapsula la información intercambiada entre el usuario y el bot. La acción StartBotConversation usa el ID de llamada como el de la SessionId del bot. Puedes modificar el estado de sesión entre tu usuario y tu bot mediante la PutSessionAPI Lex. Para obtener más información, consulte Gestión de sesiones con la API Amazon Lex v2 en la Guía para desarrolladores de Amazon Lex.

SessionState

El estado de la sesión del usuario con Amazon Lex V2.

SessionState.SessionAttributes

Una asignación de pares clave/valor que representa la información de contexto específica de la sesión. El mapa contiene la información de la conversación del bot que se transmite entre la función de Lambda adjunta al bot y la función de Lambda de audio PSTN.

Interpretaciones

Una lista de intenciones derivada de Amazon Lex que pueden satisfacer la expresión del cliente. La intención con la puntuación de NluConfidence más alta se convierte en la intención de SessionState.

Interpretaciones. NluConfidence.Puntuación

Una puntuación que indica el grado de confianza de Amazon Lex v2 de un en lo que respecta a la capacidad de una intención para satisfacer las expectativas del usuario. Varía entre 0.00 y 1.00. Una puntuación más alta indica una mayor confianza.

Intent

La acción que el usuario desea realizar.

Intent.Name

El nombre de la intención.

Intent.Slots

Un mapa de todos los espacios para la intención. El nombre de la ranura se asigna al valor de la ranura. Si no se ha ocupado un espacio, el valor es nulo.

Intent.Slots.Value

El valor del tipo de ranura.

Intent.Slots.Values

Una lista de uno o más valores que el usuario ha proporcionado para la ranura.

Intent.Slots.Value.OriginalValue

El texto de la respuesta del usuario, introducido para el espacio.

Intent.Slots.Value.InterpretedValue

Descripción: el valor que Amazon Lex v2 determina para la ranura. El valor real depende de la configuración de la estrategia de selección de valores del bot. Puede optar por utilizar el valor introducido por el usuario o puede hacer que Amazon Lex v2 elija el primer valor de la lista de resolvedValues.

Intent.Slots.Value.ResolvedValues

Una lista de valores adicionales que Amazon Lex v2 reconoce para la ranura.

Intent.State

Descripción: información sobre el cumplimiento de la intención. Valores posibles:

• Failed— La función Lambda no cumplió la intención.

• Fulfilled— La función Lambda cumplió la intención.

• ReadyForFulfillment— La información de la intención está presente y su función Lambda puede cumplirla.

Intent.ConfirmationState

Descripción: indica la confirmación de la intención. Valores posibles:

• Confirmado: se cumple la intención.

• Denegado: el usuario respondió “no” a la solicitud de confirmación.

• Ninguno: no se solicitó la confirmación al usuario o se le pidió al usuario que confirmara o rechazara la solicitud, pero no la confirmó o rechazó.

Manejo de eventos ACTION_FAILED

En el ejemplo siguiente se muestra un evento ACTION_FAILED típico para la acción StartBotConversation.

{
    "SchemaVersion": "1.0",
    "Sequence": number,
    "InvocationEventType": "ACTION_FAILED",
    "ActionData":{
        "CallId": "string",
        "Type": "StartBotConversation",
        "Parameters": {
            // parameters provided in the StartBotConversation action
        },
        "ErrorType": "string",
        "ErrorMessage": "string"
    },
    "CallDetails":{
    }
}

ErrorType

Una cadena que identifica de forma exclusiva una condición de error.

ErrorMessage

Una descripción genérica de la condición de error.

Códigos de error

En la siguiente tabla se enumeran los mensajes de error que una función de Lambda puede devolver en un evento de ACTION_FAILED.

Error	Descripción
InvalidActionParameter	Uno o más parámetros de acción no son válidos. El mensaje de error describe el parámetro no válido.
SystemException	Se ha producido un error del sistema al ejecutar una acción.
ResourceNotFound	No se encuentra un bot especificado.
ResourceAccessDenied	El acceso al bot se deniega.
ActionExecutionThrottled	Se ha superado el límite del servicio de conversación entre bots. El mensaje de error describe el límite de servicio específico que se ha superado.

Concesión de permisos para usar un bot

El siguiente ejemplo concede al SDK de Amazon Chime permiso para llamar a las API de Amazon Lex StartConversation. Debe conceder explícitamente permiso al servicio de audio para que use su bot. El bloque de condiciones es obligatorio para las entidades principales de servicio. El bloque de condiciones debe usar las claves de contexto globales AWS:SourceAccount y AWS:SourceArn. AWS:SourceAccount es el ID de su cuenta de AWS. AWS:SourceArn es el ARN de recurso de la aplicación de audio PSTN que invoca el bot Lex.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowChimePstnAudioUseBot",
      "Effect": "Allow",
      "Principal": {
        "Service": "voiceconnector.chime.amazonaws.com"
      },
      "Action": "lex:StartConversation",
      "Resource": "arn:aws:lex:region:awsAccountId:bot-alias/botId/aliasId",
      "Condition": {
        "StringEquals": {
          "AWS:SourceAccount": "awsAccountId"
        },
        "ArnEquals": {
        "AWS:SourceArn": "arn:aws:voiceconnector:region:awsAccountId:sma/smaId"
        }
      }
    }
  ]
}

Configuración de los tiempos de espera de voz y DTMF

Puede configurar los tiempos de espera de voz y DTMF al capturar las entradas del usuario. También puede configurar los tiempos de espera mediante atributos de sesión al iniciar una conversación con un bot y sobrescribirlos en su función de Lambda si es necesario. Amazon Lex le permite establecer varias ranuras para una intención o bots. Dado que puede especificar que los atributos de sesión se apliquen en el nivel de intención y ranura, puede especificar que el atributo se establezca solo cuando obtenga un determinado tipo de entrada. Por ejemplo, puede especificar un tiempo de espera más largo cuando recopile un número de cuenta que cuando recopile una fecha. Puede utilizar caracteres comodín en la clave de atributo de la sesión.

Por ejemplo, para establecer un tiempo de espera de voz para todos los intervalos a todos los efectos en 4000 milisegundos, puede proporcionar un atributo de sesión utilizando: x-amz-lex:start-timeout-ms:*:* como nombre del atributo de sesión y 4000 como valor del atributo de sesión. Para obtener más información, consulte Configuración de los tiempos de espera para capturar la entrada del usuario en la Guía para desarrolladores de Amazon Lex.

Uso de entradas DTMF durante una conversación

Los bots de Amazon Lex admiten la entrada de voz y teclado durante una conversación. Los bots interpretan las entradas del teclado como dígitos DTMF. Puede solicitar a los contactos que finalicen su entrada con la tecla almohadilla (#) y que cancelen una conversación con la tecla asterisco (*). Si no pide a los clientes que finalicen sus entradas con la tecla almohadilla, Lex deja de esperar a que se presionen más teclas después de 5 segundos.

Service Quotas y cuotas de facturación

AWS le factura los siguientes costos:

• Uso de Amazon Chime SDK para la llamada. Para obtener más información, consulte los Precios de Amazon Chime SDK.

• Uso de Amazon Lex para interpretar el discurso de los usuarios. Para obtener más información, consulte Precios de Amazon Lex Streaming Conversation.

• Uso de Amazon Polly para sintetizar las respuestas de texto de su bot. Para obtener más información, consulte precios de Amazon Polly.

También debe conocer las siguientes Service Quotas:

• El SDK de Amazon Chime tiene una cuota de servicio para el número máximo de bots de Amazon Lex que puede utilizar con la acción PSTN Audio. StartBotConversation Para obtener más información, consulte las cuotas de voz y enlaces troncales SIP en la Referencia general.AWS

• Amazon Lex tiene una Service Quota para el número máximo de conversaciones de voz simultáneas por bot Lex. Puede ponerse en contacto con el equipo de servicio de Amazon Lex para obtener más cuotas. Para obtener más información, consulte las directrices y cuotas de Amazon Lex en la Guía para desarrolladores de Amazon Lex.

• Amazon Polly tiene una Service Quota para sintetizar respuestas de texto. Puede ponerse en contacto con el equipo de servicio de Amazon Polly para obtener más cuotas. Para obtener más información sobre las Service Quotas de Amazon Polly, consulte Cuotas en Amazon Polly, en la Guía para desarrolladores de Amazon Polly.