Referencia API

Referencia completa de los 47 endpoints. Todas las solicitudes usan HTTPS y devuelven JSON. Documentación Authorization: Bearer YOUR_API_KEY.

URL de Destino https://app.convoai.cloud/api/v1/

Agentes

Un Agente es una instancia de IA configurada conectada a un número de WhatsApp. Los Agentes tienen una base de conocimiento, configuración de personalidad e historial de conversaciones.

Aún no hay facturas.

json

{
  "id":             "agt_01HXYZ1234ABCD",
  "name":           "My Sales Agent",
  "status":         "active",          // active | paused | draft
  "phone_number":   "+14155550123",
  "waba_id":        "123456789012345",
  "language":       "en",
  "ai_model":       "convoai-standard",
  "timezone":       "America/New_York",
  "knowledge_count": 12,
  "conversations_today": 47,
  "created_at":    "2026-01-15T10:30:00Z",
  "updated_at":    "2026-05-10T08:14:22Z"
}

GET/agents/Agentes

POST/agents/Crear Agente

GET/agents/{id}/Agentes activos

PATCH/agents/{id}/Actualiza cuando quieras

DELETE/agents/{id}/Eliminar cuenta

POST/agents/{id}/activate/Completa la configuración para activar

POST/agents/{id}/pause/Punto de entrada de mensajes

POST /agents/ — Mín. 8 caracteres

Campo	Tipo	Requerido	Suscripción
name	string	Opt-in requerido:	Nombre visible del agente
phone_number_id	string	Opt-in requerido:	ID de Número de Teléfono
waba_id	string	Opt-in requerido:	Política de WhatsApp Business
access_token	string	Opt-in requerido:	Token de acceso de usuario de sistema Meta (almacenado encriptado)
language	string	opcional	Código ISO 639-1. Predeterminado `"en"`
timezone	string	opcional	Zona horaria Predeterminado `"UTC"`
personality	string	opcional	Instrucciones de texto libre para el tono y personalidad de la IA
business_name	string	opcional	Activo (incluido en el contexto de IA)

Conversaciones

Una Conversación representa una sesión de mensajería WhatsApp de 24 horas con un solo contacto. Contiene todos los mensajes intercambiados en esa ventana, más metadatos de IA (intención, puntuación de lead, estado de resolución).

Conversaciones

json

{
  "id":           "conv_01HABC9876WXYZ",
  "agent_id":     "agt_01HXYZ1234ABCD",
  "contact_id":   "cnt_01HJKL5678MNOP",
  "status":       "open",             // open | resolved | handed_off
  "channel":      "whatsapp",
  "lead_score":   87,
  "intent":       "booking_inquiry",
  "ai_handled":   true,
  "messages_count": 14,
  "started_at":   "2026-05-10T09:00:00Z",
  "last_message_at": "2026-05-10T09:47:12Z"
}

GET/agents/{agent_id}/conversations/Conversaciones

GET/conversations/{id}/Conversaciones

GET/conversations/{id}/messages/Nuevos mensajes y respuestas en tus conversaciones.

POST/conversations/{id}/resolve/Conversaciones IA

POST/conversations/{id}/handoff/Transferencia humana fluida

POST/conversations/{id}/resume-ai/Reanudar IA después de transferencia

GET /agents/{agent_id}/conversations/ — Parámetros de consulta

Parámetro	Tipo	Suscripción
status	string	Estado de disponibilidad `open`, `resolved`, `handed_off`
since	ISO 8601	Gestiona 1 conversación a la vez
until	ISO 8601	Devolver conversaciones iniciadas antes de esta fecha/hora
lead_score_min	integer	Puntuación mínima de lead (0–100)
page	integer	ID de Número de Teléfono Predeterminado `1`
page_size	integer	Resultados por página. Máx: `100`. Predeterminado `20`

Contactos

Los Contactos son las personas que han enviado mensajes a tus agentes. ConvoAI crea automáticamente un registro de contacto en el primer mensaje y lo enriquece con el tiempo a partir de los datos de conversación.

Aún no hay facturas.

json

