API de Monkeia Flow

Conectá tu bot de ManyChat (u otro sistema) con Monkeia Flow: respuestas con IA usando tu prompt, eventos de bots de botones para medir embudos y llenar Ventas, tareas de IA y control de las conversaciones.

Autenticación

Cada cuenta tiene su clave del API. La ves en el panel, en Integración → Avanzado → Clave del API (dueño o administrador). Mandala en uno de estos encabezados:

Authorization: Bearer TU_CLAVE
# o
X-API-Key: TU_CLAVE

Respuestas y errores

Las respuestas son JSON con un campo status. Si algo falla, viene error (un código fijo) y a veces detail (texto para entender qué pasó).

Responder con IA

Manda el mensaje de un contacto y recibe la respuesta de la IA con el prompt publicado de tu cuenta. Monkeia guarda la memoria de cada conversación, aplica tus reglas (pausa al responder una persona, fuera de horario, palabras clave) y usa tu cuenta de OpenAI.

Cuerpo

Ejemplo

curl -X POST https://apikey.monkeia.com/v1/generate \
  -H "Authorization: Bearer TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "123456", "message": "Hola, ¿tienen cupo mañana?", "channel": "whatsapp" }'

Respuesta (200)

{
  "status": "completed",
  "output_text": "{\"mensaje\":\"¡Hola! Sí, mañana tenemos…\",\"status\":\"Conversando\"}",
  "message": "¡Hola! Sí, mañana tenemos…",
  "json": { "mensaje": "¡Hola! Sí, mañana tenemos…", "status": "Conversando" },
  "conversation_id": "…",
  "request_id": null,
  "usage": { "input_tokens": 812, "output_tokens": 64 }
}

Eventos (bots de botones)

Para bots de ManyChat con botones, sin IA (o los pasos con botones antes de la IA). Mandá un evento en cada paso importante del flujo: Monkeia guarda el contacto con sus datos, lo cuenta en el Embudo, deja una línea en su conversación y, si configuraste una etapa para ese paso, lo mueve en Ventas.

Cuerpo

Ejemplo

{
  "subscriber_id": "{{Contact Id}}",
  "event": "Eligió curso",
  "name": "{{Full Name}}",
  "phone": "{{Phone}}",
  "fields": { "curso": "{{curso}}", "sede": "{{sede}}" }
}

Respuesta (200)

{ "status": "ok", "contact_id": "…", "conversation_id": "…", "event": "eligio_curso", "moved_to_stage": null }

Hasta 60 pasos distintos por cuenta y 40 campos por evento. Un contacto que repite un paso cuenta una sola vez en el embudo.

Distancia y tiempo (Google Maps)

Kilómetros y minutos en carro entre dos puntos. Acepta los enlaces de Google Maps o Waze que manda el cliente (también los cortos maps.app.goo.gl), coordenadas o direcciones escritas. Activalo en Integración → Google Maps. Con Maps activado, la IA también tiene la herramienta calcular_ruta para usarla sola durante la conversación.

// 200
{ "status": "ok", "distance_km": 23.5, "minutes": 31 }

Sin clave propia se usa la de Monkeia con un tope de rutas por mes (429 maps_limit al llegar). Otros errores: 403 maps_disabled, 400 bad_origin / bad_destination, 404 no_route.

Tareas de IA

Una llamada a la IA sin memoria para resumir, clasificar o sacar datos. Las tareas (instrucciones y slug) se crean en el panel, en Tareas de IA.

// 200
{ "status": "completed", "output_text": "…", "json": { … }, "message": "…", "missing_variables": [], "usage": { … } }

Conversaciones

Para controlar la conversación de un contacto desde ManyChat. Cuerpo: { "user_id": "{{Contact Id}}", "channel": "whatsapp" }.

Enlaces de WhatsApp

Los enlaces que creás en Lanzamientos → Enlaces abren WhatsApp con el mensaje prellenado y una marca (ref: código). Así la conversación queda unida al enlace y a sus UTM, y ves en el panel qué chats vienen de cada campaña o sitio web. Se guarda el clic con las UTM, sin la IP.

Configurar en ManyChat

1. En el flujo, agregá Acción → Solicitud externa (External Request), tipo POST.
2. URL: https://apikey.monkeia.com/v1/generate (IA) o https://apikey.monkeia.com/v1/events (bot de botones).
3. Encabezados: Authorization = Bearer TU_CLAVE.
4. Cuerpo: el JSON del endpoint, con las variables de ManyChat (botón { }).
5. Tocá Probar la solicitud: con IA tenés que ver "status": "completed" (o queued con delivery: "manychat"); con eventos, "status": "ok".

En el panel, Integración y Embudo tienen el texto listo para copiar con tu URL y tu clave.

Límites y buenas prácticas

• Cuerpo: hasta 100 KB en /v1/generate y /v1/tasks; 32 KB en /v1/events.
• ManyChat espera unos 10 segundos por respuesta: si tu prompt usa herramientas o tarda, usá delivery: "manychat".
• Mandá un request_id único por mensaje para que los reintentos no dupliquen respuestas.
• Guardá la clave solo en ManyChat o en tu servidor.
• ¿Dudas o algo no anda? Escribinos desde Soporte en el panel.