API y Desarrollador

Lo que puedes construir

La API de ConvoAI te da control programatico completo sobre cada parte de la plataforma. Casos de uso comunes:

Cómo Funciona

ConvoAI se ubica entre la API de WhatsApp Cloud de Meta y tus clientes. Tu aplicacion interactua con la API REST de ConvoAI y recibe eventos via webhooks.

1. Un cliente potencial envía un mensaje a tu número de WhatsApp. La Cloud API de Meta lo enruta a ConvoAI al instante. Sin demoras. Sin oportunidades perdidas.
2. El agente de IA de ConvoAI busca en la base de conocimiento, genera una respuesta contextual usando su motor de IA y la envia de vuelta a traves de la API de WhatsApp.
3. ConvoAI envia un webhook a tu URL configurada para cada evento significativo (mensaje recibido, lead calificado, cita agendada, transferencia activada).
4. Tu aplicacion tambien puede enviar datos a ConvoAI — actualizar conocimiento, enviar mensajes o leer el historial de conversaciones — a traves de la API REST en cualquier momento.

Documentación

Todas las solicitudes a la API requieren una clave secreta pasada como token Bearer en el Authorization encabezado. Las claves estan vinculadas a tu cuenta y heredan los limites de tu suscripcion.

Generar clave API

1. En tu panel de ConvoAI, ve a
2. Ve a Configuración → Conectar
3. Haz clic Generar clave API, asignale un nombre descriptivo
4. Copia la clave inmediatamente — solo se muestra una vez

Formato de clave

Las claves en produccion tienen el prefijo ck_live_. Las claves de prueba (modo sandbox, no se envian mensajes reales de WhatsApp) tienen el prefijo ck_test_.

# All requests require this header
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Example curl
curl https://app.convoai.cloud/api/v1/agents/ \
  -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Verifica tu correo electrónico

curl https://app.convoai.cloud/api/v1/me/ \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "usr_01HXYZ1234ABCD",
  "email": "you@yourbusiness.com",
  "plan": "pro",
  "agents_count": 2,
  "api_version": "v1.4"
}

Comenzar

Ve de cero a enviar tu primer mensaje de WhatsApp activado por API en menos de 5 minutos.

Paso 1 — Lista tus agentes

curl https://app.convoai.cloud/api/v1/agents/ \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "count": 1,
  "results": [
    {
      "id": "agt_01HXYZ1234ABCD",
      "name": "My Sales Agent",
      "status": "active",
      "phone_number": "+14155550123",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Sin documentos de conocimiento

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_01HXYZ1234ABCD/knowledge/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer 2026 Pricing",
    "content": "Our summer plans start at $49/mo. Enterprise quotes available.",
    "doc_type": "text"
  }'

Paso 3 — Envia un mensaje a un contacto

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_01HXYZ1234ABCD/messages/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155559876",
    "type": "text",
    "text": "Hi! Your order has been confirmed. Reply anytime if you need help."
  }'

{
  "message_id": "msg_01HABC9876WXYZ",
  "status": "queued",
  "to": "+14155559876",
  "queued_at": "2026-05-10T14:22:01Z"
}

Paso 4 — Registra un webhook

curl -X POST https://app.convoai.cloud/api/v1/agents/agt_01HXYZ1234ABCD/webhooks/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/convoai",
    "events": ["lead.qualified", "appointment.booked", "handoff.triggered"],
    "secret": "whsec_your_signing_secret"
  }'

Limitación de tasa

Los limites de tasa se aplican por clave API. Todas las respuestas incluyen encabezados de limite de tasa.

Cuando se excede un limite, la API retorna 429 Too Many Requests. Inspecciona los encabezados de respuesta para determinar cuando reintentar:

X-RateLimit-Limit:     300
X-RateLimit-Remaining: 247
X-RateLimit-Reset:     1715349600
Retry-After:           12

Versionado de la API

La version estable actual es v1.4. La version se especifica en la ruta del URL: https://app.convoai.cloud/api/v1/.

Nunca haremos cambios incompatibles dentro de una version mayor. Cuando se lanza una nueva version mayor, la version anterior se mantiene soportada por un minimo de 12 meses. Las depreciaciones de cambios incompatibles se anuncian por correo electronico, el changelog y un Deprecation Tiempo de respuesta

Documentación para Desarrolladores

Al integrarte con la API de ConvoAI aceptas nuestras politicas de desarrollador. Lee cada documento antes de ir a produccion — especialmente la Politica de Uso Aceptable, que rige lo que puedes y no puedes enviar a traves de WhatsApp.

8 pasos