Integraciones con nuestra API

En Nubot ofrecemos una series de APIs para que puedas interactuar con nuestra plataforma

1. Autenticación

Para poder invocar cualquiera de los endpoints descritos en esta documentación, es obligatorio disponer de una API Key válida. Todos los endpoints expuestos (excepto el módulo de generación de API Keys) requieren el encabezado:

x-api-key: <TU_API_KEY>

Además, toda petición debe llevar la cabecera:

Content-Type: application/json

1.1. Generación de API Key

Nuestra plataforma cuenta con un módulo interno desde el cual el usuario administrador puede generar nuevas API Keys. Siga estos pasos para obtener una clave:

  1. Ingrese a la plataforma con un usuario que tenga permisos de administrador.

  2. Vaya a la sección Configuración → API Keys.

  3. Haga clic en “Generar nueva API Key”.

  4. Copie la API Key generada y guárdela en un lugar seguro (no se mostrará de nuevo).

  5. A partir de ese momento, todas las peticiones a los endpoints de nuestra API deben incluir el encabezado x-api-key con la clave recién obtenida.

Nota: Las API Keys se generan por conexion en Nubot

2. Endpoints disponibles

Importante: Todos los endpoints descritos a continuación asumen que se incluye el encabezado x-api-key correctamente. Si omite o envía una clave inválida, se retornará un error 401 Unauthorized.

2.1. Envío de mensajes (send-message)

  • Descripción breve: Permite enviar uno o varios mensajes asociados a un ticket existente en el sistema de soporte.

  • Método: POST

  • URL:

    {{backend_public_apis}}/core/send-message

  • Encabezados requeridos:

    • x-api-key: <TU_API_KEY>

    • Content-Type: application/json

  • Cuerpo de la petición (JSON):

    Campo
    Tipo
    Obligatorio
    Descripción

    ticket_id

    string

    Sí

    Identificador único del ticket al que se asociará el/los mensaje(s).

    messages

    arreglo

    Sí

    Arreglo de objetos con la siguiente estructura:

    type

    string

    Sí

    Tipo de mensaje ("text").

    content

    string

    Sí

    Contenido textual del mensaje.

    url

    url

    no

    Url del objeto que se enviara (imagen, video, archivo, audio)

    caption

    string

    no

    Contenido textual del mensaje si es una imagen.

  • Ejemplo de cuerpo:

    {
  "ticket_id": "3ce9a977-53bc-4837-ae9c-7704b4fc76fc",
  "messages": [
    {
      "type": "text",
      "content": "Hola, este es un mensaje de prueba."
    }
  ]
}

  • Respuesta exitosa (HTTP 200):

    {
  "status": "success",
  "message": "Message sent successfully."
}

  • Códigos de error más comunes:

    • 400 Bad Request

      • Falta ticket_id o messages en el cuerpo.

      • El arreglo messages tiene formato inválido (no es arreglo o falta alguno de los campos type/content).

    • 401 Unauthorized

      • No se incluyó x-api-key o la clave proporcionada es inválida.

    • 404 Not Found

      • El ticket_id indicado no existe en el sistema.

    • 500 Internal Server Error

      • Error inesperado en el servidor. Retorna:

        {
  "status": "error",
  "message": "Internal server error."
}

2.2. Actualizar etapa de ticket (update-stage)

  • Descripción breve: Actualiza la etapa (stage) de un ticket ya existente. Por ejemplo, cambiar de “Atendido” a “Venta” o “Quote”, dependiendo de los stages que tenga registrado en la plataforma.

  • Método: POST

  • URL:

    {{backend_public_apis}}/core/update-stage

  • Encabezados requeridos:

    • x-api-key: <TU_API_KEY>

    • Content-Type: application/json

  • Cuerpo de la petición (JSON):

    Campo
    Tipo
    Obligatorio
    Descripción

    ticket_id

    string

    Sí

    Identificador único del ticket al que se le actualizará la etapa.

    stage_id

    integer

    No

    Nombre de la etapa a asignar (debe corresponder a una etapa válida en la plataforma).

  • Ejemplo de cuerpo:

    {
  "ticket_id": "3ce9a977-53bc-4837-ae9c-7704b4fc76fc",
  "stage_id": "2" // puede ser null
}

  • Respuesta exitosa (HTTP 200):

    {
  "status": "success",
  "message": "Stage updated successfully."
}

  • Códigos de error más comunes:

    • 400 Bad Request

      • Falta ticket_id o stage_id.

      • stage_id no coincide con ninguna etapa válida en la plataforma.

    • 401 Unauthorized

      • No se incluyó x-api-key o la clave es inválida.

    • 404 Not Found

      • No existe ningún ticket con el ticket_id proporcionado.

    • 500 Internal Server Error

      • Error interno del servidor. Retorna:

        jsonCopyEdit{
  "status": "error",
  "message": "Internal server error."
}