{
  "id":           "cnt_01HJKL5678MNOP",
  "agent_id":     "agt_01HXYZ1234ABCD",
  "phone":        "+14155559876",
  "name":         "Sofia Ramirez",
  "email":        "sofia@example.com",   // null if not collected
  "tags":         ["hot-lead", "enterprise"],
  "pipeline_stage": "qualified",
  "lead_score":   91,
  "opted_in":     true,
  "last_seen_at": "2026-05-10T09:47:12Z",
  "created_at":   "2026-04-01T14:00:00Z",
  "metadata": {
    "company": "Acme Inc",
    "budget":  "$5k-$10k"
  }
}

GET/agents/{agent_id}/contacts/Por favor contacta a

POST/agents/{agent_id}/contacts/Por favor contacta a

GET/contacts/{id}/Por favor contacta a

PATCH/contacts/{id}/Por favor contacta a

DELETE/contacts/{id}/Elimina permanentemente tu cuenta, agentes y todos los datos.

POST/contacts/{id}/tags/Contactos

DELETE/contacts/{id}/tags/{tag}/Eliminar archivo

POST/contacts/{id}/opt-out/Aún no hay facturas.

POST /agents/{agent_id}/contacts/ — Mín. 8 caracteres

Campo	Tipo	Requerido	Suscripción
phone	string	Opt-in requerido:	Formato E.164: `+14155559876`
name	string	opcional	Nombre del Bot
email	string	opcional	Correo electrónico
tags	string[]	opcional	Array de cadenas de etiquetas
pipeline_stage	string	opcional	Pipeline de CRM y puntuación automática de leads
metadata	object	opcional	Pares clave-valor arbitrarios almacenados en el contacto

Conocimiento

Los documentos de conocimiento son indexados por el motor RAG (Generación Aumentada por Recuperación). Cada vez que el agente IA genera una respuesta, busca primero en la base de conocimiento para fundamentar la respuesta en tu contenido.

Latencia de indexación: Los nuevos documentos se indexan en En menos de 2 segundos. y se aplican al siguiente mensaje entrante. No hay paso de re-entrenamiento.

Sin documentos de conocimiento

json

{
  "id":          "kdoc_01HDEF2345GHIJ",
  "agent_id":    "agt_01HXYZ1234ABCD",
  "title":       "Pricing Plans 2026",
  "doc_type":    "text",              // text | url | file
  "content":     "Starter $49/mo includes...",
  "word_count":  320,
  "is_active":   true,
  "indexed_at":  "2026-05-10T09:05:12Z",
  "created_at":  "2026-05-10T09:05:00Z"
}

GET/agents/{agent_id}/knowledge/Sin documentos de conocimiento

POST/agents/{agent_id}/knowledge/Crear Agente

GET/knowledge/{id}/Recuperar un documento

PATCH/knowledge/{id}/Actualizar un documento (activa re-indexación)

DELETE/knowledge/{id}/Eliminar y remover del índice

POST/knowledge/{id}/reindex/Forzar re-indexación

POST /agents/{agent_id}/knowledge/ — Mín. 8 caracteres

Campo	Tipo	Requerido	Suscripción
title	string	Opt-in requerido:	Título legible del documento
doc_type	string	Opt-in requerido:	`text`, `url`, Tu `file`
content	string	Opt-in requerido:	Requerido si `doc_type` s `text`
url	string	Opt-in requerido:	Requerido si `doc_type` s `url`. Rastreamos e indexamos la página.
is_active	boolean	opcional	Si incluir en búsquedas RAG. Predeterminado `true`

Uso

Envía mensajes de WhatsApp salientes programáticamente desde tu backend. Los mensajes deben cumplir con la Política de WhatsApp Business de Meta — el texto libre solo se puede enviar dentro de la ventana de servicio al cliente de 24 horas. Fuera de esa ventana, usa un template tipo.

Opt-in requerido: Solo puedes enviar mensajes a contactos que hayan optado explícitamente por recibir comunicaciones de tu negocio. ConvoAI rechazará envíos a contactos dados de baja con 403 Forbidden.

POST/agents/{agent_id}/messages/Mensajes IA

