POST

Endpoint /api/conectia

URL

https://api.intuia.ai/api/conectia

Descripción

Este es el endpoint principal para comunicarse con el agente de IA de Intuia.ai. Permite enviar mensajes de usuarios y recibir respuestas del agente. Mantiene el contexto de la conversación utilizando el NumeroIdentificacion como identificador del usuario.

Autenticación

Requiere el header x-api-key con una API key válida proporcionada por Intuia.ai.

Parámetros

Este endpoint acepta los 6 parámetros obligatorios listados a continuación, pero también permite enviar cualquier cantidad de parámetros adicionales que sean necesarios para el funcionamiento del agente. Todos los parámetros enviados serán reenviados al webhook correspondiente.

Parámetros obligatorios:

NumeroIdentificacion(string)Requerido

Identificador único del usuario o conversación. Se utiliza para mantener el contexto entre mensajes.

MensajeUsuario(string)Requerido

El mensaje o pregunta que el usuario envía al agente de IA.

MensajeID(string)Requerido

Identificador único para este mensaje específico. Útil para seguimiento y depuración.

TelefonoUsuario(string)Requerido

Número de teléfono del usuario en formato internacional sin el signo + (ej: 573001234567).

TipoMensaje(string)Requerido

Tipo de contenido del mensaje. Puede tener 3 valores: audio, image o text.

url_media(string)Requerido

URL del archivo cuando TipoMensaje es audio o image (puede ser vacío si es text).

Parámetros adicionales:

Puede enviar cualquier parámetro adicional que necesite para el funcionamiento del agente. Ejemplos:

Agente(string)

Slug del agente creado al que se dirige el mensaje.

NombreUsuario(string)

Nombre del usuario para personalizar las respuestas.

ContextoAdicional(string)

Información adicional que pueda ser útil para el agente.

Respuesta

La respuesta incluye el mensaje del agente de IA y metadatos relacionados:

{
  "MensajeAI": [
    "Esta es la primera parte de la respuesta.",
    "Esta es la segunda parte de la respuesta.",
    "¿Le puedo ayudar con algo más?"
  ],
  "cartera": "slug de la cartera",
  "agente": false
}

Ejemplos

curl -X POST https://api.intuia.ai/api/conectia   -H "x-api-key: SU_API_KEY_AQUI"   -F "NumeroIdentificacion=12345678"   -F "MensajeUsuario=¿Cuál es el horario de atención?"   -F "MensajeID=msg_123456"   -F "TelefonoUsuario=573001234567"   -F "Agente=mi-agente-slug"   -F "TipoMensaje=text"   -F "url_media="   -F "NombreUsuario=Juan Pérez"   -F "ContextoAdicional=Cliente preferencial"

// Usando fetch con FormData
const formData = new FormData();

// Parámetros obligatorios
formData.append('NumeroIdentificacion', '12345678');
formData.append('MensajeUsuario', '¿Cuál es el horario de atención?');
formData.append('MensajeID', 'msg_123456');
formData.append('TelefonoUsuario', '573001234567');
formData.append('Agente', 'mi-agente-slug');
formData.append('TipoMensaje', 'text');
formData.append('url_media', '');

// Parámetros adicionales (opcionales)
formData.append('NombreUsuario', 'Juan Pérez');
formData.append('ContextoAdicional', 'Cliente preferencial');
formData.append('CanalComunicacion', 'WhatsApp');

const response = await fetch('https://api.intuia.ai/api/conectia', {
  method: 'POST',
  headers: {
    'x-api-key': 'SU_API_KEY_AQUI'
    // No es necesario especificar Content-Type cuando se usa FormData
  },
  body: formData
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.intuia.ai/api/conectia"
headers = {
    "x-api-key": "SU_API_KEY_AQUI"
    # No es necesario especificar Content-Type cuando se usa multipart/form-data
}

# Datos a enviar (parámetros obligatorios y adicionales)
data = {
    # Parámetros obligatorios
    "NumeroIdentificacion": "12345678",
    "MensajeUsuario": "¿Cuál es el horario de atención?",
    "MensajeID": "msg_123456",
    "TelefonoUsuario": "573001234567",
    "Agente": "mi-agente-slug",
    "TipoMensaje": "text",
    "url_media": "",
    
    # Parámetros adicionales (opcionales)
    "NombreUsuario": "Juan Pérez",
    "ContextoAdicional": "Cliente preferencial",
    "CanalComunicacion": "WhatsApp"
}

# Realizar la petición POST
response = requests.post(url, headers=headers, data=data)
print(response.json())

Notas adicionales

El contexto de la conversación se mantiene durante 24 horas.
Las respuestas pueden tardar hasta 5 segundos en casos de consultas complejas.
Se recomienda implementar un mecanismo de reintento en caso de errores de conexión.
El parámetro TelefonoUsuario debe incluir el código de país sin el signo +.