Ir al contenido
Documentación de Connecto
connecto.lat
API para desarrolladoresReferencia

Mensajes (enviar y consultar)

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.

Esta API nace apagada: actívala en Configuración → APIs antes de usarla.

Permisos#

PermisoPara qué sirveTipo
mensajes:enviarEnviar mensajes por los canalesescritura
mensajes:leerConsultar el estado de un mensaje enviadolectura

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)#

CampoDescripción
canal_idid del canal (GET /canales). Obligatorio salvo que envíes conversacion_id.
conversacion_idopcional: responder en una conversación concreta
contacto_idid del contacto destinatario
telefonosolo WhatsApp: teléfono con código de país (se busca el contacto o, con crear_contacto, se crea)
crear_contactotrue para crear el contacto si no existe (con «telefono»)
nombrenombre del contacto nuevo
tipo«texto» (por defecto), «plantilla», «imagen», «video», «documento» o «audio»
textoel mensaje (tipo texto, hasta 4096 caracteres) o el pie de la imagen, el video o el documento
adjuntotipos imagen, video, documento y audio: {"url": "https://…/archivo.pdf", "nombre": "factura.pdf"} (https público; el nombre lleva la extensión)
opcionesopcional: respuestas rápidas para WhatsApp (hasta 3 botones o 10 en lista)
boton_enlaceopcional: {"texto": "Pagar ahora", "url": "https://…"} (botón con enlace en WhatsApp)
plantillatipo plantilla: {"nombre": "aviso_pedido", "idioma": "es", "variables": ["Ana", "PED-123"]}
referencia_externaopcional: tu identificador del envío, hasta 120 caracteres (evita duplicados si reintentas)
Ejemplo de cuerpo
{
  "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"
}
Ejemplo en curl
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"}'
Ejemplo en javascript
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();
Ejemplo en php
$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ámetroDescripción
idel «mensaje_id» que devolvió el envío
referencia_externao la referencia con que lo enviaste
Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/consultar?id=valor" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
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();
Ejemplo en php
$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ámetroDescripción
mensaje_idobligatorio
Ejemplo en curl
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/mensajes/adjunto?mensaje_id=valor" \
  -H "Authorization: Bearer cnx_TU_LLAVE"
Ejemplo en javascript
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();
Ejemplo en php
$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", …}}.

¿Te fue útil esta página?
Última actualización: 14/11/2026