Saltar al contenido principal

Para desarrolladores

API y webhooks de Colibly

Con la API tu sistema consulta y actualiza contactos, lee conversaciones, envía mensajes de WhatsApp y arranca automatizaciones. Con los webhooks, Colibly avisa a tu servidor cada vez que llega un mensaje, se crea un contacto o cambia la etapa de un lead. Ambos se incluyen con la licencia Pro (y en la prueba gratuita): las API keys y los webhooks los crea un administrador con licencia Pro, y dejan de funcionar si esa persona deja de ser administrador o baja de licencia.

URL base
https://app.colibly.com/api/v1
Formato
JSON en UTF-8. Fechas en ISO 8601 (UTC). Ids opacos de texto.
Especificación
OpenAPI 3.1 en /api/v1/openapi.json, para generar clientes o importarla en Insomnia. Colección de Postman lista para usar en /api/v1/postman.json (Import → Link; pon tu key en la variable apiKey).

Primera llamada

Verifica tu key con GET /me:

curl https://app.colibly.com/api/v1/me \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Autenticación

Cada solicitud lleva una API key en el header Authorization: Bearer sk_live_…. Un administrador la crea en Configuración → API, eligiendo sus permisos, las cuentas que puede usar (o todas) y su vigencia (30, 90 o 365 días, o sin vencimiento).

  • La key completa se muestra una sola vez; nosotros solo guardamos su huella. Si se pierde, crea otra y revoca la anterior.
  • Para rotarla: crea la nueva, cámbiala en tu sistema y revoca la vieja. Revocar surte efecto de inmediato.
  • Una key actúa con el acceso de quien la creó. Si esa persona deja de ser administradora o se desactiva, la key deja de funcionar.
  • Máximo 10 keys activas por cuenta.
  • Guárdala en el servidor (variable de entorno o gestor de secretos). Nunca en una app móvil, en el navegador ni en un repositorio.

Permisos

PermisoQué permite
contacts:readLeer contactos, etiquetas y campos
contacts:writeCrear y editar contactos, etapas y etiquetas
conversations:readLeer conversaciones y mensajes
conversations:writeCambiar el estado y la asignación de conversaciones
messages:sendEnviar mensajes (texto, plantillas y botones)
webhooks:manageAdministrar webhooks salientes
automations:runIniciar automatizaciones manuales
whatsapp:manageAdministrar WhatsApp: plantillas, perfil de empresa, bloqueos, sugerencias y comandos, códigos QR y costos

GET /me y GET /accounts no piden permiso.

Límites de velocidad

Los límites se cuentan en ventanas móviles de 60 s y se aplican en capas; gana el primero que se agote:

LímiteValor
Por key120 solicitudes por minuto
Por cuenta (todas sus keys juntas)600 solicitudes por minuto
Por IP (con o sin key)3000 solicitudes por minuto
POST /messages60 envíos por minuto y 10,000 por día (UTC) por cuenta
GET /conversations60 solicitudes por minuto por key
Tamaño del cuerpo1024 KB como máximo (si no, 413 payload_too_large)

Toda respuesta autenticada informa el límite más ajustado en ese momento:

HeaderSignificado
X-RateLimit-LimitSolicitudes permitidas en la ventana del límite informado.
X-RateLimit-RemainingLas que te quedan en la ventana actual.
X-RateLimit-ResetSegundos hasta que se libera un lugar.
X-RateLimit-ScopeQué límite se informa: key, organization, ip, endpoint o daily.
Retry-AfterSolo en el 429 y el 503: segundos a esperar antes de reintentar.

Al pasarte recibes 429 rate_limited. Espera lo que indica Retry-After; reintentar antes vuelve a contar.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12
X-RateLimit-Scope: key
Retry-After: 12

{ "error": { "code": "rate_limited", "message": "Límite de 120 solicitudes por minuto excedido" } }

Además, una misma IP puede hacer hasta 30 intentos por minuto con keys inválidas; después recibe 429 aunque la siguiente key sea válida.

Si se agota el cupo diario de envíos recibes 429 daily_limit_reached, con Retry-After hasta las 00:00 UTC. Si el servicio de límites no está disponible respondemos 503 service_unavailable con Retry-After: 5: reintenta después.

Idempotencia

Si una solicitud que crea algo se corta (timeout, red caída), no sabes si llegó. Para reintentar sin duplicar, manda el header Idempotency-Key con un valor único por operación, por ejemplo un UUID o el id del pedido en tu sistema. Lo aceptan POST /messages, POST /contacts, POST /contacts/{id}/tags y POST /automations/{id}/runs.

curl -X POST "https://app.colibly.com/api/v1/messages" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-A-1043-confirmacion" \
  -d '{"conversationId":"cmchat_01","type":"text","text":"Sí, enviamos a todo México."}'
  • Durante 24 horas, la misma clave con el mismo cuerpo devuelve la respuesta original, con el header Idempotent-Replayed: true, y no vuelve a ejecutar la operación.
  • La misma clave con otro cuerpo, o en otro endpoint, responde 422 idempotency_conflict.
  • Si la primera solicitud sigue en proceso, la repetida recibe 409 conflict: espera unos segundos y reintenta.
  • Los errores 401, 402, 403, 429 y 5xx no se guardan, así que puedes reintentarlos con la misma clave.
  • Las claves son de tu cuenta: dos integraciones tuyas no deben compartir valores.

Errores

Los errores responden con el status HTTP y un cuerpo estable. Decide según code; message está en español y puede cambiar.

{ "error": { "code": "window_closed", "message": "Fuera de la ventana de 24 h: envía una plantilla aprobada", "requestId": "req_4fQm1x9TzK2bLw7a" } }

En un error de validación, details lista cada campo con su ruta (template.id, buttons.0.title), para que corrijas todo de una vez:

{
  "error": {
    "code": "invalid_request",
    "message": "type: Opción inválida: se esperaba una de "text"|"buttons"|"template" (y 1 más en details)",
    "details": [
      { "path": "type", "message": "Opción inválida: se esperaba una de "text"|"buttons"|"template"" },
      { "path": "template.id", "message": "Entrada inválida: se esperaba texto, recibido indefinido" }
    ],
    "requestId": "req_b8YmONFwR90UzIEW"
  }
}

Cada respuesta, buena o mala, trae el header X-Request-Id (igual a error.requestId). Guárdalo en tus logs e inclúyelo si escribes a soporte: con él encontramos tu llamada.

StatuscodeCuándo
400invalid_requestCuerpo o parámetros inválidos; `message` dice cuál y `details` trae cada campo (`path`, `message`).
401unauthorizedFalta la API key, es inválida, está revocada o vencida, o su dueño ya no es admin.
402plan_limitEl dueño de la API key ya no es administrador con licencia Pro, o se alcanzó un límite de la organización (p. ej. contactos).
402read_onlyCuenta en solo lectura (prueba vencida o pago pendiente): solo GET.
403forbiddenLa key no tiene el permiso que pide el endpoint.
404not_foundNo existe o no está al alcance de la key.
405method_not_allowedLa ruta existe pero no acepta ese método; el header `Allow` dice cuáles sí.
409conflictChoca con el estado actual (p. ej. automatización ya en curso, o la misma Idempotency-Key sigue en proceso).
409limit_reachedTope por cuenta: 10 webhooks.
422window_closedWhatsApp: fuera de la ventana de 24 h solo se puede enviar una plantilla aprobada.
422idempotency_conflictLa Idempotency-Key ya se usó con otro cuerpo o en otro endpoint.
422required_fieldsNo se puede resolver la conversación: faltan atributos obligatorios (ver `details`).
413payload_too_largeEl cuerpo supera 1024 KB.
429rate_limitedDemasiadas solicitudes (por key, organización, IP o endpoint; ver `X-RateLimit-Scope`); espera los segundos de `Retry-After`.
429daily_limit_reachedCupo diario de 10000 envíos por API por organización (día UTC); `Retry-After` indica cuándo se renueva.
500internal_errorError nuestro. Reintenta con la misma Idempotency-Key.
502upstream_errorWhatsApp/Meta u otro canal rechazó o no respondió.
503service_unavailableServicio temporalmente no disponible (p. ej. el limitador de velocidad); reintenta tras `Retry-After`.

Paginación

Los listados devuelven { data, nextCursor }. Pide la siguiente página con ?cursor=<nextCursor>; cuando nextCursor es null, terminaste. limit va de 1 a 100 (por defecto 25). El cursor es opaco: no lo construyas ni lo guardes por mucho tiempo. Los catálogos (/accounts, /templates, /tags, /users, /teams, /automations) devuelven la lista completa en data, sin cursor.

