Documentación de la API Pública

Este documento describe los endpoints de la API destinados al público para interactuar con mensajes y hilos. Cada endpoint requiere una autenticación válida (a través de x-api-key en el encabezado Headers) para acceder. A continuación, encontrará detalles sobre cada ruta disponible, incluidos los métodos de solicitud, los cuerpos de solicitud/respuesta y ejemplos de uso.

Autenticación

Esta API requiere una clave API válida en Headers. El formato típico es:

x-api-key: CLAVE API

Si no proporciona un token válido, el servidor devolverá un error 401 Unauthorized.

Puede encontrar su X-API-KEY de API en el tablero de configuración:
https://app.gurusup.com/settings/integrations

GET /threads

Método: GET

Recupera una lista de hilos (conversaciones) para la organización del usuario autenticado.

Solicitud

• Headers: x-api-key: <api_key>

• Parámetros de Consulta: ninguno

Respuesta

Devuelve una matriz de objetos de hilo en formato JSON. Cada hilo incluye metadatos esenciales del hilo.

[
    {
        "thread": "e3b0c44298fc1c14...",
        "thread_fid": "some_unique_thread_identifier",
        ...
    },
    ...
]

Ejemplo

GET /threads
x-api-key: <api_key>

GET /threads/{thread_fid_hash}

Método: GET

Recupera información detallada sobre un solo hilo, incluidos todos los mensajes, identificados por su hash.

Parámetro de Ruta

• thread_fid_hash: MD5-hash del original thread_fid (cadena)

Solicitud

• Headers: x-api-key: <api_key>

Respuesta

Devuelve un solo objeto de hilo en JSON, incluidos todos los mensajes relacionados.

{
    "thread": "d41d8cd98f00b204e9800998ecf8427e",
    "thread_fid": "some_unique_thread_identifier",
    "messages": [
        {
            "body": "Message content here",
            "thread_fid": "some_unique_thread_identifier",
            ...
        },
        ...
    ]

Ejemplo

GET /threads/d41d8cd98f00b204e9800998ecf8427e
x-api-key: <api_key>

POST /messages

Método: POST

Crea un nuevo mensaje (generalmente de un cliente o usuario), luego automáticamente activa una respuesta del sistema si está configurado. El valor de retorno final es la respuesta del mensaje del sistema.

Solicitud

• Headers: x-api-key: <api_key>

• Cuerpo (JSON): Un objeto PartialMessage con campos requeridos

A continuación se presentan los campos clave que puede incluir:

| Campo | Tipo | Notas |

|------------|--------|-------------------------------------------------|

| body | string | El contenido textual del mensaje. |

| user_fid | string | Identificador único para el usuario que envía el mensaje.|

| thread_fid | string | Un identificador para el hilo al que pertenece este mensaje.|

| lang | string | Código de idioma (p. ej., `en`, `es`). |

| subject | string | Asunto/título opcional para el mensaje. |
| is_customer_support_agent | boolean | Identifica si el mensaje fue enviado por un agente de soporte o un cliente |

Respuesta

Devuelve el mensaje de respuesta del sistema recién creado en formato JSON.

Ejemplo

POST /messages
x-api-key: <api_key>

GET /messages/{message_id}

Método: GET

Recupera los detalles de un solo mensaje, por su ID único de base de datos.

Parámetro de Ruta

• message_id: El ObjectID de MongoDB (o cadena) para el mensaje en cuestión.

Solicitud

• Headers: x-api-key: <api_key>

Respuesta

Devuelve el objeto de mensaje en formato JSON:

Se devuelve 404 si no se encuentra el mensaje.

Ejemplo

GET /messages/64f4f4a14abecf6c6eff59c3
Host: your-api-host.com
x-api-key: <api_key>

Webhook

El webhook es una URL que recibe eventos de la plataforma Gurusup. El webhook llamará a la URL del webhook configurada con el tipo de evento y los datos del evento. También se enviará un encabezado x-api-key con el valor de la clave API configurada en la organización.

Tipos de eventos

Evento de envío de mensaje

Cada vez que Gurusup intenta enviar un mensaje al usuario, se enviará un evento de envío de mensaje al webhook para que su plataforma pueda enviar y almacenar efectivamente el mensaje. El mensaje almacenado/enviado debe crearse de la misma manera que el mensaje original.

Ejemplo de un evento de envío de mensaje:

{
  "event_type": "send_message",
  "event_data": {
    "message_body": "Hello, how are you?",
    "subject": "Hello",
    "to": "1234567890",
    "thread_id": "1234567890",
    "in_reply_to_message": null
  }
}