⬇️Correos y notificaciones | Ranura para solicitudes entrantes

Objeto e información general

La Ranura de Petición Entrante es una Ranura que permite a un Agente escribir en un Chat cuando los Diálogos están cerrados. La presencia de un Incoming Request Slot permite a un sistema externo activar un Agente en un Chat específico enviando una petición http (POST o GET) a su webhook, por ejemplo, para enviar una notificación a un Usuario Bot sobre el estado de su pedido. Al recibir una Solicitud Entrante, un Agente inicia una Rama de Script siguiendo la Ranura de Solicitud Entrante.

Creación y configuración de Slots

1. La Ranura de Solicitud Entrante sólo puede crearse después de la Ranura de Inicio si existe una rama regular para procesar mensajes entrantes a través del Canal de Proyectos.

1. Sólo se permite una ranura de solicitud entrante por guión.

Atributos de los Slots

1. Nombre - el nombre de una Ranura que se mostrará en un Árbol de Guiones. La longitud máxima de un valor de campo es de 40 caracteres.

2. Webhook - Dirección Webhook de una ranura de solicitud entrante.

   1. El campo está vacío hasta que se guarda la ranura;

   2. El campo no se puede editar, pero su contenido se puede copiar en el portapapeles;

   3. La dirección del webhook está disponible en Variables de Contexto del Sistema IR_url.

   4. El webhook comienza a funcionar después de que el Agente es entrenado.

3. Una matriz de pares Clave de contexto - Clave de solicitud para analizar datos de los parámetros de una solicitud entrante en variables de contexto de usuario para su posterior uso en un script. Más información sobre el análisis sintáctico: Parámetros de la petición entrante y su conversión en variables de contexto.

   1. Clave de contexto: nombre de las variables de contexto de usuario en las que se escribirá el valor.

   2. Clave de solicitud: una clave de los parámetros Solicitud entrante, Expresión o Expresión con estructura de control, cuyo valor se escribirá en la Clave de contexto. Más información: Uso de la sintaxis en la ranura de petición entrante

      1. Recorte de espacios: al pulsar el botón CREAR (al crear una Ranura) o GUARDAR (al editar una Ranura), se recortan los espacios y saltos de línea al principio y al final del campo Clave de solicitud.

Webhook para ranura de solicitud entrante

1. El Webhook de solicitud entrante se genera sólo después de guardar la ranura.

2. El webhook de solicitud entrante estará disponible en la ventana de edición de la ranura cuando se abra después de guardarlo.

1. El valor del campo Webhook es una dirección url (enlace) que debe copiarse y pasarse a un sistema externo para enviar una ranura de solicitud entrante, ejemplo: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4

2. El Webhook de Petición Entrante a través del enlace se activa después de guardar el Script, pero responde con un error a todas las peticiones hasta el momento del Entrenamiento del Agente.

3. La dirección del webhook de solicitud entrante activo está disponible en el contexto de chat en la variable de contexto IR_url y se carga en el informe de contexto de chat.

4. Puede sustituir query_params en el Webhook de solicitud entrante, por ejemplo chat_id y is_urgent (aún no se admiten otros parámetros de URL).

5. El Webhook de Petición Entrante puede ser regenerado usando el botón GENERAR NUEVO WEBHOOK; responderá después de guardar el Slot (con un error), pero comenzará a procesar peticiones después de volver a entrenar al Agente.

6. Nota: En este caso, desde el momento en que se guarda el Slot hasta que el Agente es reentrenado, ambos Incoming Request Webhook funcionarán: el antiguo continuará recibiendo y procesando peticiones, el nuevo responderá con un error a las peticiones. Después de reentrenar al Agente, el Webhook de Petición Entrante antiguo se borrará y dejará de responder, y el nuevo empezará a recibir y procesar peticiones.

7. El Incoming Request Webhook no se guarda en el archivo de configuración al exportar el Agente; al importar el archivo de configuración, se genera un nuevo Incoming Request Webhook para el Agente creado por la importación.

8. Al reemplazar el Script de Agente por un archivo de configuración con Ranura de Solicitud Entrante:

   1. Si el script del agente ya tenía una ranura de solicitud entrante antes de la sustitución, el Webhook de solicitud entrante en el nuevo script seguirá siendo el mismo que antes de la sustitución.

   2. Si no había ninguna ranura de solicitud entrante en el script del agente antes de la sustitución, se generará una nueva dirección de Webhook de solicitud entrante para esta ranura.

Uso de la sintaxis en la ranura de solicitud entrante

En una Ranura, se permite utilizar Expresión y Expresión con Estructura de Control en el campo Clave de petición. Más detalles: Sintaxis.El resultado del cálculo de la plantilla se guardará en el Contexto de Chat, de forma similar a la Ranura de Memoria.