2.3. Asignar equipo o agente a ticket (update-agent-assigment)

  • Descripción breve: Asigna o reasigna un ticket a un equipo o agente específico para que atienda el caso.

  • Método: POST

  • URL:

    {{backend_public_apis}}/core/update-agent-assigment

  • Encabezados requeridos:

    • x-api-key: <TU_API_KEY>

    • Content-Type: application/json

  • Cuerpo de la petición (JSON):

    Campo
    Tipo
    Obligatorio
    Descripción

    ticket_id

    string (UUID)

    Sí

    Identificador único del ticket al que se le asignará el equipo/ agente.

    team_id

    string (UUID)

    No

    Identificador del equipo, del cual se buscara un agente disponible que asumirá la responsabilidad del ticket.

  • Ejemplo de cuerpo:

    {
  "ticket_id": "3ce9a977-53bc-4837-ae9c-7704b4fc76fc",
  "team_id": "143e9bc3-33a9-48eb-b6f8-705eb81a9399"
}

  • Respuesta exitosa (HTTP 200):

    jsonCopyEdit{
  "status": "success",
  "message": "Agent assignment updated successfully."
}

  • Códigos de error más comunes:

    • 400 Bad Request

      • Falta ticket_id o team_id.

      • Formato de alguno de los campos inválido.

    • 401 Unauthorized

      • No se incluyó x-api-key o la clave es inválida.

    • 404 Not Found

      • No existe ningún ticket con el ticket_id proporcionado, o el team_id indicado no corresponde a ningún equipo/agente válido.

    • 500 Internal Server Error

      • Error interno del servidor. Retorna:

        jsonCopyEdit{
  "status": "error",
  "message": "Internal server error."
}

3. Notas generales y convenciones

  1. URL base ({{backend_public_apis}}): En todos los ejemplos aparece la variable {{backend_public_apis}}. Asegúrate de reemplazarla por la siguiente URL: https://prod-aichain-public-apis-2419347993.us-central1.run.app .

  2. Códigos de respuesta HTTP comunes:

    Código
    Significado
    Descripción

    200

    OK

    La operación fue exitosa.

    400

    Bad Request

    Parámetros faltantes o con formato inválido.

    401

    Unauthorized

    Falta de encabezado x-api-key o clave inválida.

    404

    Not Found

    El recurso indicado (ticket, equipo, etapa, etc.) no existe.

    500

    Internal Server Error

    Error inesperado en el servidor. Contiene:

    { 
    "status": "error",
    "message": "Internal server error."
}

  3. Encabezados adicionales recomendados:

    • Accept: application/json

    • User-Agent: NombreDeTuApp/Versión (opcional para trazabilidad)

  4. Validaciones de campo:

    • Para todos los endpoints, los campos marcados como “Obligatorio” no pueden omitirse ni enviarse como null o cadena vacía.

    • Si se envía un valor inválido (por ejemplo, un stage_name que no corresponda a ninguna etapa configurada), se recibirá un 400 Bad Request y un mensaje explicando qué parámetro es inválido.

  5. Ejemplos concisos:

    • En la documentación anterior se muestran ejemplos mínimos de cuerpos y respuestas. En producción, valida que los ejemplos se ajusten a la versión actual de la API y a cualquier configuración especial que tu organización tenga (nombres de etapas, identificación de equipos/agentes, etc.).

PreviousConfiguración del Agente IA y Webhook de Mensajes

Last updated