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 http(s) pública del archivo cuando TipoMensaje es audio o image. Vacío si es text. Cualquier otro valor se rechaza con HTTP 400.

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.

Validación de parámetros

Antes de reenviar el mensaje al agente, la API comprueba la forma de cada campo. Si alguno no cumple, responde HTTP 400 sin procesar el mensaje y sin devolver los valores recibidos.

NumeroIdentificacion: letras, dígitos y . _ : @ + -, máximo 100 caracteres.
MensajeUsuario: texto libre, máximo 8.000 caracteres. Su contenido no se filtra.
MensajeID: letras, dígitos y . _ : = / + -, máximo 128 caracteres.
TelefonoUsuario: entre 7 y 15 dígitos con código de país; se toleran espacios, guiones y paréntesis.
TipoMensaje: una sola palabra (text, image, audio, video, document…).
url_media: vacío, o una URL absoluta http:// o https:// a un host público, sin credenciales, máximo 2.048 caracteres.
Agente: slug con letras, dígitos, _ y -.
Cualquier otro campo: nombre con letras, dígitos y _ . - (máximo 64 caracteres), valor de texto de hasta 10.000 caracteres sin caracteres de control. Se admiten hasta 40 campos por solicitud.

Ejemplo de respuesta cuando un campo no cumple:

{
  "error": "Parámetros inválidos",
  "detalles": [
    {
      "campo": "url_media",
      "motivo": "debe ser una URL absoluta (http:// o https://) o vacío"
    }
  ],
  "cartera": "",
  "agente": false
}

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 +.
Las solicitudes con parámetros que no cumplen el formato indicado reciben HTTP 400 con el campo y el motivo; ver "Validación de parámetros".