IMPORTANTE: Para analizar los campos is_urgent / chat_id, sólo se permite Expression. No se permite el uso de expresiones con estructuras de control.

Al analizar el cuerpo de una solicitud, las "variables" especificadas en el campo Clave de solicitud no son variables de contexto, sino llamadas al cuerpo, las cabeceras, los objetos de consulta -partes de la solicitud entrante- y sus propiedades. Más información: Parámetros de la solicitud entrante y su conversión en variables de contexto

Solicitud entrante

Una Solicitud entrante es una solicitud HTTPS enviada al Webhook de Solicitud entrante con el fin de activar la Rama de Script que sigue a la Ranura de Solicitud entrante en un Chat específico para ese Agente. El ID del chat de destino - chat_id - debe especificarse en el cuerpo de la solicitud o en los parámetros url (query params).

Formato de solicitud entrante

1. Protocolo: HTTPS

2. Request method: POST\GET

   1. Cuerpo de la solicitud POST: JSON

3. Autorización: el token de autorización forma parte de la URL del Webhook de solicitud entrante

4. atributo de solicitud chat_id:

   1. El atributo chat_id contiene el identificador del chat (el valor de la variable chat_id) en el que se debe iniciar la rama de script de ranura de solicitud entrante.

   2. Atributo obligatorio. Ubicación: clave "chat_id" en el cuerpo de la solicitud entrante o el parámetro chat_id en los parámetros url de la solicitud entrante (query params).

   3. Chat_id orden de búsqueda y prioridad de selección:

      1. Para una solicitud POST:

         1. Prioridad 1 - a lo largo de la ruta especificada en el cuerpo de la solicitud: El usuario puede definir la ruta de acceso a la clave "chat_id" en los ajustes de análisis sintáctico de la ranura de solicitud entrante: ésta es la ruta prioritaria para la búsqueda

⁠3. Prioridad 2 - en el parámetro de la petición: Si la clave "chat_id" no se encuentra en el cuerpo de la solicitud POST entrante en la ruta especificada por el usuario, el sistema buscará el parámetro chat_id en los parámetros de consulta de la url de solicitud. Ejemplo:https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea

1. Prioridad 3 - en el primer nivel del cuerpo de la solicitud: Si la clave "chat_id" no se encuentra en la ruta especificada por el usuario en el cuerpo de la petición, y el parámetro chat_id no se encuentra en los parámetros de la consulta, la clave "chat_id" se busca en el primer nivel del cuerpo de la petición

ii. Para una solicitud GET: la búsqueda se produce sólo en los parámetros URL de la solicitud @Incoming Request

1. atributo de solicitud is_urgent:

   1. El atributo is_urgent contiene una indicación de la urgencia de la solicitud. Atributo opcional, si no se especifica, se evalúa como false.

   2. Valores válidos:

      1. true - señal de una solicitud entrante urgente - se ejecuta inmediatamente e interrumpe un diálogo activo

      2. false - señal de una solicitud entrante no urgente - se ejecuta después de cerrar el diálogo

   3. Orden de búsqueda Is_urgent y prioridad de selección:

      1. Para una solicitud POST:

         1. Prioridad 1 - a lo largo de la ruta especificada en el cuerpo de la solicitud: El usuario puede definir la ruta de acceso a la clave "is_urgent" en los ajustes de análisis sintáctico de la ranura de solicitud entrante: esta es la ruta prioritaria para la búsqueda.

1. Prioridad 2 - en el parámetro de solicitud: Si en la ruta especificada por el usuario no se encuentra la clave "is_urgent" en el cuerpo de la solicitud POST entrante, el sistema buscará el parámetro is_urgent en los parámetros de consulta de la url de la solicitud - ejemplo: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?is_urgent=true

2. Prioridad 3 - en el primer nivel del cuerpo de la solicitud: Si la clave "is_urgent" no se encuentra en la ruta especificada por el usuario en el cuerpo de la petición, y el parámetro is_urgent no se encuentra en los parámetros de la consulta, la clave "is_urgent" se busca en el primer nivel del cuerpo de la petición

3. Si el atributo is_urgent no se encuentra mediante los métodos anteriores, toma el valor false

ii. Para una solicitud GET: la búsqueda se produce sólo en los parámetros URL de la solicitud entrante

Importante:

* las ubicaciones de chat_id y is_urgent pueden ser las mismas (ejemplo): https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb8924 4f6dea&is_urgent=true)

* las ubicaciones de chat_id y is_urgent pueden diferir, por ejemplo, is_urgent puede pasarse en los parámetros de la solicitud, y la ruta a la clave "chat_id" (en el cuerpo de la solicitud) puede ser especificada por el usuario en los ajustes de análisis sintáctico.

