Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioConfiguración general e IA

API: Aplicaciones aliadas (mensajería para otros sistemas)

Para qué sirve#

Una aplicación aliada es un sistema tuyo (o de un tercero) que usa la mensajería de Connecto —WhatsApp, Messenger, Instagram, Telegram y el chat web— sin que sus clientes tengan que ser clientes directos de Connecto. La aplicación crea una cuenta de Connecto por cada uno de sus clientes; cada cuenta tiene sus propias líneas, plantillas y llaves, y la aplicación envía y recibe mensajes por API.

Las líneas de Meta se registran siempre desde Connecto (ventana oficial de Meta), porque los permisos pertenecen a la app de Meta de Connecto. Tu aplicación nunca ve ni guarda tokens de Meta.

Cómo encaja#

  1. Connecto da de alta tu aplicación y te entrega una llave de aplicación (cna_…).
  2. Por cada cliente tuyo que use mensajería, tu aplicación crea una cuenta (POST /api/aliados/v1/cuentas) con su propia referencia. La cuenta no se cobra al cliente: el acuerdo es con tu aplicación.
  3. Tu aplicación crea una llave de API para esa cuenta y, con ella, conecta canales, crea plantillas, se suscribe a webhooks y envía mensajes.
  4. Cada cliente puede tener o no su canal: solo se crea la cuenta de quien lo necesita.
Las direcciones de las cuentas empiezan por el prefijo de tu aplicación (por ejemplo miapp-acme-3f2a.connecto.lat). La API de mensajería de cada cuenta vive en su propia dirección: https://<cuenta>.connecto.lat/api/v1.

Habilitar la conexión desde el panel de tu aplicación (una sola llamada)#

Cuando un administrador de tu aplicación activa «Conectar con Connecto» para uno de sus clientes, tu aplicación hace una llamada y guarda lo que responde:

Bash / Shell
curl -X POST https://connecto.lat/api/aliados/v1/cuentas/cliente-123/habilitar \
  -H "Authorization: Bearer cna_TU_LLAVE_DE_APLICACION" -H "Content-Type: application/json" \
  -d '{"nombre": "Acme S.A.", "correo": "[email protected]"}'
  • Si la cuenta no existe, se crea sola; si estaba suspendida, se reactiva. La llamada espera hasta 25 segundos a que quede lista.
  • Responde 201 con lista: true, la api de la cuenta y la llave de la cuenta (llave), que se entrega una sola vez: tu aplicación debe guardarla.
  • Si la cuenta tarda más, responde 202 con lista: false: vuelve a llamar al mismo punto y continúa (no crea nada dos veces).
  • Llamarla otra vez no cambia nada: responde 200 con llave: null y llave_ya_entregada: true. Con "renovar_llave": true se revoca la llave anterior y se entrega una nueva.
  • Para deshabilitar la conexión de ese cliente: POST /api/aliados/v1/cuentas/cliente-123/deshabilitar (se conservan sus datos y conversaciones; …/habilitar la vuelve a encender).
  • Tu aplicación solo puede volver a encender (habilitar o reactivar) lo que ella misma deshabilitó. Una cuenta que suspendió o canceló Connecto responde 409 y se reactiva escribiéndonos.

Los pasos siguientes explican cada pieza por separado, para quien prefiera manejarlas una a una.

Paso a paso#

1. Crear la cuenta de un cliente#

Bash / Shell
curl -X POST https://connecto.lat/api/aliados/v1/cuentas \
  -H "Authorization: Bearer cna_TU_LLAVE_DE_APLICACION" -H "Content-Type: application/json" \
  -d '{"referencia": "cliente-123", "nombre": "Acme S.A.", "correo": "[email protected]"}'

Responde 202 con el subdominio, la url y la api de la cuenta. Repetir la misma referencia devuelve la cuenta que ya existe (no crea otra). La cuenta tarda unos minutos en pasar de creando a activa: consúltala con GET /api/aliados/v1/cuentas/cliente-123.

2. Crear una llave de API para la cuenta#

Bash / Shell
curl -X POST https://connecto.lat/api/aliados/v1/cuentas/cliente-123/llaves \
  -H "Authorization: Bearer cna_…" -H "Content-Type: application/json" \
  -d '{"nombre": "Mi aplicación", "permisos": ["mensajes:enviar", "mensajes:leer", "plantillas:leer", "plantillas:escribir", "canales:leer", "canales:escribir", "webhooks:leer", "webhooks:gestionar"]}'

Devuelve la llave cnx_… una sola vez. Sin permisos se dan los de mensajería. Estos permisos son explícitos: ningún comodín los cubre.

3. Conectar los canales#

Con la llave de la cuenta (Authorization: Bearer cnx_…) sobre https://<cuenta>.connecto.lat/api/v1:

CanalCómo
WhatsAppPOST /canales/conexion devuelve una dirección de un solo uso (15 minutos). Ábrela en una ventana emergente para la persona dueña del número: inicia sesión en Meta y elige su número. Al terminar llega el webhook canal.conectado.
Chat web (livechat)POST /canales/livechat con los dominios del sitio. Devuelve el codigo (<script …>) para pegar antes de </body>. Se personaliza el botón (icono, texto, color) y el formulario previo (ver abajo).
TelegramPOST /canales/telegram con el bot_token de @BotFather.
Messenger e InstagramPiden elegir las Páginas en la pantalla de Connecto: POST /api/aliados/v1/cuentas/{referencia}/acceso devuelve un enlace de un solo uso (10 minutos) que abre la cuenta en Configuración › Canales.

GET /canales lista los canales de la cuenta (sin tokens).

Formulario previo del chat web (nombre, correo y teléfono)#