// Recorre todos los contactos de 100 en 100.
let cursor = null;
do {
  const url = new URL("https://app.colibly.com/api/v1/contacts");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.COLIBLY_API_KEY}` } });
  const page = await res.json();
  for (const contact of page.data) guardar(contact);
  cursor = page.nextCursor;
} while (cursor);

Para sincronizar cambios periódicamente usa GET /contacts?updatedSince=… con la fecha de tu última sincronización, o mejor, suscríbete al webhook correspondiente.

Versiones

La versión va en la ruta: hoy es /api/v1. Dentro de v1 solo agregamos: campos nuevos en las respuestas, endpoints, eventos y valores nuevos en los enumerados. Tu integración debe ignorar los campos que no conoce.

Un cambio incompatible (quitar o renombrar un campo, cambiar un tipo o el significado de un error) saldría como /api/v2. v1 se mantendría al menos 12 meses después, y avisaríamos por correo a los administradores con keys activas.

Webhooks

Un webhook es una URL de tu servidor a la que Colibly manda un POST con JSON cada vez que ocurre un evento que elegiste. Se crean en Configuración → API → Webhooks o con POST /webhooks, eligiendo eventos (o todos con *) y, si quieres, solo algunas cuentas.

  • La URL debe ser https:// y pública. Rechazamos direcciones internas o reservadas, y no seguimos redirecciones.
  • Al crearlo recibes un secreto whsec_…, que se muestra una vez y sirve para verificar la firma. Se rota en la pantalla o con POST /webhooks/{id}/rotate-secret. Con { "graceHours": 24 } el anterior sigue firmando ese tiempo (hasta 72 h); sin él, deja de firmar en ese momento.
  • Máximo 10 webhooks por cuenta.
  • El botón Probar (o POST /webhooks/{id}/test) envía un evento webhook.test firmado, para validar tu receptor sin esperar un evento real. Su resultado queda en el historial de entregas.

Cada entrega

HeaderValor
X-Colibly-Signaturet=<unix>,v1=<hex>: HMAC-SHA256 del texto {t}.{cuerpo} con tu secreto.
X-Colibly-EventTipo de evento, p. ej. contact.created.
X-Colibly-DeliveryId de la entrega; es el mismo en cada reintento.
X-Colibly-Event-IdId del evento (el mismo que id en el cuerpo): igual en todos tus endpoints y reintentos, útil para descartar duplicados.
X-Colibly-AttemptNúmero de intento (1 = primera entrega).
User-AgentColibly-Webhooks/1.0
Content-Typeapplication/json

El cuerpo siempre tiene la misma forma. contact y conversation traen los datos del momento de la entrega; data trae el hecho tal como ocurrió.

{
  "id": "7d1f2c9e-3b4a-4f0e-9a51-0c2b8e6d4f10",
  "type": "contact.lead_status_changed",
  "occurredAt": "2026-10-18T19:02:11.000Z",
  "account": {
    "id": "cmacc_wa_01",
    "channel": "WHATSAPP",
    "name": "Ventas CDMX",
    "phoneNumber": "+52 1 55 1234 5678",
    "phoneE164": "+525512345678"
  },
  "contact": {
    "id": "cmcon_01",
    "name": "Ana López",
    "realName": null,
    "tags": [
      {
        "id": "cmtag_01",
        "name": "Mayoreo"
      }
    ],
    "phone": "5215598765432",
    "phoneE164": "+525598765432",
    "externalId": null,
    "leadStatus": "QUALIFIED",
    "leadOrigin": "ORGANIC"
  },
  "conversation": {
    "id": "cmchat_01",
    "channel": "WHATSAPP",
    "status": "OPEN",
    "assignedToId": "cmusr_02"
  },
  "data": {
    "from": "NEW",
    "to": "QUALIFIED"
  }
}

Eventos

message.receivedMensaje recibido de un contactoVer ejemplo
{
  "messageId": "cmmsg_01",
  "messageType": "text",
  "text": "¿Tienen envío a Puebla?",
  "interactiveReplyId": null
}
message.sentMensaje enviado: bandeja, API, automatización, bot, campaña, secuencia, aviso automático o la app WhatsApp BusinessVer ejemplo
{
  "messageId": "cmmsg_02",
  "messageType": "text",
  "text": "Sí, enviamos a todo México.",
  "source": "agent",
  "senderId": "cmusr_02",
  "origin": "agent",
  "sentBy": "user",
  "senderName": "Carla Méndez"
}
message.status_changedEstado de un mensaje enviado (entregado, leído o fallido). Solo WhatsAppVer ejemplo
{
  "messageId": "cmmsg_02",
  "status": "delivered",
  "previousStatus": "sent",
  "error": null,
  "pricing": {
    "billable": false,
    "model": "PMP",
    "category": "service",
    "type": "free_customer_service"
  }
}
message.updatedUn mensaje ya guardado cambió: su medio quedó listo o llegó el contenido de un media_placeholderVer ejemplo
{
  "messageId": "cmmsg_01",
  "reason": "media_ready"
}
contact.createdContacto nuevoVer ejemplo
{
  "origin": "ORGANIC",
  "source": "inbound"
}
contact.lead_status_changedCambio de etapa del leadVer ejemplo
{
  "from": "NEW",
  "to": "QUALIFIED"
}
contact.marketing_preference_changedEl contacto pidió dejar de recibir marketing, o volver a recibirlo, desde WhatsAppVer ejemplo
{
  "optedOut": true,
  "source": "whatsapp"
}
tag.addedEtiqueta agregada a un contacto o conversaciónVer ejemplo
{
  "tagId": "cmtag_01",
  "tagName": "Mayoreo",
  "target": "contact"
}
conversation.assignedConversación asignadaVer ejemplo
{
  "assignedToId": "cmusr_02",
  "auto": true
}
conversation.resolvedConversación resueltaVer ejemplo
{}
conversation.welcome_requestedUn cliente abrió el chat por primera vez sin escribir (mensaje de bienvenida). Solo WhatsAppVer ejemplo
{
  "messageId": "cmmsg_09"
}
appointment.createdCita creadaVer ejemplo
{
  "appointmentId": "cmapt_01",
  "title": "Visita a showroom",
  "scheduledAt": "2026-10-22T17:00:00.000Z",
  "source": "AI_BOT"
}
appointment.status_changedCambio de estado de una citaVer ejemplo
{
  "appointmentId": "cmapt_01",
  "from": "SCHEDULED",
  "to": "COMPLETED"
}
lead.scoredLead calificado por un calificador IAVer ejemplo
{
  "scorerId": "cmsc_01",
  "scorerName": "Intención de compra",
  "score": 82,
  "label": "Caliente",
  "previousLabel": "Tibio"
}
lead.ad_capturedLead llegado de un anuncio (CTWA o Instant Form)Ver ejemplo
{
  "origin": "CTWA",
  "adId": "120210000000000000"
}
flow.completedUn cliente terminó un formulario de WhatsApp (Flow), con sus respuestas. Solo WhatsAppVer ejemplo
{
  "messageId": "cmmsg_11",
  "flowToken": "cita-A-1043",
  "response": {
    "sucursal": "centro",
    "fecha": "2026-11-20",
    "hora": "10:00"
  }
}
order.receivedPedido desde el carrito del catálogo de WhatsApp, con productos y total. Solo WhatsAppVer ejemplo
{
  "messageId": "cmmsg_10",
  "catalogId": "1234567890",
  "text": "Para entrega el sábado",
  "items": [
    {
      "productId": "SKU-1043",
      "quantity": 2,
      "price": 1499,
      "currency": "MXN"
    }
  ],
  "total": 2998,
  "currency": "MXN"
}
template.status_changedMeta revisó, pausó, desactivó o marcó una plantilla. Solo WhatsAppVer ejemplo
{
  "templateId": "cmtpl_01",
  "name": "confirmacion_pedido",
  "language": "es_MX",
  "event": "APPROVED",
  "status": "APPROVED",
  "previousStatus": "PENDING",
  "reason": null
}
template.category_changedMeta cambió la categoría de una plantilla. Solo WhatsAppVer ejemplo
{
  "templateId": "cmtpl_01",
  "name": "confirmacion_pedido",
  "language": "es_MX",
  "category": "MARKETING",
  "previousCategory": "UTILITY"
}
account.quality_changedCambió la calidad o el límite de envío del número. Solo WhatsAppVer ejemplo
{
  "event": "UPGRADE",
  "messagingTier": "TIER_10K"
}
account.connectedSe conectó un número de WhatsApp (desde el panel o con un enlace de conexión). Solo WhatsAppVer ejemplo
{
  "accountId": "cmacc_wa_02",
  "coexistence": false,
  "via": "onboarding_link",
  "linkId": "cmobl_01",
  "reference": "cliente-4521"
}
call.ringingLlamada de WhatsApp sonando (entrante o saliente). Solo WhatsAppVer ejemplo
{
  "callId": "cmcall_01",
  "direction": "inbound",
  "phone": "5215512345678"
}
call.answeredLlamada de WhatsApp contestada. Solo WhatsAppVer ejemplo
{
  "callId": "cmcall_01",
  "direction": "inbound",
  "phone": "5215512345678",
  "answeredById": "cmusr_02"
}
call.endedLlamada de WhatsApp terminada: contestada, perdida, rechazada o fallida, con su duración. Solo WhatsAppVer ejemplo
{
  "callId": "cmcall_01",
  "direction": "inbound",
  "phone": "5215512345678",
  "outcome": "ENDED",
  "durationSeconds": 184,
  "startedAt": "2026-10-18T19:02:11.000Z",
  "endedAt": "2026-10-18T19:05:15.000Z"
}
webhook.testEvento de prueba (botón “Probar” en Configuración → API). account, contact y conversation llegan en null.Ver ejemplo
{
  "message": "Evento de prueba enviado desde Colibly"
}

Los contactos que llegan al importar el historial de WhatsApp Business (Coexistencia) generan contact.created con data.source = "history". Llegan espaciados y después de los eventos en vivo; fíltralos por ese campo si no te interesan.

Verificar la firma

Verifica cada entrega antes de confiar en ella: compara la firma con una función de tiempo constante y rechaza las que tengan más de 5 minutos.

El header puede traer más de una v1: al rotar el secreto con periodo de gracia, cada entrega va firmada con el nuevo y con el anterior (t=…,v1=<nuevo>,v1=<anterior>) hasta que vence. Acepta la entrega si cualquiera coincide con tu secreto; así cambias el secreto de tu servidor sin perder eventos. Las recetas de abajo ya lo hacen.

Node.js

// Node.js 18+ con Express. Usa el cuerpo CRUDO: si lo parseas y
// vuelves a serializar, la firma ya no coincide.
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.COLIBLY_WEBHOOK_SECRET; // whsec_...

app.post("/colibly/eventos", express.raw({ type: "application/json" }), (req, res) => {
  // t=<unix>,v1=<firma>[,v1=<firma>]: tras rotar el secreto con periodo de
  // gracia llegan dos v1 (nuevo y anterior). Basta con que una coincida.
  const parts = (req.get("X-Colibly-Signature") ?? "").split(",").map((p) => p.split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  const signatures = parts.filter(([k, v]) => k === "v1" && /^[0-9a-f]{64}$/.test(v ?? "")).map(([, v]) => v);
  if (!t || !/^\d+$/.test(t) || signatures.length === 0) return res.sendStatus(400);

  // Rechaza entregas de hace más de 5 minutos (reenvíos).
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);

  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest();
  const valid = signatures.some((v1) => crypto.timingSafeEqual(Buffer.from(v1, "hex"), expected));
  if (!valid) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString("utf8"));
  // Un mismo evento puede llegar más de una vez: descarta los event.id ya vistos.
  res.sendStatus(200); // responde rápido y procesa después
  procesar(event);
});

PHP

<?php
// PHP 7.4+. Lee el cuerpo crudo con php://input.
$secret = getenv('COLIBLY_WEBHOOK_SECRET'); // whsec_...
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_COLIBLY_SIGNATURE'] ?? '';

// t=<unix>,v1=<firma>[,v1=<firma>]: tras rotar el secreto con periodo de
// gracia llegan dos v1 (nuevo y anterior). Basta con que una coincida.
$t = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
    [$k, $v] = array_pad(explode('=', $part, 2), 2, '');
    if ($k === 't') $t = $v;
    if ($k === 'v1' && preg_match('/^[0-9a-f]{64}$/', $v)) $signatures[] = $v;
}
if ($t === null || !ctype_digit($t) || !$signatures) {
    http_response_code(400);
    exit;
}

// Rechaza entregas de hace más de 5 minutos (reenvíos).
if (abs(time() - (int) $t) > 300) {
    http_response_code(400);
    exit;
}

$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = false;
foreach ($signatures as $v1) {
    if (hash_equals($expected, $v1)) $valid = true;
}
if (!$valid) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// Un mismo evento puede llegar más de una vez: descarta los $event['id'] ya vistos.
http_response_code(200);
// procesar($event);

Python

# Python 3.9+ con Flask. Usa el cuerpo CRUDO (request.get_data()).
import hashlib, hmac, json, os, re, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["COLIBLY_WEBHOOK_SECRET"].encode()  # whsec_...

@app.post("/colibly/eventos")
def eventos():
    # t=<unix>,v1=<firma>[,v1=<firma>]: tras rotar el secreto con periodo de
    # gracia llegan dos v1 (nuevo y anterior). Basta con que una coincida.
    t, signatures = None, []
    for part in request.headers.get("X-Colibly-Signature", "").split(","):
        key, _, value = part.partition("=")
        if key == "t":
            t = value
        elif key == "v1" and re.fullmatch(r"[0-9a-f]{64}", value):
            signatures.append(value)
    if not t or not t.isdigit() or not signatures:
        abort(400)

    # Rechaza entregas de hace más de 5 minutos (reenvíos).
    if abs(time.time() - int(t)) > 300:
        abort(400)

    body = request.get_data()
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not any(hmac.compare_digest(expected, v1) for v1 in signatures):
        abort(401)

    event = json.loads(body)
    # Un mismo evento puede llegar más de una vez: descarta los event["id"] ya vistos.
    procesar(event)  # mejor en segundo plano: responde en menos de 20 s
    return "", 200

Reintentos, desactivación y pausa

  • Responde con cualquier 2xx en menos de 20 segundos. Si tu proceso tarda, responde primero y procesa después.
  • A un mismo webhook le enviamos como mucho 2 entregas a la vez; las demás esperan su turno sin gastar intentos.
  • Si fallas (error, timeout o status distinto de 2xx), reintentamos hasta completar 6 intentos. La primera espera es de 30 segundos y se duplica en cada intento, unos 16 minutos en total. Una URL rechazada por seguridad no se reintenta.
  • Un evento puede llegar más de una vez y no siempre en orden. Usa id para descartar duplicados y occurredAt para ordenar.
  • Tras 20 entregas fallidas seguidas, el webhook se desactiva solo y avisamos a quien lo creó. Al reactivarlo, el contador vuelve a cero.
  • Si quien creó el webhook deja de ser administrador o se desactiva, el webhook se pausa y avisamos a los demás administradores. Otro administrador lo reactiva y queda a su nombre (por API: PATCH /webhooks/{id} con { "active": true, "takeOwnership": true }).
  • En Configuración → API → Webhooks → Ver entregas está el registro de los últimos 30 días, con status, intentos y respuesta, y un botón para reintentar las fallidas.

Referencia de endpoints

Todos los ejemplos usan datos ficticios. Las rutas son relativas a https://app.colibly.com/api/v1.

Cuenta

Identidad de la key y cuentas a su alcance

GET/me

Identidad de la API key

Sin permiso especial. Útil para verificar la conexión.

Ejemplo

curl "https://app.colibly.com/api/v1/me" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "key": {
    "name": "ERP",
    "prefix": "sk_live_AbC123",
    "scopes": [
      "contacts:read",
      "messages:send"
    ],
    "expiresAt": null
  },
  "owner": {
    "id": "cmusr_01",
    "name": "Luisa Admin",
    "email": "admin@ejemplo.mx"
  },
  "accountIds": [
    "cmacc_wa_01"
  ],
  "channelAccountIds": []
}

GET/accounts

Cuentas al alcance de la key

WhatsApp y demás canales que la key puede usar. Sin permiso especial.

Ejemplo

curl "https://app.colibly.com/api/v1/accounts" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmacc_wa_01",
      "channel": "WHATSAPP",
      "name": "Ventas CDMX",
      "phoneNumber": "+52 1 55 1234 5678",
      "phoneE164": "+525512345678",
      "status": "CONNECTED"
    }
  ]
}

Contactos

GET/contacts

Listar contactos

Requiere el permiso contacts:read. Más recientes primero.

ParámetroEnDescripción
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior
accountId?querystring
leadStatus?queryNEW | CONTACTED | QUALIFIED | CUSTOMER | LOST
tagId?querystring
q?queryNombre o teléfono
updatedSince?queryPara sincronizar: solo los modificados después de esta fecha

Ejemplo

curl "https://app.colibly.com/api/v1/contacts?limit=2&leadStatus=QUALIFIED" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmcon_01",
      "accountId": "cmacc_wa_01",
      "channel": "WHATSAPP",
      "name": "Ana López",
      "realName": null,
      "phone": "5215598765432",
      "phoneE164": "+525598765432",
      "externalId": null,
      "leadStatus": "QUALIFIED",
      "leadOrigin": "ORGANIC",
      "adId": null,
      "ctwaClid": null,
      "dealValueCents": 85000,
      "dealCurrency": "MXN",
      "expectedCloseAt": "2026-10-25T00:00:00.000Z",
      "optedOutMarketing": false,
      "tags": [
        {
          "id": "cmtag_01",
          "name": "Mayoreo"
        }
      ],
      "customFields": {
        "ciudad": "Puebla"
      },
      "conversationId": "cmchat_01",
      "createdAt": "2026-10-01T16:20:00.000Z",
      "updatedAt": "2026-10-18T19:02:11.000Z"
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0xOFQxOTowMjoxMS4wMDBaIiwiaWQiOiJjbWNvbl8wMSJ9"
}

POST/contacts

Crear contacto de WhatsApp

Requiere el permiso contacts:write. Idempotente por teléfono: 201 si lo creó, 200 si ya existía (no lo modifica). Respeta el límite de contactos del plan (402 plan_limit).

ParámetroEnDescripción
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
accountIdstringCuenta de WhatsApp
phonestringCon código de país, p. ej. 5215512345678 o +52 55 1234 5678 (8 a 15 dígitos); 10 dígitos sin `+` se toman como México. En México 52… y 521… son el mismo contacto
name?string
leadStatus?NEW | CONTACTED | QUALIFIED | CUSTOMER | LOST
tags?string[]Nombres; se crean si no existen
customFields?objectPor key del campo

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/contacts" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"accountId":"cmacc_wa_01","phone":"5215598765432","name":"Ana López","leadStatus":"NEW","tags":["Mayoreo"],"customFields":{"ciudad":"Puebla"}}'

Respuesta 200

{
  "id": "cmcon_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "name": "Ana López",
  "realName": null,
  "phone": "5215598765432",
  "phoneE164": "+525598765432",
  "externalId": null,
  "leadStatus": "QUALIFIED",
  "leadOrigin": "ORGANIC",
  "adId": null,
  "ctwaClid": null,
  "dealValueCents": 85000,
  "dealCurrency": "MXN",
  "expectedCloseAt": "2026-10-25T00:00:00.000Z",
  "optedOutMarketing": false,
  "tags": [
    {
      "id": "cmtag_01",
      "name": "Mayoreo"
    }
  ],
  "customFields": {
    "ciudad": "Puebla"
  },
  "conversationId": "cmchat_01",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

GET/contacts/{id}

Obtener contacto

Requiere el permiso contacts:read.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/contacts/cmcon_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmcon_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "name": "Ana López",
  "realName": null,
  "phone": "5215598765432",
  "phoneE164": "+525598765432",
  "externalId": null,
  "leadStatus": "QUALIFIED",
  "leadOrigin": "ORGANIC",
  "adId": null,
  "ctwaClid": null,
  "dealValueCents": 85000,
  "dealCurrency": "MXN",
  "expectedCloseAt": "2026-10-25T00:00:00.000Z",
  "optedOutMarketing": false,
  "tags": [
    {
      "id": "cmtag_01",
      "name": "Mayoreo"
    }
  ],
  "customFields": {
    "ciudad": "Puebla"
  },
  "conversationId": "cmchat_01",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

PATCH/contacts/{id}

Actualizar contacto

Requiere el permiso contacts:write. Cambiar leadStatus dispara lo mismo que moverlo en el Pipeline (Meta CAPI, secuencias, webhooks).

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
name?string
realName?string | null
leadStatus?NEW | CONTACTED | QUALIFIED | CUSTOMER | LOST
customFields?objectnull o "" borra el valor
dealValueCents?integer | nullValor del trato en centavos de MXN; null lo borra
expectedCloseAt?string | nullFecha estimada de cierre; null la borra

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/contacts/cmcon_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leadStatus":"CUSTOMER","customFields":{"pedido":"A-1043"}}'

Respuesta 200

{
  "id": "cmcon_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "name": "Ana López",
  "realName": null,
  "phone": "5215598765432",
  "phoneE164": "+525598765432",
  "externalId": null,
  "leadStatus": "QUALIFIED",
  "leadOrigin": "ORGANIC",
  "adId": null,
  "ctwaClid": null,
  "dealValueCents": 85000,
  "dealCurrency": "MXN",
  "expectedCloseAt": "2026-10-25T00:00:00.000Z",
  "optedOutMarketing": false,
  "tags": [
    {
      "id": "cmtag_01",
      "name": "Mayoreo"
    }
  ],
  "customFields": {
    "ciudad": "Puebla"
  },
  "conversationId": "cmchat_01",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

POST/contacts/{id}/tags

Agregar etiqueta

Requiere el permiso contacts:write. Por tagId o por name (uno de los dos); por nombre se crea si no existe. Devuelve el contacto.

ParámetroEnDescripción
idrutastring
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
tagId?string
name?string

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/contacts/cmcon_01/tags" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"name":"Mayoreo"}'

Respuesta 200

{
  "id": "cmcon_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "name": "Ana López",
  "realName": null,
  "phone": "5215598765432",
  "phoneE164": "+525598765432",
  "externalId": null,
  "leadStatus": "QUALIFIED",
  "leadOrigin": "ORGANIC",
  "adId": null,
  "ctwaClid": null,
  "dealValueCents": 85000,
  "dealCurrency": "MXN",
  "expectedCloseAt": "2026-10-25T00:00:00.000Z",
  "optedOutMarketing": false,
  "tags": [
    {
      "id": "cmtag_01",
      "name": "Mayoreo"
    }
  ],
  "customFields": {
    "ciudad": "Puebla"
  },
  "conversationId": "cmchat_01",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

DELETE/contacts/{id}/tags

Quitar etiqueta

Requiere el permiso contacts:write.

ParámetroEnDescripción
idrutastring
tagIdquerystring

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/contacts/cmcon_01/tags?tagId=cmtag_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmcon_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "name": "Ana López",
  "realName": null,
  "phone": "5215598765432",
  "phoneE164": "+525598765432",
  "externalId": null,
  "leadStatus": "QUALIFIED",
  "leadOrigin": "ORGANIC",
  "adId": null,
  "ctwaClid": null,
  "dealValueCents": 85000,
  "dealCurrency": "MXN",
  "expectedCloseAt": "2026-10-25T00:00:00.000Z",
  "optedOutMarketing": false,
  "tags": [
    {
      "id": "cmtag_01",
      "name": "Mayoreo"
    }
  ],
  "customFields": {
    "ciudad": "Puebla"
  },
  "conversationId": "cmchat_01",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

Conversaciones

GET/conversations

Listar conversaciones

Requiere el permiso conversations:read. Todos los canales, por último mensaje.

ParámetroEnDescripción
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior
accountId?querystring
channel?queryWHATSAPP | TELEGRAM | MESSENGER | INSTAGRAM | WEBCHAT
status?queryOPEN | PENDING | RESOLVED
assignedToId?querystring
teamId?querySolo las de ese equipo (GET /teams)
contactId?querystring
updatedSince?querySolo las que cambiaron desde esa fecha (mensaje, estado, asignación, no leídos). Guarda el mayor updatedAt recibido y úsalo en la siguiente consulta

Ejemplo

curl "https://app.colibly.com/api/v1/conversations?status=OPEN&limit=20" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmchat_01",
      "accountId": "cmacc_wa_01",
      "channel": "WHATSAPP",
      "contactId": "cmcon_01",
      "name": "Ana López",
      "status": "OPEN",
      "assignedToId": "cmusr_02",
      "teamId": "cmteam_01",
      "unreadCount": 1,
      "lastMessage": "¿Tienen envío a Puebla?",
      "lastMessageAt": "2026-10-18T19:02:11.000Z",
      "createdAt": "2026-10-01T16:20:00.000Z",
      "updatedAt": "2026-10-18T19:02:11.000Z"
    }
  ],
  "nextCursor": null
}

GET/conversations/{id}

Obtener conversación

Requiere el permiso conversations:read.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/conversations/cmchat_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmchat_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "contactId": "cmcon_01",
  "name": "Ana López",
  "status": "OPEN",
  "assignedToId": "cmusr_02",
  "teamId": "cmteam_01",
  "unreadCount": 1,
  "lastMessage": "¿Tienen envío a Puebla?",
  "lastMessageAt": "2026-10-18T19:02:11.000Z",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

PATCH/conversations/{id}

Resolver, reabrir o asignar

Requiere el permiso conversations:write. status y/o assignedToId (id de GET /users; null quita la asignación). Mismos efectos que en la bandeja: resolver deja de marcarla como "esperando respuesta", puede mandar la encuesta CSAT (WhatsApp) y emite conversation.resolved; asignar avisa a la persona y emite conversation.assigned. Si la conversación tiene atributos obligatorios sin llenar, resolverla responde 422 required_fields. La persona asignada debe poder atender esa cuenta (si no, 400). Devuelve la conversación actualizada.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
status?OPEN | PENDING | RESOLVED
assignedToId?string | nullId de GET /users; null quita la asignación
teamId?string | nullId de GET /teams; null la saca de su equipo. Si la conversación no tiene a nadie asignado, se asigna dentro del equipo (si la cuenta tiene la asignación automática); un assignedToId en el mismo cuerpo gana

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/conversations/cmchat_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"RESOLVED","assignedToId":"cmusr_02"}'

Respuesta 200

{
  "id": "cmchat_01",
  "accountId": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "contactId": "cmcon_01",
  "name": "Ana López",
  "status": "RESOLVED",
  "assignedToId": "cmusr_02",
  "teamId": "cmteam_01",
  "unreadCount": 1,
  "lastMessage": "¿Tienen envío a Puebla?",
  "lastMessageAt": "2026-10-18T19:02:11.000Z",
  "createdAt": "2026-10-01T16:20:00.000Z",
  "updatedAt": "2026-10-18T19:02:11.000Z"
}

POST/conversations/{id}/read

Marcar como leída (y mostrar "escribiendo…")

Requiere el permiso conversations:write. Pone unreadCount en 0. En WhatsApp también marca como leído el último mensaje del cliente (palomitas azules; Meta marca los anteriores) y, con typing: true, le muestra "escribiendo…" hasta 25 s o hasta tu respuesta: úsalo justo antes de una respuesta que tarda (p. ej. de una IA). En otros canales solo se marca en Colibly y typing se ignora. readOnWhatsApp: false si la conversación aún no tiene un mensaje del cliente con id de WhatsApp.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
typing?booleanMostrar "escribiendo…" (WhatsApp)

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/conversations/ID/read" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"typing":true}'

Respuesta 200

{
  "conversationId": "cmchat_01",
  "read": true,
  "typing": true,
  "readOnWhatsApp": true
}

GET/conversations/{id}/messages

Mensajes de una conversación

Requiere el permiso conversations:read. Sin since: recientes primero (por timestamp), para leer el historial hacia atrás. Con since: los guardados desde esa fecha (por createdAt), del más viejo al más nuevo, para ponerse al día.

ParámetroEnDescripción
idrutastring
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior
since?queryFecha ISO 8601: mensajes con createdAt ≥ since, en orden ascendente

Ejemplo

curl "https://app.colibly.com/api/v1/conversations/cmchat_01/messages" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmmsg_01",
      "conversationId": "cmchat_01",
      "direction": "INBOUND",
      "type": "text",
      "text": "¿Tienen envío a Puebla?",
      "caption": null,
      "mimeType": null,
      "filename": null,
      "status": null,
      "senderId": null,
      "interactive": null,
      "timestamp": "2026-10-18T19:02:11.000Z",
      "externalId": "wamid.HBgNNTIxNTU1MTExMTIyMjIVAgASGBQzQTk5",
      "content": null,
      "media": null,
      "replyTo": null,
      "reaction": null,
      "transcript": null,
      "error": null,
      "deliveredAt": null,
      "readAt": null,
      "pricing": null,
      "origin": "contact",
      "sentBy": "contact",
      "senderName": null,
      "referral": null,
      "createdAt": "2026-10-18T19:02:12.000Z"
    }
  ],
  "nextCursor": null
}

Mensajes

GET/messages/{id}/media

Descargar el medio de un mensaje

Requiere el permiso conversations:read. Bytes del archivo (imagen, audio, video, sticker o documento), como descarga. Es la URL de message.media.url. 404 si el mensaje no tiene medio o aún se está bajando de Meta.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/messages/ID/media" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

POST/media

Subir un archivo

Requiere el permiso messages:send. Sube un archivo una vez para reusarlo en muchos envíos: media: { id } en POST /messages o headerParam (y cards[].headerParam) de una plantilla. multipart/form-data con los campos file y type (image, document, audio, video o sticker; filename opcional), o JSON con type y url https. Mismos tipos y tamaños que los envíos (documentos hasta 20 MB). Caduca a los 30 días (expiresAt), como los archivos de Meta.

Campo del cuerpoTipoDescripción
typeimage | document | audio | video | sticker
urlstring
filename?string
mimeType?string

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/media" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"document","url":"https://erp.ejemplo.mx/catalogo-2026.pdf","filename":"Catálogo 2026.pdf"}'

Respuesta 201

{
  "id": "cmmed_01",
  "type": "document",
  "mimeType": "application/pdf",
  "filename": "Catálogo 2026.pdf",
  "bytes": 482113,
  "sha256": "9f2c…",
  "createdAt": "2026-11-14T10:00:00.000Z",
  "expiresAt": "2026-12-14T10:00:00.000Z"
}

GET/media/{id}

Obtener un archivo subido

Requiere el permiso messages:send. Tipo, tamaño y vencimiento. 404 si no existe o ya caducó.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/media/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmmed_01",
  "type": "document",
  "mimeType": "application/pdf",
  "filename": "Catálogo 2026.pdf",
  "bytes": 482113,
  "sha256": "9f2c…",
  "createdAt": "2026-11-14T10:00:00.000Z",
  "expiresAt": "2026-12-14T10:00:00.000Z"
}

DELETE/media/{id}

Borrar un archivo subido

Requiere el permiso messages:send. Lo borra antes de que caduque. Los mensajes que ya salieron con él no cambian.

ParámetroEnDescripción
idrutastring

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/media/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmmed_01",
  "deleted": true
}

POST/messages/{id}/reaction

Reaccionar a un mensaje

Requiere el permiso messages:send. Solo WhatsApp. Reacciona con un emoji a un mensaje entrante o saliente de los últimos 30 días; emoji: "" quita la reacción. Una reacción nueva reemplaza a la anterior. Cuenta para el límite por minuto de envíos, no para el cupo diario. 409 si otra reacción a ese mensaje sigue en curso.

ParámetroEnDescripción
idrutastring
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
emojistringUn solo emoji, o "" para quitarla

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/messages/ID/reaction" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"emoji":"👍"}'

Respuesta 201

{
  "messageId": "cmmsg_01",
  "emoji": "👍",
  "status": "accepted"
}

GET/messages/{id}

Obtener un mensaje

Requiere el permiso conversations:read. Cualquier canal, con su estado y su medio actuales (p. ej. para releer un media_placeholder del historial cuando ya llegó el medio).

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/messages/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmmsg_01",
  "conversationId": "cmchat_01",
  "direction": "INBOUND",
  "type": "text",
  "text": "¿Tienen envío a Puebla?",
  "caption": null,
  "mimeType": null,
  "filename": null,
  "status": null,
  "senderId": null,
  "interactive": null,
  "timestamp": "2026-10-18T19:02:11.000Z",
  "externalId": "wamid.HBgNNTIxNTU1MTExMTIyMjIVAgASGBQzQTk5",
  "content": null,
  "media": null,
  "replyTo": null,
  "reaction": null,
  "transcript": null,
  "error": null,
  "deliveredAt": null,
  "readAt": null,
  "pricing": null,
  "origin": "contact",
  "sentBy": "contact",
  "senderName": null,
  "referral": null,
  "createdAt": "2026-10-18T19:02:12.000Z"
}

GET/messages

Mensajes nuevos de todas las conversaciones

Requiere el permiso conversations:read. Todo lo que Colibly guardó desde since en las conversaciones al alcance de la key (entrantes y salientes, cualquier canal), del más viejo al más nuevo por createdAt. Sirve para ponerse al día sin depender solo de los webhooks: guarda el createdAt del último mensaje recibido y úsalo como el siguiente since (o sigue con nextCursor). Un cambio de estado no vuelve a traer el mensaje: llega por message.status_changed o con GET /messages/{id}. Límite propio: 60 por minuto por key.

ParámetroEnDescripción
sincequerystring
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior
accountId?querystring
direction?queryINBOUND | OUTBOUND

Ejemplo

curl "https://app.colibly.com/api/v1/messages?since=2026-11-04T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmmsg_01",
      "conversationId": "cmchat_01",
      "direction": "INBOUND",
      "type": "text",
      "text": "¿Tienen envío a Puebla?",
      "caption": null,
      "mimeType": null,
      "filename": null,
      "status": null,
      "senderId": null,
      "interactive": null,
      "timestamp": "2026-10-18T19:02:11.000Z",
      "externalId": "wamid.HBgNNTIxNTU1MTExMTIyMjIVAgASGBQzQTk5",
      "content": null,
      "media": null,
      "replyTo": null,
      "reaction": null,
      "transcript": null,
      "error": null,
      "deliveredAt": null,
      "readAt": null,
      "pricing": null,
      "origin": "contact",
      "sentBy": "contact",
      "senderName": null,
      "referral": null,
      "createdAt": "2026-10-18T19:02:12.000Z"
    }
  ],
  "nextCursor": null
}

POST/messages

Enviar mensaje

Requiere el permiso messages:send. Destino (uno): conversationId, contactId o accountId + to (WhatsApp: el teléfono con código de país; si el contacto no existe se crea, solo con una plantilla). En WhatsApp todo salvo las plantillas va solo dentro de la ventana de 24 h (fuera de ella: 422 window_closed → usa una plantilla aprobada). Una plantilla a un contacto sin chat abre el chat. Tipos: text, buttons (hasta 3), list (hasta 10 opciones), template, archivos (abajo) y, solo en WhatsApp, sticker (WebP 512×512 por media.url), location, location_request (botón "Enviar ubicación"; la respuesta llega como mensaje entrante location), cta_url (botón que abre una URL) flow (abre un WhatsApp Flow: formulario dentro del chat) y del catálogo de Meta product (un producto), product_list (hasta 30 productos en 10 secciones) y catalog (botón "Ver catálogo"). Sin catalogId se usa el único catálogo conectado a la cuenta (GET /accounts/{id}/catalog); los productos se identifican por su product_retailer_id ("ID de contenido" en Commerce Manager). Un pedido del carrito llega como mensaje order y como evento order.received. Flows: flow.id de GET /accounts/{id}/flows, flow.cta (texto del botón) y flow.screen (primera pantalla; sin ella el Flow pide datos a su endpoint). La respuesta del cliente llega como mensaje con content.flowResponse y como evento flow.completed, con el flow.token que mandaste. La opción que elige el cliente en buttons o list llega en message.received con interactive.reply.id. `replyTo` (WhatsApp): id de un mensaje de la misma conversación para citarlo. Manda siempre `Idempotency-Key`: si reintentas por un timeout, el mensaje no sale dos veces. Tarjetas de contacto (contacts, solo WhatsApp): hasta 10, cada una con name y al menos un teléfono o correo. Archivos (type image, document, audio o video): pasa media.url, una URL https pública (Colibly la descarga y la manda por el canal), o media.id de un archivo subido con POST /media para reusarlo sin volver a descargarlo. Tipos y tamaños admitidos (los de WhatsApp, para que el mismo envío sirva en todos los canales): image hasta 5 MB (jpeg, png); document hasta 20 MB (pdf, plain, csv, msword, vnd.openxmlformats-officedocument.wordprocessingml.document, vnd.ms-excel, vnd.openxmlformats-officedocument.spreadsheetml.sheet, vnd.ms-powerpoint, vnd.openxmlformats-officedocument.presentationml.presentation); audio hasta 16 MB (aac, amr, mpeg, mp4, ogg); video hasta 16 MB (mp4, 3gpp). Una URL que no responde, un tipo no admitido o un archivo muy grande dan 400 con details[0].path = "media.url". El chat web todavía no recibe archivos, y Messenger e Instagram no admiten caption.

ParámetroEnDescripción
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
conversationId?string
contactId?string
accountId?stringCuenta de WhatsApp que envía (con `to`)
to?stringTeléfono con código de país (con `accountId`); se toman solo los dígitos; 10 dígitos sin `+` se toman como México (+52)
typetext | buttons | list | template | image | document | audio | video | sticker | location | location_request | cta_url | product | product_list | catalog | flow | contacts
text?stringRequerido para text, buttons, list, cta_url y location_request
buttons?object[]
template?objectLo que pide cada plantilla está en `send` de GET /templates.
media?objectRequerido para image, document, audio, video y sticker: `url` o `id` (uno). Colibly descarga la URL al enviar (sin redirecciones, 30 s como máximo). Un sticker es WebP de 512×512, hasta 100 KB (500 KB animado).
contacts?object[]type contacts (WhatsApp)
caption?stringTexto junto al archivo (image, video, document). No en audio, ni en Messenger/Instagram
list?objecttype list
cta?objecttype cta_url (WhatsApp)
location?objecttype location (WhatsApp)
replyTo?stringId de un mensaje de la misma conversación para citarlo (WhatsApp)
product?objecttype product (WhatsApp). `text` es opcional
productList?objecttype product_list (WhatsApp), con `text`. Hasta 10 secciones y 30 productos
catalog?objecttype catalog (WhatsApp), con `text`
flow?objecttype flow (WhatsApp), con `text`
footer?stringPie de product, product_list, catalog o flow

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/messages" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"conversationId":"cmchat_01","type":"text","text":"Sí, enviamos a todo México."}'

Respuesta 200

{
  "id": null,
  "conversationId": "cmchat_01",
  "externalId": null,
  "test": true,
  "preview": {
    "type": "text",
    "text": "Sí, enviamos a todo México.",
    "template": null
  }
}

Llamadas

Llamadas de WhatsApp (Calling API): historial y eventos call.*

GET/calls

Llamadas de WhatsApp

Requiere el permiso conversations:read. Llamadas entrantes y salientes de las cuentas de WhatsApp de la key, más recientes primero. En vivo llegan por los eventos call.ringing, call.answered y call.ended. Filtros: accountId, contactId, status, direction (inbound u outbound) y since.

ParámetroEnDescripción
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior
accountId?querystring
contactId?querystring
status?queryRINGING | CONNECTING | ACTIVE | ENDED | MISSED | REJECTED | FAILED
direction?queryinbound | outbound
since?querystring

Ejemplo

curl "https://app.colibly.com/api/v1/calls?status=MISSED&limit=20" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmcall_01",
      "accountId": "cmacc_wa_01",
      "conversationId": "cmchat_01",
      "contactId": "cmcon_01",
      "direction": "inbound",
      "status": "ENDED",
      "phone": "5215512345678",
      "name": "Ana López",
      "answeredById": "cmusr_02",
      "startedAt": "2026-10-18T19:02:11.000Z",
      "endedAt": "2026-10-18T19:05:15.000Z",
      "durationSeconds": 184,
      "hasRecording": false,
      "transcript": null,
      "createdAt": "2026-10-18T19:01:58.000Z"
    }
  ],
  "nextCursor": null
}

GET/calls/{id}

Obtener una llamada

Requiere el permiso conversations:read. Con su transcripción si Meta la mandó.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/calls/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmcall_01",
  "accountId": "cmacc_wa_01",
  "conversationId": "cmchat_01",
  "contactId": "cmcon_01",
  "direction": "inbound",
  "status": "ENDED",
  "phone": "5215512345678",
  "name": "Ana López",
  "answeredById": "cmusr_02",
  "startedAt": "2026-10-18T19:02:11.000Z",
  "endedAt": "2026-10-18T19:05:15.000Z",
  "durationSeconds": 184,
  "hasRecording": false,
  "transcript": null,
  "createdAt": "2026-10-18T19:01:58.000Z"
}

Automatizaciones

POST/automations/{id}/runs

Iniciar una automatización manual

Requiere el permiso automations:run. Solo automatizaciones activas con disparador “Manual”. 409 si ya hay una ejecución en curso para ese contacto u otra automatización conversacional atiende su chat.

ParámetroEnDescripción
idrutastring
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
contactIdstring
vars?objectDisponibles como {{var.x}}

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/automations/cmaut_01/runs" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"contactId":"cmcon_01","vars":{"pedido":"A-1043"}}'

Respuesta 201

{
  "runId": "cmrun_01"
}

Catálogos

Ids que piden los demás endpoints: plantillas, etiquetas, personas y automatizaciones

GET/templates

Plantillas de WhatsApp

Requiere el permiso messages:send. Plantillas de las cuentas de WhatsApp de la key, con lo que pide cada una en POST /messages (type: "template"): send describe todo: bodyParams como lista ({{1}}…) o como objeto ({{nombre}}, parameterFormat: NAMED), headerParam si send.header.required (texto, o URL https / media id si es IMAGE, VIDEO o DOCUMENT; headerLocation si es LOCATION), un elemento de buttons por cada botón con param (urlParam, couponCode, payload, flowToken), code en AUTHENTICATION, offerExpiresAt si send.offer.hasExpiration y cards con send.carouselCards elementos. params queda por compatibilidad. Solo las APPROVED se pueden enviar. Lista completa, por nombre.

ParámetroEnDescripción
accountId?querystring
status?queryEstado de Meta: APPROVED, PENDING, REJECTED, PAUSED, DISABLED…

Ejemplo

curl "https://app.colibly.com/api/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmtpl_01",
      "accountId": "cmacc_wa_01",
      "name": "confirmacion_pedido",
      "language": "es_MX",
      "category": "UTILITY",
      "status": "APPROVED",
      "statusReason": null,
      "params": {
        "bodyParamCount": 2,
        "header": null,
        "buttonParamRequired": false
      },
      "send": {
        "parameterFormat": "POSITIONAL",
        "bodyParams": 2,
        "header": null,
        "buttons": [
          {
            "index": 0,
            "type": "URL",
            "text": "Rastrear",
            "param": "urlParam",
            "required": true
          }
        ],
        "requiresCode": false,
        "offer": null,
        "carouselCards": null
      },
      "bodyText": "Hola {{1}}, tu pedido {{2}} va en camino.",
      "syncedAt": "2026-10-18T12:00:00.000Z"
    }
  ]
}

GET/templates/{id}/analytics

Métricas de una plantilla

Requiere el permiso messages:send. Enviados, entregados, leídos y clics por día según Meta, con totals. Por omisión, los últimos 30 días; Meta conserva hasta 90.

ParámetroEnDescripción
idrutastring
since?querystring
until?querystring

Ejemplo

curl "https://app.colibly.com/api/v1/templates/ID/analytics" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "templateId": "cmtpl_01",
  "since": "2026-10-14T00:00:00.000Z",
  "until": "2026-11-13T00:00:00.000Z",
  "totals": {
    "sent": 40,
    "delivered": 38,
    "read": 30,
    "clicked": 6
  },
  "data": [
    {
      "date": "2026-11-12T00:00:00.000Z",
      "sent": 40,
      "delivered": 38,
      "read": 30,
      "clicked": 6
    }
  ]
}

GET/templates/{id}

Obtener una plantilla

Requiere el permiso messages:send. Igual que en GET /templates, más components tal como los guarda Meta (HEADER, BODY, FOOTER, BUTTONS).

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/templates/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmtpl_01",
  "accountId": "cmacc_wa_01",
  "name": "confirmacion_pedido",
  "language": "es_MX",
  "category": "UTILITY",
  "status": "APPROVED",
  "statusReason": null,
  "params": {
    "bodyParamCount": 2,
    "header": null,
    "buttonParamRequired": false
  },
  "send": {
    "parameterFormat": "POSITIONAL",
    "bodyParams": 2,
    "header": null,
    "buttons": [
      {
        "index": 0,
        "type": "URL",
        "text": "Rastrear",
        "param": "urlParam",
        "required": true
      }
    ],
    "requiresCode": false,
    "offer": null,
    "carouselCards": null
  },
  "bodyText": "Hola {{1}}, tu pedido {{2}} va en camino.",
  "syncedAt": "2026-10-18T12:00:00.000Z"
}

POST/templates/sync

Sincronizar plantillas con Meta

Requiere el permiso messages:send. Consulta a Meta las plantillas de las cuentas de WhatsApp de la key (todas, o una con accountId) y devuelve la lista ya actualizada, con el formato de GET /templates. Úsalo después de crear una plantilla para ver su revisión (PENDING → APPROVED o REJECTED, con statusReason) sin esperar. Meta también avisa por webhook y Colibly refresca las pendientes solo; este es el atajo explícito. synced lista las cuentas que respondieron y failed las que no. Las plantillas que Meta ya no devuelve quedan como DELETED (no se borran). Límite: 6 por minuto por organización.

ParámetroEnDescripción
accountId?querystring

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/templates/sync" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmtpl_01",
      "accountId": "cmacc_wa_01",
      "name": "confirmacion_pedido",
      "language": "es_MX",
      "category": "UTILITY",
      "status": "APPROVED",
      "statusReason": null,
      "params": {
        "bodyParamCount": 2,
        "header": null,
        "buttonParamRequired": false
      },
      "send": {
        "parameterFormat": "POSITIONAL",
        "bodyParams": 2,
        "header": null,
        "buttons": [
          {
            "index": 0,
            "type": "URL",
            "text": "Rastrear",
            "param": "urlParam",
            "required": true
          }
        ],
        "requiresCode": false,
        "offer": null,
        "carouselCards": null
      },
      "bodyText": "Hola {{1}}, tu pedido {{2}} va en camino.",
      "syncedAt": "2026-10-18T12:00:00.000Z"
    }
  ],
  "synced": [
    "cmacc_wa_01"
  ],
  "failed": []
}

GET/tags

Etiquetas

Requiere el permiso contacts:read. Etiquetas de contacto de las cuentas de la key (cada cuenta tiene las suyas). Para GET /contacts?tagId= y POST /contacts/{id}/tags. Lista completa, por nombre.

ParámetroEnDescripción
accountId?querystring

Ejemplo

curl "https://app.colibly.com/api/v1/tags" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmtag_01",
      "accountId": "cmacc_wa_01",
      "name": "Mayoreo",
      "color": "accent",
      "createdAt": "2026-10-01T16:20:00.000Z"
    }
  ]
}

GET/users

Personas de la organización

Requiere el permiso conversations:read. Para traducir assignedToId y para asignar con PATCH /conversations/{id}. Incluye las desactivadas (active: false), que pueden seguir en conversaciones viejas. Lista completa, por nombre.

Ejemplo

curl "https://app.colibly.com/api/v1/users" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmusr_02",
      "name": "Carlos Ventas",
      "email": "carlos@ejemplo.mx",
      "role": "user",
      "active": true
    }
  ]
}

GET/teams

Equipos

Requiere el permiso conversations:read. Equipos de la organización (Usuarios → Equipos), para traducir teamId y mover conversaciones con PATCH /conversations/{id}. Un equipo enruta la asignación automática; no da permisos. memberIds = personas activas. Lista completa, por nombre.

Ejemplo

curl "https://app.colibly.com/api/v1/teams" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmteam_01",
      "name": "Ventas",
      "memberIds": [
        "cmusr_02"
      ],
      "createdAt": "2026-11-05T15:00:00.000Z"
    }
  ]
}

GET/automations

Automatizaciones

Requiere el permiso automations:run. Automatizaciones de las cuentas de la key (sin archivadas). runnable: true = activa con disparador "Manual": la que acepta POST /automations/{id}/runs. Lista completa, por nombre.

ParámetroEnDescripción
accountId?querystring
runnable?querySolo las que se pueden iniciar por API

Ejemplo

curl "https://app.colibly.com/api/v1/automations?runnable=true" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmaut_01",
      "accountId": "cmacc_wa_01",
      "name": "Pedido confirmado",
      "description": "Avisa al cliente y lo etiqueta",
      "status": "ACTIVE",
      "triggerType": "manual",
      "runnable": true,
      "updatedAt": "2026-10-15T18:00:00.000Z"
    }
  ]
}

Webhooks

Administración de webhooks salientes por API

GET/webhooks

Listar webhooks

Requiere el permiso webhooks:manage.

Ejemplo

curl "https://app.colibly.com/api/v1/webhooks" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmwh_01",
      "name": "ERP pedidos",
      "url": "https://erp.ejemplo.mx/colibly/eventos",
      "events": [
        "contact.created",
        "contact.lead_status_changed"
      ],
      "accountIds": [],
      "channelAccountIds": [],
      "active": true,
      "status": "active",
      "ownerId": "cmusr_01",
      "pausedAt": null,
      "pausedReason": null,
      "disabledAt": null,
      "consecutiveFailures": 0,
      "lastDeliveryAt": "2026-10-18T19:02:13.000Z",
      "previousSecretExpiresAt": null,
      "createdAt": "2026-10-01T15:00:00.000Z"
    }
  ]
}

POST/webhooks

Crear webhook

Requiere el permiso webhooks:manage. La respuesta incluye secret (whsec_...) una sola vez: guárdalo para verificar la firma. Máximo 10 webhooks por cuenta (409 limit_reached).

Campo del cuerpoTipoDescripción
namestring
urlstringhttps:// y pública (no se aceptan direcciones internas)
events* | message.received | message.sent | message.status_changed | message.updated | contact.created | contact.lead_status_changed | contact.marketing_preference_changed | tag.added | conversation.assigned | conversation.resolved | conversation.welcome_requested | appointment.created | appointment.status_changed | lead.scored | lead.ad_captured | flow.completed | order.received | template.status_changed | template.category_changed | account.quality_changed | account.connected | call.ringing | call.answered | call.ended[]"*" = todos
accountIds?string[]Vacío = todas
channelAccountIds?string[]

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/webhooks" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"ERP pedidos","url":"https://erp.ejemplo.mx/colibly/eventos","events":["contact.created","contact.lead_status_changed"]}'

Respuesta 201

{
  "id": "cmwh_01",
  "name": "ERP pedidos",
  "url": "https://erp.ejemplo.mx/colibly/eventos",
  "events": [
    "contact.created",
    "contact.lead_status_changed"
  ],
  "accountIds": [],
  "channelAccountIds": [],
  "active": true,
  "status": "active",
  "ownerId": "cmusr_01",
  "pausedAt": null,
  "pausedReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2026-10-18T19:02:13.000Z",
  "previousSecretExpiresAt": null,
  "createdAt": "2026-10-01T15:00:00.000Z",
  "secret": "whsec_9fK2…"
}

GET/webhooks/{id}

Obtener webhook

Requiere el permiso webhooks:manage.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/webhooks/cmwh_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmwh_01",
  "name": "ERP pedidos",
  "url": "https://erp.ejemplo.mx/colibly/eventos",
  "events": [
    "contact.created",
    "contact.lead_status_changed"
  ],
  "accountIds": [],
  "channelAccountIds": [],
  "active": true,
  "status": "active",
  "ownerId": "cmusr_01",
  "pausedAt": null,
  "pausedReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2026-10-18T19:02:13.000Z",
  "previousSecretExpiresAt": null,
  "createdAt": "2026-10-01T15:00:00.000Z"
}

PATCH/webhooks/{id}

Editar / reactivar webhook

Requiere el permiso webhooks:manage. active: true reactiva uno desactivado por fallos (reinicia el contador). Uno con status: paused (su creador dejó de ser admin) solo se reactiva con takeOwnership: true: pasa a ser del dueño de la key.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
name?string
url?string
events?string[]
accountIds?string[]
channelAccountIds?string[]
active?boolean
takeOwnership?booleanPasa el webhook al dueño de la key; obligatorio para reactivar uno pausado

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/webhooks/cmwh_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":true,"takeOwnership":true}'

Respuesta 200

{
  "id": "cmwh_01",
  "name": "ERP pedidos",
  "url": "https://erp.ejemplo.mx/colibly/eventos",
  "events": [
    "contact.created",
    "contact.lead_status_changed"
  ],
  "accountIds": [],
  "channelAccountIds": [],
  "active": true,
  "status": "active",
  "ownerId": "cmusr_01",
  "pausedAt": null,
  "pausedReason": null,
  "disabledAt": null,
  "consecutiveFailures": 0,
  "lastDeliveryAt": "2026-10-18T19:02:13.000Z",
  "previousSecretExpiresAt": null,
  "createdAt": "2026-10-01T15:00:00.000Z"
}

DELETE/webhooks/{id}

Eliminar webhook

Requiere el permiso webhooks:manage. Borra también su registro de entregas.

ParámetroEnDescripción
idrutastring

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/webhooks/cmwh_01" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "deleted": true
}

POST/webhooks/{id}/test

Enviar un evento de prueba

Requiere el permiso webhooks:manage. Entrega un evento webhook.test firmado a ese endpoint, como una entrega real (reintentos e historial incluidos), para validar la URL y tu verificación de firma. Su resultado se lee en GET /webhooks/{id}/deliveries/{deliveryId}. Un webhook desactivado responde 409. Límite: 10 por minuto por organización.

ParámetroEnDescripción
idrutastring

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/webhooks/ID/test" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 202

{
  "deliveryId": "cmwhd_01",
  "status": "pending"
}

POST/webhooks/{id}/rotate-secret

Rotar el secreto

Requiere el permiso webhooks:manage. Genera un secreto nuevo y lo devuelve (única vez que se ve). Sin cuerpo (o graceHours: 0) el anterior deja de firmar de inmediato. Con graceHours (1 a 72) el anterior sigue firmando ese tiempo: cada entrega lleva t=…,v1=<nuevo>,v1=<anterior>, así que puedes cambiar el secreto de tu receptor sin perder entregas (tu verificador debe aceptar si cualquiera de las v1 coincide; las recetas de la documentación ya lo hacen). Rotar otra vez descarta el más viejo.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
graceHours?integer

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/webhooks/ID/rotate-secret" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"graceHours":24}'

Respuesta 200

{
  "id": "cmwh_01",
  "secret": "whsec_Q7v…",
  "previousSecretExpiresAt": "2026-11-06T16:00:00.000Z"
}

GET/webhooks/{id}/deliveries

Historial de entregas

Requiere el permiso webhooks:manage. Entregas del endpoint, las más recientes primero (se guardan 30 días). Sin el cuerpo: pídelo con GET /webhooks/{id}/deliveries/{deliveryId}.

ParámetroEnDescripción
idrutastring
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior
status?querypending | sent | failed
eventType?querystring
since?querySolo las creadas desde esa fecha

Ejemplo

curl "https://app.colibly.com/api/v1/webhooks/ID/deliveries?status=failed&limit=20" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "cmwhd_01",
      "eventId": "7d1f2c9e-3b4a-4f0e-9a51-0c2b8e6d4f10",
      "eventType": "message.status_changed",
      "status": "failed",
      "attempts": 6,
      "responseCode": 500,
      "error": "HTTP 500",
      "createdAt": "2026-10-18T19:02:11.000Z",
      "deliveredAt": null
    }
  ],
  "nextCursor": null
}

GET/webhooks/{id}/deliveries/{deliveryId}

Obtener una entrega

Requiere el permiso webhooks:manage. Con payload: el cuerpo exacto que se envió (lo que firma X-Colibly-Signature).

ParámetroEnDescripción
idrutastring
deliveryIdrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/webhooks/ID/deliveries/{deliveryId}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmwhd_01",
  "eventId": "7d1f2c9e-3b4a-4f0e-9a51-0c2b8e6d4f10",
  "eventType": "message.status_changed",
  "status": "failed",
  "attempts": 6,
  "responseCode": 500,
  "error": "HTTP 500",
  "createdAt": "2026-10-18T19:02:11.000Z",
  "deliveredAt": null,
  "payload": {
    "id": "7d1f2c9e-3b4a-4f0e-9a51-0c2b8e6d4f10",
    "type": "message.status_changed",
    "occurredAt": "2026-10-18T19:02:11.000Z",
    "account": {
      "id": "cmacc_wa_01",
      "channel": "WHATSAPP",
      "name": "Ventas CDMX",
      "phoneNumber": "+52 1 55 1234 5678",
      "phoneE164": "+525512345678"
    },
    "contact": {
      "id": "cmcon_01",
      "name": "Ana López",
      "realName": null,
      "tags": [
        {
          "id": "cmtag_01",
          "name": "Mayoreo"
        }
      ],
      "phone": "5215598765432",
      "phoneE164": "+525598765432",
      "externalId": null,
      "leadStatus": "QUALIFIED",
      "leadOrigin": "ORGANIC"
    },
    "conversation": {
      "id": "cmchat_01",
      "channel": "WHATSAPP",
      "status": "OPEN",
      "assignedToId": "cmusr_02"
    },
    "data": {
      "messageId": "cmmsg_02",
      "status": "delivered",
      "previousStatus": "sent",
      "error": null,
      "pricing": {
        "billable": false,
        "model": "PMP",
        "category": "service",
        "type": "free_customer_service"
      }
    },
    "message": {
      "id": "cmmsg_01",
      "conversationId": "cmchat_01",
      "direction": "INBOUND",
      "type": "text",
      "text": "¿Tienen envío a Puebla?",
      "caption": null,
      "mimeType": null,
      "filename": null,
      "status": null,
      "senderId": null,
      "interactive": null,
      "timestamp": "2026-10-18T19:02:11.000Z",
      "externalId": "wamid.HBgNNTIxNTU1MTExMTIyMjIVAgASGBQzQTk5",
      "content": null,
      "media": null,
      "replyTo": null,
      "reaction": null,
      "transcript": null,
      "error": null,
      "deliveredAt": null,
      "readAt": null,
      "pricing": null,
      "origin": "contact",
      "sentBy": "contact",
      "senderName": null,
      "referral": null,
      "createdAt": "2026-10-18T19:02:12.000Z"
    }
  }
}

POST/webhooks/{id}/deliveries/{deliveryId}/replay

Reenviar una entrega

Requiere el permiso webhooks:manage. Vuelve a entregar el mismo evento (mismo cuerpo y mismo X-Colibly-Event-Id, intentos desde cero) a ese endpoint. Para entregas fallidas o ya entregadas; una en curso o un webhook desactivado responde 409 conflict. Límite: 30 por minuto por organización.

ParámetroEnDescripción
idrutastring
deliveryIdrutastring
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/webhooks/ID/deliveries/{deliveryId}/replay" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11"

Respuesta 202

{
  "id": "cmwhd_01",
  "status": "pending"
}

WhatsApp

Administración de la cuenta en Meta: estado del número, perfil de empresa, bloqueos, plantillas, Flows, números, PIN y enlaces de conexión

GET/accounts/{id}

Cuenta y estado del número

Sin permiso especial. En WhatsApp trae health: calidad del número (qualityRating), límite de envío (messagingTier), estado del nombre para mostrar, si puede enviar (canSendMessage) y los avisos de Meta en español. Se vuelve a leer de Meta como mucho cada 10 minutos (health.checkedAt). Otros canales: health: null.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmacc_wa_01",
  "channel": "WHATSAPP",
  "name": "Ventas CDMX",
  "phoneNumber": "+52 1 55 1234 5678",
  "phoneE164": "+525512345678",
  "status": "CONNECTED",
  "wabaId": "102290129340398",
  "phoneNumberId": "106540352242922",
  "coexistence": false,
  "health": {
    "qualityRating": "GREEN",
    "lastQualityEvent": "UPGRADE",
    "messagingTier": "TIER_10K",
    "nameStatus": "APPROVED",
    "canSendMessage": "AVAILABLE",
    "notices": [],
    "checkedAt": "2026-11-13T17:00:00.000Z"
  },
  "createdAt": "2026-10-01T16:00:00.000Z"
}

GET/accounts/{id}/profile

Perfil de empresa

Sin permiso especial. El perfil que ven los clientes en WhatsApp, leído de Meta al momento. 422 si la cuenta no está conectada a WhatsApp Cloud API.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/profile" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "about": "Respondemos de 9 a 19 h",
  "address": "Av. Reforma 100, CDMX",
  "description": "Muebles a la medida con envío a todo México",
  "email": "ventas@ejemplo.mx",
  "websites": [
    "https://ejemplo.mx"
  ],
  "vertical": "RETAIL",
  "profilePictureUrl": "https://pps.whatsapp.net/v/t61/ejemplo.jpg"
}

PATCH/accounts/{id}/profile

Editar el perfil de empresa

Requiere el permiso whatsapp:manage. Solo cambia los campos enviados; "" borra uno (salvo about). profilePictureUrl: JPG o PNG de hasta 5 MB por https; Colibly lo sube a Meta (la cuenta necesita App ID). Responde el perfil ya actualizado; la foto nueva puede tardar unos segundos en aparecer en profilePictureUrl. Límite: 30 cambios por minuto por organización entre perfil, bloqueos y plantillas.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
about?string
address?string
description?string
email?string"" lo borra
websites?string[]
vertical?stringCategoría de Meta en mayúsculas
profilePictureUrl?stringJPG o PNG de hasta 5 MB por https

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/accounts/ID/profile" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"about":"Respondemos de 9 a 19 h","websites":["https://ejemplo.mx"]}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "about": "Respondemos de 9 a 19 h",
  "address": "Av. Reforma 100, CDMX",
  "description": "Muebles a la medida con envío a todo México",
  "email": "ventas@ejemplo.mx",
  "websites": [
    "https://ejemplo.mx"
  ],
  "vertical": "RETAIL",
  "profilePictureUrl": "https://pps.whatsapp.net/v/t61/ejemplo.jpg"
}

GET/accounts/{id}/blocked-users

Usuarios bloqueados

Requiere el permiso whatsapp:manage. La lista de bloqueo del número, leída de Meta. nextCursor es el de Meta: pásalo en cursor.

ParámetroEnDescripción
idrutastring
limit?queryEntero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400
cursor?querynextCursor de la página anterior

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/blocked-users" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "phone": "5215512345678"
    }
  ],
  "nextCursor": null
}

POST/accounts/{id}/blocked-users

Bloquear usuarios

Requiere el permiso whatsapp:manage. Un bloqueado no puede escribir al número ni recibir mensajes de él. Regla de Meta: solo a quien escribió en las últimas 24 h. Hasta 100 teléfonos por llamada; responde 200 con el resultado de cada uno (blocked y failed).

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
phonesstring[]Con código de país; 10 dígitos = México

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/blocked-users" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones":["+5215512345678"]}'

Respuesta 200

{
  "blocked": [
    {
      "phone": "5215512345678"
    }
  ],
  "failed": []
}

DELETE/accounts/{id}/blocked-users/{phone}

Desbloquear un usuario

Requiere el permiso whatsapp:manage.

ParámetroEnDescripción
idrutastring
phonerutaCon código de país; 10 dígitos = México

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/accounts/ID/blocked-users/{phone}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "phone": "5215512345678",
  "blocked": false
}

GET/accounts/{id}/analytics

Costos y volumen de mensajes

Requiere el permiso whatsapp:manage. Mensajes cobrables y su costo según Meta (modelo por mensaje) del número de la cuenta, por día o por mes, desglosados por país, categoría (MARKETING, UTILITY, AUTHENTICATION, SERVICE) y tipo de precio (REGULAR, FREE_CUSTOMER_SERVICE, FREE_ENTRY_POINT…). El costo está en la moneda de la cuenta de WhatsApp Business en Meta. Por omisión, los últimos 30 días; máximo 365.

ParámetroEnDescripción
idrutastring
since?querystring
until?querystring
granularity?queryDAILY | MONTHLY

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/analytics" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "since": "2026-10-14T00:00:00.000Z",
  "until": "2026-11-13T00:00:00.000Z",
  "granularity": "DAILY",
  "totals": {
    "volume": 120,
    "cost": 61.2
  },
  "data": [
    {
      "start": "2026-11-12T00:00:00.000Z",
      "end": "2026-11-13T00:00:00.000Z",
      "phone": "525512345678",
      "country": "MX",
      "category": "MARKETING",
      "pricingType": "REGULAR",
      "volume": 120,
      "cost": 61.2
    }
  ]
}

GET/accounts/{id}/conversational-automation

Sugerencias de inicio y comandos

Sin permiso especial. prompts son los botones que ve el cliente al abrir el chat; commands, lo que aparece al escribir "/". Al tocarlos, el cliente manda ese texto como un mensaje normal. welcomeMessageEnabled (Meta) y welcomeMessageText (Colibly): el saludo a quien abre el chat por primera vez.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/conversational-automation" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "welcomeMessageEnabled": true,
  "welcomeMessageText": "¡Hola! Gracias por escribirnos. ¿En qué te ayudamos?",
  "prompts": [
    "Quiero una cotización",
    "¿Dónde están?"
  ],
  "commands": [
    {
      "name": "horarios",
      "description": "Horario de atención"
    }
  ]
}

PATCH/accounts/{id}/conversational-automation

Cambiar sugerencias y comandos

Requiere el permiso whatsapp:manage. Solo cambia lo enviado; [] borra la lista. Hasta 4 sugerencias de 80 caracteres y 30 comandos (nombre de 32, sin "/" ni espacios; descripción de 256). WhatsApp puede tardar en mostrarlos. welcomeMessage: con enabled: true WhatsApp avisa cuando alguien abre el chat por primera vez sin escribir; Colibly guarda un aviso (type: "request_welcome"), emite conversation.welcome_requested y, si hay text, lo contesta (una vez, y nunca si alguien ya le escribió). Sin text, el saludo queda en tus manos con el evento. text: null lo borra.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
prompts?string[]
commands?object[]
welcomeMessage?object

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/accounts/ID/conversational-automation" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts":["Quiero una cotización","¿Dónde están?"],"welcomeMessage":{"enabled":true,"text":"¡Hola! Gracias por escribirnos. ¿En qué te ayudamos?"}}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "welcomeMessageEnabled": true,
  "welcomeMessageText": "¡Hola! Gracias por escribirnos. ¿En qué te ayudamos?",
  "prompts": [
    "Quiero una cotización",
    "¿Dónde están?"
  ],
  "commands": [
    {
      "name": "horarios",
      "description": "Horario de atención"
    }
  ]
}

GET/accounts/{id}/flows

WhatsApp Flows

Requiere el permiso messages:send. Los Flows (formularios dentro de WhatsApp) de la cuenta: los del constructor del Administrador de WhatsApp y los creados con POST aquí. Se mandan con POST /messages type: "flow": los PUBLISHED, o un DRAFT con flow.draft: true para probarlo.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/flows" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "id": "1234567890123456",
      "name": "Agendar visita",
      "status": "PUBLISHED",
      "categories": [
        "APPOINTMENT_BOOKING"
      ]
    }
  ]
}

POST/accounts/{id}/flows

Crear un Flow

Requiere el permiso whatsapp:manage. Crea el Flow en DRAFT con su flowJson (formato de WhatsApp Flows: version y screens) o clonando otro (cloneFlowId). publish: true lo publica de una vez si el JSON no tiene errores. Responde el Flow con los validationErrors de Meta. Para un Flow que consulta tu sistema en cada pantalla (data_exchange), usa useColiblyEndpoint: true (tras PATCH /accounts/{id}/flows-endpoint) o tu propio endpointUri.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
namestring
categoriesSIGN_UP | SIGN_IN | APPOINTMENT_BOOKING | LEAD_GENERATION | CONTACT_US | CUSTOMER_SUPPORT | SURVEY | OTHER[]
flowJson?objectJSON del Flow (version, screens…)
cloneFlowId?string
endpointUri?string | nullTu endpoint (https), si cifras tú
useColiblyEndpoint?booleanUsar el endpoint de Colibly (reenvía a tu URL ya descifrado)
publish?boolean

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/flows" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agendar visita","categories":["APPOINTMENT_BOOKING"],"flowJson":{"version":"6.3","screens":[{"id":"CITA","title":"Agenda tu visita","terminal":true,"layout":{"type":"SingleColumnLayout","children":[]}}]}}'

Respuesta 201

{
  "id": "1234567890123456",
  "name": "Agendar visita",
  "status": "DRAFT",
  "categories": [
    "APPOINTMENT_BOOKING"
  ],
  "validationErrors": [],
  "jsonVersion": "6.3",
  "dataApiVersion": null,
  "endpointUri": null,
  "previewUrl": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=…",
  "previewExpiresAt": "2026-11-21T10:00:00+0000"
}

GET/accounts/{id}/flows/{flowId}

Obtener un Flow

Requiere el permiso messages:send. Estado, errores de validación, endpoint y una URL de vista previa (temporal).

ParámetroEnDescripción
idrutastring
flowIdrutaId del Flow en Meta

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/flows/{flowId}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "1234567890123456",
  "name": "Agendar visita",
  "status": "DRAFT",
  "categories": [
    "APPOINTMENT_BOOKING"
  ],
  "validationErrors": [],
  "jsonVersion": "6.3",
  "dataApiVersion": null,
  "endpointUri": null,
  "previewUrl": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=…",
  "previewExpiresAt": "2026-11-21T10:00:00+0000"
}

PATCH/accounts/{id}/flows/{flowId}

Editar un Flow

Requiere el permiso whatsapp:manage. Nombre, categorías, endpoint y/o flowJson. Meta solo deja cambiar el JSON de un Flow en DRAFT; para cambiar uno publicado, clónalo (POST con cloneFlowId).

ParámetroEnDescripción
idrutastring
flowIdrutaId del Flow en Meta
Campo del cuerpoTipoDescripción
name?string
categories?string[]
flowJson?object
endpointUri?string | null
useColiblyEndpoint?boolean

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/accounts/ID/flows/{flowId}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agendar visita (v2)"}'

Respuesta 200

{
  "id": "1234567890123456",
  "name": "Agendar visita",
  "status": "DRAFT",
  "categories": [
    "APPOINTMENT_BOOKING"
  ],
  "validationErrors": [],
  "jsonVersion": "6.3",
  "dataApiVersion": null,
  "endpointUri": null,
  "previewUrl": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=…",
  "previewExpiresAt": "2026-11-21T10:00:00+0000"
}

DELETE/accounts/{id}/flows/{flowId}

Borrar un Flow

Requiere el permiso whatsapp:manage. Solo en DRAFT; uno publicado se retira con …/deprecate.

ParámetroEnDescripción
idrutastring
flowIdrutaId del Flow en Meta

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/accounts/ID/flows/{flowId}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "1234567890123456",
  "deleted": true
}

POST/accounts/{id}/flows/{flowId}/publish

Publicar un Flow

Requiere el permiso whatsapp:manage. Solo sin errores de validación. Ya publicado, su JSON no se puede editar.

ParámetroEnDescripción
idrutastring
flowIdrutaId del Flow en Meta

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/flows/{flowId}/publish" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "1234567890123456",
  "name": "Agendar visita",
  "status": "PUBLISHED",
  "categories": [
    "APPOINTMENT_BOOKING"
  ],
  "validationErrors": [],
  "jsonVersion": "6.3",
  "dataApiVersion": null,
  "endpointUri": null,
  "previewUrl": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=…",
  "previewExpiresAt": "2026-11-21T10:00:00+0000"
}

POST/accounts/{id}/flows/{flowId}/deprecate

Retirar un Flow

Requiere el permiso whatsapp:manage. Deja de poder enviarse y los ya enviados dejan de abrirse. No se puede deshacer.

ParámetroEnDescripción
idrutastring
flowIdrutaId del Flow en Meta

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/flows/{flowId}/deprecate" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "1234567890123456",
  "name": "Agendar visita",
  "status": "DEPRECATED",
  "categories": [
    "APPOINTMENT_BOOKING"
  ],
  "validationErrors": [],
  "jsonVersion": "6.3",
  "dataApiVersion": null,
  "endpointUri": null,
  "previewUrl": "https://business.facebook.com/wa/manage/flows/1234567890123456/preview/?token=…",
  "previewExpiresAt": "2026-11-21T10:00:00+0000"
}

GET/accounts/{id}/flows-endpoint

Endpoint de datos de Flows

Requiere el permiso whatsapp:manage. Colibly aloja el endpoint de datos de los Flows de la cuenta (endpointUri): recibe cada solicitud cifrada de Meta, la descifra y la reenvía como JSON a tu url, firmada con X-Colibly-Signature (igual que los webhooks, con el secret de este endpoint). Tu respuesta ({ screen, data } o { data }, el formato de Meta) vuelve cifrada al cliente. Contesta en menos de 8 s.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/flows-endpoint" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "endpointUri": "https://app.colibly.com/api/whatsapp/flows/endpoint/cmacc_wa_01",
  "url": "https://erp.ejemplo.mx/whatsapp/flows",
  "keyUploadedAt": "2026-11-14T10:00:00.000Z"
}

PATCH/accounts/{id}/flows-endpoint

Configurar el endpoint de Flows

Requiere el permiso whatsapp:manage. url activa o cambia el reenvío; la primera vez genera la llave RSA del número, la sube a Meta y devuelve secret (una sola vez). url: null lo apaga. ?rotateSecret=true genera un secreto nuevo (y lo devuelve).

ParámetroEnDescripción
idrutastring
rotateSecret?queryboolean
Campo del cuerpoTipoDescripción
urlstring | null

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/accounts/ID/flows-endpoint" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.ejemplo.mx/whatsapp/flows"}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "endpointUri": "https://app.colibly.com/api/whatsapp/flows/endpoint/cmacc_wa_01",
  "url": "https://erp.ejemplo.mx/whatsapp/flows",
  "keyUploadedAt": "2026-11-14T10:00:00.000Z",
  "secret": "whsec_3fQm1x9TzK2bLw7aPq0dRs8vXy4n"
}

GET/accounts/{id}/phone-numbers

Números de la cuenta de Meta

Requiere el permiso whatsapp:manage. Todos los números de la cuenta de WhatsApp Business (WABA) de esta cuenta, estén o no conectados a Colibly: estado, calidad, límite de envío, nombre y si están en la app WhatsApp Business. accountId es la cuenta de Colibly de ese número (null si no está conectado en tu organización).

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/phone-numbers" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "wabaId": "102938475610293",
  "data": [
    {
      "phoneNumberId": "109876543210987",
      "displayPhoneNumber": "+52 55 1234 5678",
      "verifiedName": "Muebles Centro",
      "nameStatus": "APPROVED",
      "qualityRating": "GREEN",
      "messagingLimitTier": "TIER_1K",
      "status": "CONNECTED",
      "platformType": "CLOUD_API",
      "codeVerificationStatus": "VERIFIED",
      "isOnBizApp": false,
      "isOfficialBusinessAccount": false,
      "throughput": "STANDARD",
      "accountId": "cmacc_wa_01"
    }
  ]
}

POST/accounts/{id}/two-step-pin

Cambiar el PIN del número

Requiere el permiso whatsapp:manage. PIN de 6 dígitos de la verificación en dos pasos (Meta lo pide para registrar el número). Colibly lo guarda cifrado para volver a registrarlo sin pedirlo.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
pinstring

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/two-step-pin" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pin":"482913"}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "updated": true
}

POST/accounts/{id}/register

Registrar el número en Cloud API

Requiere el permiso whatsapp:manage. Tras darlo de baja o si Meta lo pide. Sin pin usa el que guarda Colibly. No aplica a números de coexistencia (422). La cuenta vuelve a CONNECTED.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
pin?string

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/register" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "registered": true
}

POST/accounts/{id}/deregister

Dar de baja el número de Cloud API

Requiere el permiso whatsapp:manage. El número deja de enviar y recibir hasta registrarlo otra vez. Pide confirm: true. La cuenta queda DISCONNECTED con su historial. No aplica a números de coexistencia (422).

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
confirmboolean

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/deregister" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm":true}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "deregistered": true
}

POST/onboarding-links

Crear un enlace de conexión

Requiere el permiso whatsapp:manage. Para agencias y revendedores: tu cliente abre url, inicia sesión con su Facebook y conecta su número (nuevo o el de su app WhatsApp Business), sin cuenta en Colibly. El número entra a tu organización a nombre del dueño de la key, con las mismas reglas que conectarlo desde el panel (límite del plan, coexistencia de la organización). url solo se devuelve aquí. Al terminar llega account.connected con tu reference, y si diste redirectUrl el cliente vuelve ahí con ?status=connected&accountId=…&reference=…. Vence a las 72 h por omisión (máximo 720).

ParámetroEnDescripción
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
name?stringNombre de la cuenta que se creará (si no, el de Meta)
reference?stringTu id del cliente; vuelve en el evento y en la redirección
redirectUrl?stringhttps; a dónde vuelve el cliente al terminar
expiresInHours?integer

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/onboarding-links" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"name":"Sucursal Norte","reference":"cliente-4521","redirectUrl":"https://agencia.ejemplo.mx/whatsapp/listo"}'

Respuesta 201

{
  "id": "cmobl_01",
  "status": "PENDING",
  "name": "Sucursal Norte",
  "reference": "cliente-4521",
  "redirectUrl": "https://agencia.ejemplo.mx/whatsapp/listo",
  "accountId": null,
  "lastError": null,
  "expiresAt": "2026-11-17T10:00:00.000Z",
  "completedAt": null,
  "createdAt": "2026-11-14T10:00:00.000Z",
  "url": "https://app.colibly.com/conectar/ob_3fQm1x9TzK2bLw7aPq0dRs8vXy4nBc1d"
}

GET/accounts/{id}/catalog

Catálogo y ajustes de comercio

Sin permiso especial. catalogs: los catálogos de Meta conectados a la cuenta (se conectan en el Administrador de WhatsApp; con uno solo, los envíos product y product_list no necesitan catalogId). cartEnabled: el cliente puede armar un pedido en el chat (llega como mensaje order y evento order.received). catalogVisible: el botón de tienda aparece en el perfil y el chat.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/catalog" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "catalogs": [
    {
      "id": "1234567890",
      "name": "Catálogo Tienda Centro"
    }
  ],
  "cartEnabled": true,
  "catalogVisible": true,
  "notices": []
}

PATCH/accounts/{id}/catalog

Cambiar los ajustes de comercio

Requiere el permiso whatsapp:manage. Activa o apaga el carrito y la visibilidad del catálogo.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
cartEnabled?boolean
catalogVisible?boolean

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/accounts/ID/catalog" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cartEnabled":true,"catalogVisible":true}'

Respuesta 200

{
  "accountId": "cmacc_wa_01",
  "catalogs": [
    {
      "id": "1234567890",
      "name": "Catálogo Tienda Centro"
    }
  ],
  "cartEnabled": true,
  "catalogVisible": true,
  "notices": []
}

GET/accounts/{id}/qr-codes

Códigos QR

Sin permiso especial. Códigos QR y enlaces (deepLinkUrl) que abren el chat con un mensaje ya escrito.

ParámetroEnDescripción
idrutastring

Ejemplo

curl "https://app.colibly.com/api/v1/accounts/ID/qr-codes" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "data": [
    {
      "code": "4O4YGZEG3RIVE1",
      "prefilledMessage": "Hola, quiero información de la promoción",
      "deepLinkUrl": "https://wa.me/message/4O4YGZEG3RIVE1",
      "qrImageUrl": "https://scontent.whatsapp.net/v/qr-ejemplo.png"
    }
  ]
}

POST/accounts/{id}/qr-codes

Crear un código QR

Requiere el permiso whatsapp:manage. prefilledMessage hasta 140 caracteres; format de la imagen PNG (por omisión) o SVG. qrImageUrl es temporal: descárgala si la vas a imprimir.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
prefilledMessagestring
format?PNG | SVG

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/accounts/ID/qr-codes" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prefilledMessage":"Hola, quiero información de la promoción"}'

Respuesta 201

{
  "code": "4O4YGZEG3RIVE1",
  "prefilledMessage": "Hola, quiero información de la promoción",
  "deepLinkUrl": "https://wa.me/message/4O4YGZEG3RIVE1",
  "qrImageUrl": "https://scontent.whatsapp.net/v/qr-ejemplo.png"
}

PATCH/accounts/{id}/qr-codes/{code}

Cambiar el mensaje de un código QR

Requiere el permiso whatsapp:manage. El QR y el enlace siguen siendo los mismos.

ParámetroEnDescripción
idrutastring
coderutastring
Campo del cuerpoTipoDescripción
prefilledMessagestring

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/accounts/ID/qr-codes/{code}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prefilledMessage":"Hola, quiero agendar una cita"}'

Respuesta 200

{
  "code": "4O4YGZEG3RIVE1",
  "prefilledMessage": "Hola, quiero información de la promoción",
  "deepLinkUrl": "https://wa.me/message/4O4YGZEG3RIVE1",
  "qrImageUrl": "https://scontent.whatsapp.net/v/qr-ejemplo.png"
}

DELETE/accounts/{id}/qr-codes/{code}

Borrar un código QR

Requiere el permiso whatsapp:manage. El QR impreso y su enlace dejan de funcionar.

ParámetroEnDescripción
idrutastring
coderutastring

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/accounts/ID/qr-codes/{code}" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "code": "4O4YGZEG3RIVE1",
  "deleted": true
}

POST/templates

Crear una plantilla

Requiere el permiso whatsapp:manage. La manda a revisión de Meta y responde la plantilla en PENDING, con components en el formato de Meta. El resultado llega con el evento template.status_changed (o GET /templates/{id}). Categorías MARKETING, UTILITY o AUTHENTICATION. Variables del cuerpo por posición ({{1}}, {{2}}… seguidas, bodyExamples como lista) o con nombre ({{nombre}}, bodyExamples como objeto); no se mezclan. Cabecera TEXT (60 caracteres, una variable con exampleText), LOCATION, o IMAGE, VIDEO o DOCUMENT con exampleUrl (JPG/PNG, MP4 o PDF por https; la cuenta necesita App ID). Hasta 10 botones: QUICK_REPLY (juntos), URL (máx. 2; puede terminar en {{1}} con urlExample), PHONE_NUMBER, COPY_CODE (example), FLOW (flowId, navigateScreen) y VOICE_CALL. limitedTimeOffer (MARKETING, con botón URL; con vencimiento también COPY_CODE), carousel (MARKETING, 2 a 10 tarjetas con IMAGE o VIDEO y los mismos botones) y authentication (solo AUTHENTICATION: Meta fija el texto; ONE_TAP y ZERO_TAP piden packageName y signatureHash). 409 si ya existe ese nombre en ese idioma.

ParámetroEnDescripción
Idempotency-Key?headerClave única por operación (p. ej. un UUID). Durante 24 h, repetir la solicitud con la misma clave y el mismo cuerpo devuelve la respuesta original (con el header Idempotent-Replayed: true) sin repetir la operación. Misma clave con otro cuerpo → 422 idempotency_conflict; mientras la primera sigue en proceso → 409 conflict. Los errores 401, 402, 403, 429 y 5xx no se guardan: puedes reintentar con la misma clave.
Campo del cuerpoTipoDescripción
accountIdstring
namestring
language?stringCódigo de Meta: es, es_MX, en_US…
category?MARKETING | UTILITY | AUTHENTICATION
componentsobjectbody es requerido salvo en AUTHENTICATION, que solo lleva authentication

Ejemplo

curl -X POST "https://app.colibly.com/api/v1/templates" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c3a-9d1b-2f6a0c7e5b11" \
  -d '{"accountId":"cmacc_wa_01","name":"confirmacion_pedido","language":"es_MX","category":"UTILITY","components":{"body":"Hola {{1}}, tu pedido {{2}} va en camino.","bodyExamples":["Ana","A-1043"],"buttons":[{"type":"URL","text":"Rastrear","url":"https://ejemplo.mx/envio/{{1}}","urlExample":"https://ejemplo.mx/envio/A-1043"}]}}'

Respuesta 201

{
  "id": "cmtpl_01",
  "accountId": "cmacc_wa_01",
  "name": "confirmacion_pedido",
  "language": "es_MX",
  "category": "UTILITY",
  "status": "PENDING",
  "statusReason": null,
  "params": {
    "bodyParamCount": 2,
    "header": null,
    "buttonParamRequired": false
  },
  "send": {
    "parameterFormat": "POSITIONAL",
    "bodyParams": 2,
    "header": null,
    "buttons": [
      {
        "index": 0,
        "type": "URL",
        "text": "Rastrear",
        "param": "urlParam",
        "required": true
      }
    ],
    "requiresCode": false,
    "offer": null,
    "carouselCards": null
  },
  "bodyText": "Hola {{1}}, tu pedido {{2}} va en camino.",
  "syncedAt": "2026-10-18T12:00:00.000Z"
}

PATCH/templates/{id}

Editar una plantilla

Requiere el permiso whatsapp:manage. Reemplaza sus componentes en Meta con la misma definición de POST /templates (sin accountId, name ni language) y vuelve a revisión (PENDING). Solo plantillas APPROVED, REJECTED o PAUSED (si no, 422). Una aprobada se edita 1 vez cada 24 h y 10 veces en 30 días, y no cambia de categoría.

ParámetroEnDescripción
idrutastring
Campo del cuerpoTipoDescripción
category?MARKETING | UTILITY | AUTHENTICATIONSolo si la plantilla no está aprobada
componentsobjectbody es requerido salvo en AUTHENTICATION, que solo lleva authentication

Ejemplo

curl -X PATCH "https://app.colibly.com/api/v1/templates/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"components":{"body":"Hola {{1}}, tu pedido {{2}} ya salió.","bodyExamples":["Ana","A-1043"]}}'

Respuesta 200

{
  "id": "cmtpl_01",
  "accountId": "cmacc_wa_01",
  "name": "confirmacion_pedido",
  "language": "es_MX",
  "category": "UTILITY",
  "status": "PENDING",
  "statusReason": null,
  "params": {
    "bodyParamCount": 2,
    "header": null,
    "buttonParamRequired": false
  },
  "send": {
    "parameterFormat": "POSITIONAL",
    "bodyParams": 2,
    "header": null,
    "buttons": [
      {
        "index": 0,
        "type": "URL",
        "text": "Rastrear",
        "param": "urlParam",
        "required": true
      }
    ],
    "requiresCode": false,
    "offer": null,
    "carouselCards": null
  },
  "bodyText": "Hola {{1}}, tu pedido {{2}} va en camino.",
  "syncedAt": "2026-10-18T12:00:00.000Z"
}

DELETE/templates/{id}

Borrar una plantilla

Requiere el permiso whatsapp:manage. La borra en Meta (solo ese idioma) y queda como DELETED en Colibly; las campañas que la usaron conservan su historial. Meta no deja volver a usar el nombre durante 30 días.

ParámetroEnDescripción
idrutastring

Ejemplo

curl -X DELETE "https://app.colibly.com/api/v1/templates/ID" \
  -H "Authorization: Bearer $COLIBLY_API_KEY"

Respuesta 200

{
  "id": "cmtpl_01",
  "deleted": true
}