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#
- Connecto da de alta tu aplicación y te entrega una llave de aplicación (
cna_…). - 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. - 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.
- Cada cliente puede tener o no su canal: solo se crea la cuenta de quien lo necesita.
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:
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
201conlista: true, laapide 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
202conlista: false: vuelve a llamar al mismo punto y continúa (no crea nada dos veces). - Llamarla otra vez no cambia nada: responde
200conllave: nullyllave_ya_entregada: true. Con"renovar_llave": truese 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;…/habilitarla vuelve a encender). - Tu aplicación solo puede volver a encender (
habilitaroreactivar) lo que ella misma deshabilitó. Una cuenta que suspendió o canceló Connecto responde409y 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#
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#
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:
| Canal | Cómo |
|---|---|
POST /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). |
| Telegram | POST /canales/telegram con el bot_token de @BotFather. |
| Messenger e Instagram | Piden 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):
{ "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": falseel 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 cadamensaje.recibido), para que tu aplicación cree el contacto en su sistema:
{ "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)#
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#
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#
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_cerraday 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 laconversacion_idque llega en el webhookmensaje.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_externahace 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;…/reactivarlas devuelve. - Los canales se encienden y apagan con
POST /canales/estado.
Errores frecuentes#
| Código | Qué significa |
|---|---|
ventana_cerrada | Pasó la ventana de la red: envía una plantilla. |
sin_conversacion | Messenger, Instagram o Telegram: el contacto debe escribir primero. |
contacto_bloqueado | El contacto está bloqueado en la cuenta. |
api_deshabilitada | La API está apagada en la cuenta (las llaves creadas por la plataforma la encienden). |
en_proceso | Una petición con la misma referencia_externa todavía se procesa. |