1. Datos del usuario en la solicitud entrante:

   1. variables, matrices y objetos: pares clave-valor en el cuerpo de la solicitud entrante para transferirlos a variables de contexto al analizarlos en la ranura de solicitud entrante. Campos opcionales.

   2. Sólo puede enviarse en una solicitud POST.

Parámetros de la solicitud entrante y su conversión en variables de contexto

Parámetros de la solicitud entrante:

Cuando llega una solicitud entrante, es posible acceder a sus partes (cabeceras, cuerpo, parámetros) como objetos para analizar el contenido de estas partes.

1. Cuerpo de la solicitud

body - objeto cuerpo de la petición. Formato: JSON.

Acceso a las claves anidadas en el cuerpo(JSON): body.<key>

Importante: Si el tamaño del cuerpo de la Incoming Request excede el límite del tamaño del cuerpo recibido en la Incoming Request, entonces se sustituye por un cuerpo vacío {}.

1. Cabeceras de solicitud

cabeceras - un objeto que contiene las cabeceras de la solicitud. Acceso a las cabeceras: cabeceras.

1. Parámetros de consulta

query - un objeto que contiene parámetros de consulta de la URL (después del signo ? en la URL)

Acceso a los parámetros: query.<nombre del parámetro>

Importante: el cuerpo, las cabeceras y los objetos de consulta no se guardan en el contexto de chat, pero están disponibles para el análisis sintáctico cuando se ejecuta esta ranura de solicitud entrante.

El cuerpo, las cabeceras y la consulta pueden analizarse íntegramente en variables de contexto.

En Variables de contexto, en el campo Clave de contexto, puede establecer nombres que coincidan con los nombres de partes de la solicitud, por ejemplo, analizar todo el objeto body en la variable body.

Funciones de análisis sintáctico:

• Es posible analizar objetos, matrices y variables de cualquier anidamiento;

• Ejemplo: {{ body.content.par1 }} - acceso a la variable par1 anidada en content y body

• Los nombres de las variables y las rutas a los valores distinguen entre mayúsculas y minúsculas;

• Ejemplo: {{ cuerpo.nombre }} y {{ cuerpo.Nombre }} - llaman a diferentes claves (name y Name) en el cuerpo de la petición.

• El punto (.) se refiere a las claves de los niveles inferiores del objeto multinivel\JSON;

• Ejemplo: {{ body.content.par1 }}

• Se accede al número de elemento de matriz correspondiente mediante números. La numeración de los elementos de la matriz comienza en cero, por lo que el acceso al primer elemento de la matriz se designa como 0.

• Ejemplo: {{ body.array.0.par1 }} - accediendo al primer elemento del array

• La referencia a la clave de un objeto, si su nombre coincide con el de los métodos reservados de los objetos, se produce mediante corchetes y comillas.

• Ejemplo: {{ data["keys"] }}

Ejemplos de solicitudes entrantes y su análisis sintáctico

1) Con chat_id y is_urgent en el cuerpo de la petición A continuación se muestra un ejemplo de una y parseando los datos de esta petición en variables

• La solicitud POST se envía al Webhook de solicitud entrante y contiene los siguientes parámetros de consulta: ...?bar=42&baz=aaa

• La solicitud contiene una cabecera Authorization con el valor Token fjrv44344fjvr

• Cuerpo de la solicitud:

{
    "chat_id": "e2022b50f626d13b8fc12ee0ea2d7582dca09424",
    "is_urgent": true,
    "par": "value",
    "content":
        {
            "par1": "value1"
        },
    "array": [
        {
            "par2": "value2"
        },
        {
            "par3": "value3"
        }
    ]
}

Análisis sintáctico de esta solicitud en variables:

En el ejemplo, en el caso de body y query, las claves y parámetros individuales se analizan en variables, pero también es posible analizar el objeto completo, como en el ejemplo siguiente con las cabeceras.

var1 contendrá el valor

El valor valor1 se escribirá en var2

El valor valor2 se escribirá en var3

El valor (objeto) {'Authorization': 'Token fjrv44344fjvr'} se escribirá en var4

42 se escribirá en var5

1. Con chat_id y is_urgent en los parámetros de la URL de solicitud

URL: https://platform_domain/api/incoming_request/31104::lhmscvYm4Ms4qkJTFP6I22HyGVW_03HE-SXtcd0tLk4?chat_id=1b7637033b3fc4c15a95bfad048ceb89244f6dea&is_urgent=false

CUERPO:

{
    "message": "Discounts for new clients",
    "name": "John"
}

En este ejemplo, la solicitud entrante se dirige a Chat con chat_id= 1b7637033b3fc4c15a95bfad048ceb89244f6dea.

Esta petición se pondrá en cola y se ejecutará después de que se cierre el Diálogo, porque no es urgente (is_urgent = false).

Parseando esta petición en variables:

Los valores de las claves de mensaje y nombre se analizarán en Variables de Contexto de Usuario si la Ranura está configurada como se muestra en la siguiente captura de pantalla.

