Cierre de Conversaciones HITL en Botpress

Este endpoint permite cerrar la última conversación atendida por un agente humano (HITL) en Botpress y devolver el control de la interacción al bot.

Descripción general

El flujo se basa en identificar la conversación HITL asociada a una conversación de origen (WhatsApp, Instagram, Messenger, etc.), obtener el ticketId correspondiente y notificar a Botpress que el ticket fue resuelto.

---

Endpoint

POST

https://suricata1.com.ar/api/close-conversation

---

Flujo del proceso

1. Obtiene la configuración de Botpress del merchant desde base de datos.

2. Usa el conversation_id del canal origen para consultar la conversación en Botpress.

3. Extrae el tag downstream, que contiene el ID de la conversación HITL.

4. Consulta la conversación HITL para obtener el ticketId desde un tag específico.

5. Llama al webhook de Botpress para indicar que el ticket fue resuelto.

6. Devuelve una respuesta JSON indicando éxito o error, con códigos HTTP adecuados.

---

Parámetros de entrada

El endpoint recibe los siguientes parámetros vía request:

Parámetro	Tipo	Descripción
merchant	string	Prefijo del merchant (sanitizado)
conversation_id	string	ID de la conversación origen (WhatsApp, Instagram, Messenger, etc.)
token	string	Token de acceso simple

---

Método principal: closeConversationByHookBotpress(Request $request)

Propósito

Orquesta todo el flujo de cierre de la conversación:

• Valida el token

• Carga la configuración del merchant

• Obtiene el ticketId asociado a la conversación HITL

• Notifica a Botpress que el ticket fue resuelto

---

Flujo principal

1. Valida el token:

   • Si falta o es inválido, retorna error.

2. Obtiene la configuración de Botpress del merchant desde base de datos.

3. Llama a getConversationHitlId(conversation_id, bot_id) para obtener el ticketId.

4. Realiza un POST al webhook de Botpress indicando que el ticket fue resuelto, enviando el siguiente payload:

   {
     "ticketId": "<id>"
   }

5. Retorna una respuesta JSON con el resultado de la operación.

---

Respuestas

Código HTTP	Descripción
200	Conversación cerrada correctamente
400	Token ausente o parámetros inválidos
403	Token inválido
404	Configuración del merchant no encontrada
500	Error interno del proceso

Ejemplo de respuesta exitosa

{
  "message": "Conversation closed successfully. Ticket: <id>"
}

Ejemplo de respuesta de error

{
  "error": "Error description"
}

---

Método: getConversationHitlId($conversation_id, $bot_id)

Propósito

Dado un conversation_id de origen, obtiene la conversación correspondiente en Botpress, extrae el tag downstream y devuelve el ticketId asociado a la conversación HITL.

---

Parámetros

Parámetro	Tipo	Descripción
conversation_id	string	ID de la conversación origen
bot_id	string	Identificador del bot utilizado en las llamadas a Botpress

---

Flujo

1. Consulta la conversación origen en Botpress.

2. Extrae el objeto conversation si la respuesta viene envuelta.

3. Obtiene el valor del tag tags.downstream.

4. Si el tag downstream no existe:

   • Retorna un error en formato JSON.

5. Espera breve (sleep(2)).

6. Llama a getTicketId(downstream, bot_id).

7. Valida que el ticketId sea escalar y no vacío.

8. Retorna el ticketId.

---

Respuestas / Errores

• string: Ticket ID válido.

• JSON error (500):

  • Error al consultar la API de Botpress.

  • No se encuentra el tag downstream.

  • No se puede obtener el ticketId.

Nota Este método puede retornar tanto valores escalares (ticketId) como respuestas JSON de error. El método llamador debe manejar ambos escenarios.

---

Método: getTicketId($conversationHitl_id, $bot_id)

Propósito

Consulta la conversación HITL (downstream) y extrae el ID del ticket desde los tags de la conversación.

---

Parámetros

Parámetro	Tipo	Descripción
conversationHitl_id	string	ID de la conversación HITL
bot_id	string	Identificador del bot

---

Flujo

1. Consulta la conversación HITL en Botpress.

2. Extrae el objeto conversation si la respuesta está envuelta.

3. Revisa los tags asociados a la conversación.

4. Extrae el valor del tag:

   suricata/suricata-meerkat:id

---

Respuestas

Valor	Descripción
string	Ticket ID encontrado
null	Error en la consulta o tag inexistente