← Frepi Developers

Mensajes por evento — API de automatizaciones v1

Versión 1.0 · POST / GET · Autenticación Bearer con una llave frk_live_…

Tu sistema llama a Frepi cuando su cliente hace algo (un depósito, un pedido, una cita). La llamada trae el teléfono, las variables y la lógica de una conversación corta: una plantilla aprobada, qué hace cada botón y, si quieres, un formulario de WhatsApp. Una persona aprueba cada lógica nueva una vez en Frepi. Después Frepi envía y sigue las respuestas.

1 · La llave

• Créala en Frepi: Automatizaciones › Mensajes por evento › Llaves › Nueva llave. Solo la ve quien puede configurar el espacio, y se muestra una sola vez.
• Vale para un espacio, las líneas que elijas y los permisos automations:run (enviar, cancelar) y automations:read (leer envíos). Vence a los 3, 6 o 12 meses.
• En cada llamada Frepi revisa que quien creó la llave siga activo y con permiso en ese espacio.

Authorization: Bearer frk_live_…

2 · Rutas

Ningún teléfono va en una URL. Todas las respuestas llevan Cache-Control: private, no-store.

3 · Un envío

curl -X POST https://ejemplo.frepi.ai/api/automations/v1/runs \
  -H "Authorization: Bearer $FREPI_AUTOMATION_KEY" \
  -H "Idempotency-Key: dep-8812" \
  -H "Content-Type: application/json" \
  -d @envio.json

{
  "line": "+57 601 555 0100",
  "to": { "phone": "+573001234567", "name": "Ana" },
  "external_ref": "DEP-8812",
  "variables": { "nombre": "Ana", "monto": "$250.000", "referencia": "DEP-8812" },
  "logic": {
    "declare": { "nombre": { "type": "text", "max": 40 } },
    "start": { "type": "template", "template": "deposito_recibido",
               "buttons": { "Sí, invertir": "invertir", "No, gracias": "gracias", "Hablar con asesor": "asesor" },
               "wait": "24h" },
    "steps": {
      "invertir": { "type": "form", "form": "frm_invierte_deposito", "text": "Completa este formulario corto.",
                    "button": "Abrir formulario", "wait": "2h", "on_complete": "listo" },
      "listo":    { "type": "text", "text": "¡Gracias, {{answers.nombre|amigo}}! Un asesor te escribe hoy." },
      "gracias":  { "type": "text", "text": "Perfecto. Aquí estamos si nos necesitas." },
      "asesor":   { "type": "handoff", "to": "team", "text": "Te paso con un asesor.", "tag": "pide_asesor" }
    }
  }
}

Un formulario en línea (contrato 1.1)

En un paso form, form es la referencia de un formulario de «Formularios» (frm_…) o un formulario nuevo escrito en la misma llamada. Frepi lo crea y lo publica en la cuenta de WhatsApp de la línea cuando una persona aprueba la lógica; antes no se publica nada.

"invertir": {
  "type": "form", "text": "Completa este formulario corto.", "button": "Abrir formulario", "wait": "2h",
  "on_complete": "listo",
  "form": {
    "name": "Invierte tu depósito",
    "submit": "Enviar",
    "fields": [
      { "token": "nombre", "label": "Nombre", "type": "text", "required": false },
      { "token": "plazo", "label": "¿A qué plazo?", "type": "option",
        "options": [ { "id": "tres", "title": "3 meses" }, { "id": "seis", "title": "6 meses" } ] },
      { "token": "fecha", "label": "¿Cuándo te llamamos?", "type": "date" }
    ]
  }
}

• Hasta 10 campos de tipo text, option (2 a 20 opciones) o date. required es true si no lo envías. El token es lo que trae la respuesta ({{answers.token}}); una opción responde su id, una fecha AAAA-MM-DD.
• El mismo contenido es el mismo formulario: repetirlo no crea otro. Cambiar un texto o un campo es una lógica nueva (otra aprobación) y un formulario nuevo. Un formulario publicado no se edita.
• Mientras se publica, el envío espera en ese paso. Si WhatsApp rechaza el formulario, la llamada responde 422 validation_failed con form_unavailable hasta que una persona lo reintente en «Formularios», y un envío que esperaba termina failed / line_ineligible.
• Errores propios: form_fields_unsupported, form_too_many_fields, form_field_invalid, cada uno con el path del campo.

4 · Aprobar una vez

1. La primera llamada con una lógica nueva responde 409 logic_pending_approval con logic_id y approve_url. No se envía nada.
2. Una persona abre approve_url en Frepi y pulsa «Aprobar». Una llave nunca puede aprobar.
3. Desde ahí, cada llamada con la misma lógica se envía de inmediato. Puedes mandar "automation_id": "aut_…" en vez de line + logic.
4. Cambiar la línea, el modo del agente o la lógica pide otra aprobación.
5. Aprobar una lógica con un formulario en línea muestra sus campos y lo publica en la cuenta de WhatsApp de la línea.

5 · Idempotencia y límites

• Idempotency-Key es obligatorio. La misma llave con el mismo cuerpo responde 202 con replayed: true y no envía nada otra vez; con otro cuerpo, 409 idempotency_conflict.
• Por llave: 60 envíos por minuto y 5.000 por día. Por teléfono: 3 envíos de la API cada 24 h. Hasta 20 lógicas esperando aprobación por llave. 429 trae Retry-After.

6 · Errores

Todo error es {"error": {"code", "message", …}}. Un 422 validation_failed trae errors[] con cada problema, su code y su path. Lee el code, nunca el message; un código que no conoces se trata por su estado HTTP.

¿Quieres enviar un formulario de una campaña que ya lanzaste en Frepi? Llama a la campaña por su id: Enviar un formulario desde tu sistema (campaign_id, contrato 1.2).