Funcionamiento de los Slot

El funcionamiento de la ranura comienza en el momento en que la plataforma recibe una solicitud entrante de un servicio externo en el gancho web de solicitud entrante. Tras recibir una solicitud, se realizan las siguientes operaciones en el orden especificado:

1. Comprobación de los límites de solicitudes API: para cada Empresa existe un Límite de Solicitudes Entrantes - 20 Solicitudes Entrantes por segundo en total para todos los Webhooks de Solicitud Entrante en todos los Agentes de la Empresa.

   1. Si se supera el límite: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 429

   2. En caso contrario, se pasa a la operación siguiente.

2. Verificación del método: Se comprueba el método POST/GET en la solicitud entrante:

   1. Si se ha enviado una solicitud utilizando un método diferente (no POST/GET): Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 405

   2. Otherwise, the transition to the next operation occurs.

3. Comprobación de la cabecera content-type: application/json: si el método de solicitud es POST, se comprueba la presencia de la cabecera content-type: application/json:

   1. Si la solicitud entrante no tiene una cabecera content-type: application/json: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante: con estado: Estado HTTP: 400 CUERPO: "Estado": "Tipo de contenido no soportado".

   2. En caso contrario, se pasa a la operación siguiente.

4. Comprobación del tamaño del cuerpo de la solicitud entrante:

   1. Si el tamaño del cuerpo de la solicitud entrante supera los 10 KB, el cuerpo se sustituye por {}.

   2. En caso contrario, se pasa a la operación siguiente.

5. Validación de la corrección de JSON: si el método de solicitud es POST, se valida que el cuerpo de la solicitud entrante sea JSON correcto:

   1. Si no fue posible analizar el cuerpo de la solicitud entrante, es decir, JSON no válido: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 400 CUERPO: {"status": "Document parse error."}

   2. En caso contrario, se pasa a la operación siguiente

6. Búsqueda de la Ranura de Petición Entrante: el sistema busca entre el Modelo de Agente Entrenado la Ranura de Petición Entrante cuyo Webhook de Petición Entrante recibió una petición:

   1. Si la ranura de solicitud entrante no se encuentra en el modelo de agente entrenado, la ranura de solicitud entrante se abrirá.Solicitud Webhook para la que se recibió la solicitud: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 404 CUERPO: {"status": "Solicitud entrante no encontrada."}

   2. En caso contrario, se pasa a la operación siguiente.

7. Buscar chat_id:

   1. Si el método de solicitud es GET, el sistema busca el parámetro chat_id en los parámetros URL de la solicitud entrante

   2. Si el método de solicitud es POST, el sistema busca el parámetro chat_id en el cuerpo de la solicitud entrante y, si no lo encuentra, en los parámetros de URL de la solicitud entrante.

   3. Si no se encuentra el parámetro chat_id: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 400 CUERPO: {"status": "No chat id aprobado."}

      1. En caso contrario, se pasa a la operación siguiente.

8. Buscar is_urgent:

   1. Si el método de solicitud es GET, el sistema busca el parámetro is_urgent en los parámetros URL de la solicitud entrante

   2. Si el método de solicitud es POST, el sistema busca el parámetro is_urgent en el cuerpo de la solicitud entrante y, si no lo encuentra, en los parámetros URL de la solicitud entrante.

   3. Si no hay is_urgent o existe, pero no fue posible leer el booleano correcto, el sistema lo considera falso.

9. Buscar chat por chat_id.

   1. Si no se encuentra el Chat por chat_id recibido en el cuerpo o en los parámetros de la petición: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 400 CUERPO: {"status": "Chat no encontrado."}

   2. Si se encuentra un chat con un identificador del atributo chat_id, pero se elimina el canal de proyecto de este chat: Se detiene el procesamiento de la solicitud. Envío de una respuesta a una solicitud entrante con el estado Estado HTTP: 400 CUERPO: {"status": "No hay ningún canal activo para el evento recibido."}

   3. En caso contrario, se pasa a la operación siguiente.

10. Ejecutando el script.

    1. Si is_urgent == true, (paso 7) entonces se lanza la Rama de Guión de Ranura de Solicitud Entrante. Envío de una respuesta a una solicitud entrante con el estado: Estado HTTP: 200 OK CUERPO: “status”: "Aceptado para ejecución"

    2. Si is_urgent == false, y no hay ningún Diálogo activo en el Chat, entonces se lanza la Rama de Guión de la Ranura de Petición Entrante. Envío de una respuesta a una solicitud entrante con el estado: Estado HTTP: 200 OK CUERPO: “status”: “Aceptado para ejecución"

    3. Si is_urgent == false y hay un diálogo activo en el chat, la solicitud pasa a la cola de solicitudes entrantes y se procesará en el chat inactivo cuando llegue su turno.