GET/messages/{id}/Plantillas de mensajes aprobadas:

POST /agents/{agent_id}/messages/ — Mín. 8 caracteres

Campo	Tipo	Requerido	Suscripción
to	string	Opt-in requerido:	Número de teléfono del destinatario en formato E.164
type	string	Opt-in requerido:	`text` Tu `template`
text	string	Opt-in requerido:	Cuerpo del mensaje. Requerido cuando `type` s `text`. (máx. 300 caracteres)
template_name	string	Opt-in requerido:	Nombre de plantilla aprobada por Meta. Requerido cuando `type` s `template`.
template_params	string[]	opcional	Sustituciones de variables para marcadores de plantilla, en orden.
language_code	string	opcional	Código de idioma BCP 47 para plantilla. Predeterminado `"en_US"`

Costo por mensaje

{
  "to":   "+14155559876",
  "type": "text",
  "text": "Hi Sofia! Your appointment on May 15 is confirmed. Reply CANCEL to cancel."
}

Mensajes de plantilla:

{
  "to":              "+14155559876",
  "type":            "template",
  "template_name":   "appointment_reminder",
  "template_params": ["Sofia", "May 15", "10:00 AM"],
  "language_code":   "en_US"
}

Analíticas

Obtén métricas de rendimiento de un agente o de toda la cuenta. Todas las métricas están pre-agregadas y se devuelven al instante sin paginación.

GET/agents/{agent_id}/analytics/Resumen para rango de fechas

GET/agents/{agent_id}/analytics/conversations/Conversaciones

GET/agents/{agent_id}/analytics/leads/Calificación de Prospectos

GET/agents/{agent_id}/analytics/csat/Limitación:

json · GET /analytics/ respuesta

{
  "period":              "2026-05-01 / 2026-05-10",
  "conversations_total":  1247,
  "ai_resolved_pct":      91.4,
  "handoff_pct":          8.6,
  "leads_qualified":      284,
  "appointments_booked":  67,
  "avg_response_time_ms": 1840,
  "avg_csat":             4.7,
  "messages_sent":        5832,
  "messages_received":    4109
}

Error

ConvoAI usa códigos de estado HTTP estándar. Todos los errores devuelven un cuerpo JSON con error y detail campos.

json · respuesta de error

{
  "error":  "validation_error",
  "detail": "The 'to' field must be a valid E.164 phone number.",
  "field":  "to",        // present for field-specific errors
  "code":   "invalid_phone"
}

Estado	Ingresar código	Advertencia
400	`bad_request`	JSON malformado o parámetro requerido faltante
400	`validation_error`	Un valor de campo es inválido (tipo, formato o restricción incorrectos)
401	`authentication_required`	Faltante o malformado `Authorization` encabezado
401	`invalid_api_key`	La clave API no es reconocida o ha sido revocada
403	`forbidden`	Autenticado pero no permitido (ej. acceso entre cuentas)
403	`contact_opted_out`	Se intentó enviar un mensaje a un contacto dado de baja
403	`plan_limit`	La acción requiere un plan de suscripción superior
404	`not_found`	El recurso solicitado no existe
409	`conflict`	El recurso ya existe (ej. número de teléfono duplicado)
422	`unprocessable`	Solicitud entendida pero no se puede procesar (ej. ventana de WhatsApp expirada)
429	`rate_limited`	Demasiadas solicitudes. Ver `Retry-After` encabezado.
500	`server_error`	Error interno. Reportado automáticamente a nuestro equipo.
503	`meta_unavailable`	La API de WhatsApp de Meta es inaccesible. Reintenta con retroceso exponencial.

Claves de Idempotencia Activas

Todos POST las solicitudes aceptan un Idempotency-Key encabezado. Enviar la misma clave dos veces en 24 horas devuelve la respuesta original sin realizar la acción de nuevo. Usa esto para reintentar solicitudes fallidas de forma segura.

bash

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_xxx/messages/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-confirm-12345" \
  -H "Content-Type: application/json" \
  -d '{"to":"+14155559876","type":"text","text":"Your order is confirmed!"}'