Para que el chat pida los datos del visitante antes de iniciar la conversación, agrega formulario al crear el chat (POST /canales/livechat) o al editarlo (PATCH /canales/livechat con el canal_id):

JSON
{ "dominios": ["tusitio.com"], "formulario": { "activo": true, "nombre": true, "correo": true, "telefono": true } }
  • Cada dato puede ser true (se muestra y es obligatorio), false (no se pide) o {"mostrar": true, "obligatorio": false}. Sin indicar datos se piden los tres. Con "activo": false el chat abre sin formulario.
  • El formulario muestra los campos y el botón Iniciar conversación. Se muestra siempre que el visitante no tenga una conversación abierta o activa: la primera vez, y de nuevo cuando la conversación anterior se resolvió.
  • Los datos que escribe el visitante llegan a tu aplicación en el webhook conversacion.creada (y en cada mensaje.recibido), para que tu aplicación cree el contacto en su sistema:
JSON
{ "evento": "conversacion.creada",
  "datos": { "conversacion_id": 212, "contacto_id": 77, "canal_id": 5, "canal": "helplive",
             "contacto":   { "id": 77, "nombre": "Ana Pérez", "correo": "[email protected]", "telefono": "+573001112233" },
             "formulario": { "nombre": "Ana Pérez", "correo": "[email protected]", "telefono": "+573001112233", "asunto": "Ventas" } } }

formulario solo viaja en el chat web e incluye también el asunto y los campos extra si los configuraste. En los demás canales el aviso trae solo contacto.

4. Plantillas (WhatsApp, Messenger, Instagram)#

Bash / Shell
curl -X POST https://<cuenta>.connecto.lat/api/v1/plantillas -H "Authorization: Bearer cnx_…" -H "Content-Type: application/json" \
  -d '{"canal_id": 3, "nombre": "aviso_pedido", "idioma": "es", "categoria": "utility",
       "cuerpo": "Hola {{1}}, recibimos tu pedido {{2}}.", "ejemplos": ["Ana", "PED-123"]}'

Queda PENDING hasta que Meta la apruebe; GET /plantillas?canal_id=3 muestra su estado.

5. Recibir: webhooks#

Bash / Shell
curl -X POST https://<cuenta>.connecto.lat/api/v1/webhooks -H "Authorization: Bearer cnx_…" -H "Content-Type: application/json" \
  -d '{"nombre": "Mi aplicación", "url": "https://miapp.com/hooks/connecto", "eventos": ["mensaje.recibido", "mensaje.estado"], "canales": [3]}'

Responde el secreto (una sola vez). Cada aviso llega firmado: X-Connecto-Signature: v1=<HMAC-SHA256(secreto, marca_de_tiempo + "." + cuerpo)> con X-Connecto-Timestamp. Si no respondes 2xx se reintenta (1 min, 5 min, 30 min, 2 h, 6 h).

Eventos de mensajería: mensaje.recibido (con adjuntos si trae archivo), mensaje.enviado, mensaje.estado (sent, delivered, read, failed) y canal.conectado / canal.desconectado. El filtro canales limita a esos canales los avisos de mensajes, conversaciones y canales (vacío = todos). Los eventos de contactos y de oportunidades (contacto.*, oportunidad.*) no pertenecen a un canal y llegan siempre, estén o no filtrados los canales del webhook. Los archivos que llegan se descargan con GET /mensajes/adjunto?mensaje_id=.

6. Enviar#

Bash / Shell
curl -X POST https://<cuenta>.connecto.lat/api/v1/mensajes/enviar -H "Authorization: Bearer cnx_…" -H "Content-Type: application/json" \
  -d '{"canal_id": 3, "telefono": "+573001112233", "crear_contacto": true, "tipo": "plantilla",
       "plantilla": {"nombre": "aviso_pedido", "idioma": "es", "variables": ["Ana", "PED-123"]}, "referencia_externa": "pedido-123-aviso"}'
  • Texto, imagen, video, documento y audio solo dentro de la ventana de la red (24 horas desde el último mensaje del contacto en WhatsApp, Messenger e Instagram). Pasada la ventana responde 422 ventana_cerrada y hay que enviar una plantilla.
  • En WhatsApp se puede iniciar la conversación con una plantilla indicando el telefono. En Messenger, Instagram, Telegram y chat web solo se responde a quien ya escribió (con la conversacion_id que llega en el webhook mensaje.recibido). El chat web no tiene ventana de 24 horas: se responde mientras el visitante tenga abierta la conversación, con texto, imágenes, video, documentos o audio.
  • referencia_externa hace el envío idempotente: si reintentas con la misma referencia no se manda un segundo mensaje.
  • GET /mensajes/consultar?id= (o ?referencia_externa=) devuelve el estado de entrega.

Reglas y límites#

  • Los mensajes de WhatsApp los cobra Meta según su categoría; esas tarifas las fija Meta, no Connecto.
  • Cada llave tiene un límite por minuto (120 por defecto) y puede limitarse a ciertas IPs.
  • Las cuentas suspendidas (POST …/suspender) dejan de enviar y recibir; …/reactivar las devuelve.
  • Los canales se encienden y apagan con POST /canales/estado.

Errores frecuentes#

CódigoQué significa
ventana_cerradaPasó la ventana de la red: envía una plantilla.
sin_conversacionMessenger, Instagram o Telegram: el contacto debe escribir primero.
contacto_bloqueadoEl contacto está bloqueado en la cuenta.
api_deshabilitadaLa API está apagada en la cuenta (las llaves creadas por la plataforma la encienden).
en_procesoUna petición con la misma referencia_externa todavía se procesa.
¿Te fue útil esta página?
Última actualización: 14/11/2026