Un sistema externo envía mensajes por los canales de la cuenta (WhatsApp, Messenger, Instagram y Telegram) y consulta su estado de entrega. Los mensajes que llegan de los contactos se reciben por webhook («mensaje.recibido»). Envía mensajes reales, por eso nace apagada y sus permisos se dan de forma explícita.
Permisos#
| Permiso | Para qué sirve | Tipo |
|---|---|---|
mensajes:enviar | Enviar mensajes por los canales | escritura |
mensajes:leer | Consultar el estado de un mensaje enviado | lectura |
Endpoints#
POST /mensajes/enviar#
Envía un mensaje de texto o una plantilla a un contacto por un canal. El mensaje queda en la conversación del contacto. El texto libre solo se puede 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 aprobada. En WhatsApp se puede iniciar la conversación con una plantilla indicando el teléfono. Con «referencia_externa» el envío es idempotente: repetirlo no manda otro mensaje y devuelve el mismo resultado («duplicado»: true).
Permiso: mensajes:enviar · escritura
Cuerpo (JSON)#
| Campo | Descripción |
|---|---|
canal_id | id del canal (GET /canales). Obligatorio salvo que envíes conversacion_id. |
conversacion_id | opcional: responder en una conversación concreta |
contacto_id | id del contacto destinatario |
telefono | solo WhatsApp: teléfono con código de país (se busca el contacto o, con crear_contacto, se crea) |
crear_contacto | true para crear el contacto si no existe (con «telefono») |
nombre | nombre del contacto nuevo |
tipo | «texto» (por defecto), «plantilla», «imagen», «video», «documento» o «audio» |
texto | el mensaje (tipo texto, hasta 4096 caracteres) o el pie de la imagen, el video o el documento |
adjunto | tipos imagen, video, documento y audio: {"url": "https://…/archivo.pdf", "nombre": "factura.pdf"} (https público; el nombre lleva la extensión) |
opciones | opcional: respuestas rápidas para WhatsApp (hasta 3 botones o 10 en lista) |
boton_enlace | opcional: {"texto": "Pagar ahora", "url": "https://…"} (botón con enlace en WhatsApp) |
plantilla | tipo plantilla: {"nombre": "aviso_pedido", "idioma": "es", "variables": ["Ana", "PED-123"]} |
referencia_externa | opcional: tu identificador del envío, hasta 120 caracteres (evita duplicados si reintentas) |
{
"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"
}curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/enviar" \
-H "Authorization: Bearer cnx_TU_LLAVE" \
-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"}'const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/enviar", {
method: "POST",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"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"
})
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/enviar");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(array (
'canal_id' => 3,
'telefono' => '+573001112233',
'crear_contacto' => true,
'tipo' => 'plantilla',
'plantilla' =>
array (
'nombre' => 'aviso_pedido',
'idioma' => 'es',
'variables' =>
array (
0 => 'Ana',
1 => 'PED-123',
),
),
'referencia_externa' => 'pedido-123-aviso',
)),
]);
$datos = json_decode(curl_exec($ch), true);GET /mensajes/consultar#
Estado de un mensaje: sending, sent, delivered, read o failed (con el motivo del error). También llega por webhook («mensaje.estado»).
Permiso: mensajes:leer · lectura
Parámetros de la consulta#
| Parámetro | Descripción |
|---|---|
id | el «mensaje_id» que devolvió el envío |
referencia_externa | o la referencia con que lo enviaste |
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/consultar?id=valor" \
-H "Authorization: Bearer cnx_TU_LLAVE"const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/consultar?id=valor", {
method: "GET",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/consultar?id=valor");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);GET /mensajes/adjunto#
Descarga el archivo de un mensaje (la imagen, el video, el audio o el documento que envió el contacto, o el que enviaste). Responde el archivo, no JSON. El «mensaje_id» llega en el webhook «mensaje.recibido» (campo «adjuntos»).
Permiso: mensajes:leer · lectura
Parámetros de la consulta#
| Parámetro | Descripción |
|---|---|
mensaje_id | obligatorio |
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/adjunto?mensaje_id=valor" \
-H "Authorization: Bearer cnx_TU_LLAVE"const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/adjunto?mensaje_id=valor", {
method: "GET",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/adjunto?mensaje_id=valor");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);Respuesta#
enviar: {"datos": {"mensaje_id", "conversacion_id", "contacto_id", "canal_id", "canal", "estado", "externo_id", "referencia_externa", "duplicado"}}. consultar: {"datos": {"mensaje_id", "estado", "error", "texto", "creado_at", …}}.