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
| Permiso | Qué permite |
|---|---|
contacts:read | Leer contactos, etiquetas y campos |
contacts:write | Crear y editar contactos, etapas y etiquetas |
conversations:read | Leer conversaciones y mensajes |
conversations:write | Cambiar el estado y la asignación de conversaciones |
messages:send | Enviar mensajes (texto, plantillas y botones) |
webhooks:manage | Administrar webhooks salientes |
automations:run | Iniciar automatizaciones manuales |
whatsapp:manage | Administrar 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ímite | Valor |
|---|---|
| Por key | 120 solicitudes por minuto |
| Por cuenta (todas sus keys juntas) | 600 solicitudes por minuto |
| Por IP (con o sin key) | 3000 solicitudes por minuto |
POST /messages | 60 envíos por minuto y 10,000 por día (UTC) por cuenta |
GET /conversations | 60 solicitudes por minuto por key |
| Tamaño del cuerpo | 1024 KB como máximo (si no, 413 payload_too_large) |
Toda respuesta autenticada informa el límite más ajustado en ese momento:
| Header | Significado |
|---|---|
X-RateLimit-Limit | Solicitudes permitidas en la ventana del límite informado. |
X-RateLimit-Remaining | Las que te quedan en la ventana actual. |
X-RateLimit-Reset | Segundos hasta que se libera un lugar. |
X-RateLimit-Scope | Qué límite se informa: key, organization, ip, endpoint o daily. |
Retry-After | Solo 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.
| Status | code | Cuándo |
|---|---|---|
| 400 | invalid_request | Cuerpo o parámetros inválidos; `message` dice cuál y `details` trae cada campo (`path`, `message`). |
| 401 | unauthorized | Falta la API key, es inválida, está revocada o vencida, o su dueño ya no es admin. |
| 402 | plan_limit | El 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). |
| 402 | read_only | Cuenta en solo lectura (prueba vencida o pago pendiente): solo GET. |
| 403 | forbidden | La key no tiene el permiso que pide el endpoint. |
| 404 | not_found | No existe o no está al alcance de la key. |
| 405 | method_not_allowed | La ruta existe pero no acepta ese método; el header `Allow` dice cuáles sí. |
| 409 | conflict | Choca con el estado actual (p. ej. automatización ya en curso, o la misma Idempotency-Key sigue en proceso). |
| 409 | limit_reached | Tope por cuenta: 10 webhooks. |
| 422 | window_closed | WhatsApp: fuera de la ventana de 24 h solo se puede enviar una plantilla aprobada. |
| 422 | idempotency_conflict | La Idempotency-Key ya se usó con otro cuerpo o en otro endpoint. |
| 422 | required_fields | No se puede resolver la conversación: faltan atributos obligatorios (ver `details`). |
| 413 | payload_too_large | El cuerpo supera 1024 KB. |
| 429 | rate_limited | Demasiadas solicitudes (por key, organización, IP o endpoint; ver `X-RateLimit-Scope`); espera los segundos de `Retry-After`. |
| 429 | daily_limit_reached | Cupo diario de 10000 envíos por API por organización (día UTC); `Retry-After` indica cuándo se renueva. |
| 500 | internal_error | Error nuestro. Reintenta con la misma Idempotency-Key. |
| 502 | upstream_error | WhatsApp/Meta u otro canal rechazó o no respondió. |
| 503 | service_unavailable | Servicio 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 conPOST /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 eventowebhook.testfirmado, para validar tu receptor sin esperar un evento real. Su resultado queda en el historial de entregas.
Cada entrega
| Header | Valor |
|---|---|
X-Colibly-Signature | t=<unix>,v1=<hex>: HMAC-SHA256 del texto {t}.{cuerpo} con tu secreto. |
X-Colibly-Event | Tipo de evento, p. ej. contact.created. |
X-Colibly-Delivery | Id de la entrega; es el mismo en cada reintento. |
X-Colibly-Event-Id | Id del evento (el mismo que id en el cuerpo): igual en todos tus endpoints y reintentos, útil para descartar duplicados. |
X-Colibly-Attempt | Número de intento (1 = primera entrega). |
User-Agent | Colibly-Webhooks/1.0 |
Content-Type | application/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 "", 200Reintentos, 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
idpara descartar duplicados yoccurredAtpara 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ámetro | En | Descripción |
|---|---|---|
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
accountId? | query | string |
leadStatus? | query | NEW | CONTACTED | QUALIFIED | CUSTOMER | LOST |
tagId? | query | string |
q? | query | Nombre o teléfono |
updatedSince? | query | Para 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ámetro | En | Descripción |
|---|---|---|
Idempotency-Key? | header | Clave ú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 cuerpo | Tipo | Descripción |
|---|---|---|
accountId | string | Cuenta de WhatsApp |
phone | string | Con 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? | object | Por 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
name? | string | |
realName? | string | null | |
leadStatus? | NEW | CONTACTED | QUALIFIED | CUSTOMER | LOST | |
customFields? | object | null o "" borra el valor |
dealValueCents? | integer | null | Valor del trato en centavos de MXN; null lo borra |
expectedCloseAt? | string | null | Fecha 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"
}Conversaciones
GET/conversations
Listar conversaciones
Requiere el permiso conversations:read. Todos los canales, por último mensaje.
| Parámetro | En | Descripción |
|---|---|---|
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
accountId? | query | string |
channel? | query | WHATSAPP | TELEGRAM | MESSENGER | INSTAGRAM | WEBCHAT |
status? | query | OPEN | PENDING | RESOLVED |
assignedToId? | query | string |
teamId? | query | Solo las de ese equipo (GET /teams) |
contactId? | query | string |
updatedSince? | query | Solo 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
status? | OPEN | PENDING | RESOLVED | |
assignedToId? | string | null | Id de GET /users; null quita la asignación |
teamId? | string | null | Id 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
typing? | boolean | Mostrar "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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
since? | query | Fecha 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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 cuerpo | Tipo | Descripción |
|---|---|---|
type | image | document | audio | video | sticker | |
url | string | |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
Idempotency-Key? | header | Clave ú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 cuerpo | Tipo | Descripción |
|---|---|---|
emoji | string | Un 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
since | query | string |
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
accountId? | query | string |
direction? | query | INBOUND | 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ámetro | En | Descripción |
|---|---|---|
Idempotency-Key? | header | Clave ú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 cuerpo | Tipo | Descripción |
|---|---|---|
conversationId? | string | |
contactId? | string | |
accountId? | string | Cuenta de WhatsApp que envía (con `to`) |
to? | string | Telé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) |
type | text | buttons | list | template | image | document | audio | video | sticker | location | location_request | cta_url | product | product_list | catalog | flow | contacts | |
text? | string | Requerido para text, buttons, list, cta_url y location_request |
buttons? | object[] | |
template? | object | Lo que pide cada plantilla está en `send` de GET /templates. |
media? | object | Requerido 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? | string | Texto junto al archivo (image, video, document). No en audio, ni en Messenger/Instagram |
list? | object | type list |
cta? | object | type cta_url (WhatsApp) |
location? | object | type location (WhatsApp) |
replyTo? | string | Id de un mensaje de la misma conversación para citarlo (WhatsApp) |
product? | object | type product (WhatsApp). `text` es opcional |
productList? | object | type product_list (WhatsApp), con `text`. Hasta 10 secciones y 30 productos |
catalog? | object | type catalog (WhatsApp), con `text` |
flow? | object | type flow (WhatsApp), con `text` |
footer? | string | Pie 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ámetro | En | Descripción |
|---|---|---|
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
accountId? | query | string |
contactId? | query | string |
status? | query | RINGING | CONNECTING | ACTIVE | ENDED | MISSED | REJECTED | FAILED |
direction? | query | inbound | outbound |
since? | query | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
Idempotency-Key? | header | Clave ú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 cuerpo | Tipo | Descripción |
|---|---|---|
contactId | string | |
vars? | object | Disponibles 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ámetro | En | Descripción |
|---|---|---|
accountId? | query | string |
status? | query | Estado 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
since? | query | string |
until? | query | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
accountId? | query | string |
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/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ámetro | En | Descripción |
|---|---|---|
accountId? | query | string |
runnable? | query | Solo 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 cuerpo | Tipo | Descripción |
|---|---|---|
name | string | |
url | string | https:// 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
name? | string | |
url? | string | |
events? | string[] | |
accountIds? | string[] | |
channelAccountIds? | string[] | |
active? | boolean | |
takeOwnership? | boolean | Pasa 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripció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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
status? | query | pending | sent | failed |
eventType? | query | string |
since? | query | Solo 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
deliveryId | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
deliveryId | ruta | string |
Idempotency-Key? | header | Clave ú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"
}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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
about? | string | |
address? | string | |
description? | string | |
email? | string | "" lo borra |
websites? | string[] | |
vertical? | string | Categoría de Meta en mayúsculas |
profilePictureUrl? | string | JPG 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
phones | string[] | 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
phone | ruta | Con 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
since? | query | string |
until? | query | string |
granularity? | query | DAILY | 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripció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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
name | string | |
categories | SIGN_UP | SIGN_IN | APPOINTMENT_BOOKING | LEAD_GENERATION | CONTACT_US | CUSTOMER_SUPPORT | SURVEY | OTHER[] | |
flowJson? | object | JSON del Flow (version, screens…) |
cloneFlowId? | string | |
endpointUri? | string | null | Tu endpoint (https), si cifras tú |
useColiblyEndpoint? | boolean | Usar 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
flowId | ruta | Id 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
flowId | ruta | Id del Flow en Meta |
| Campo del cuerpo | Tipo | Descripció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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
flowId | ruta | Id 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
flowId | ruta | Id 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
flowId | ruta | Id 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
rotateSecret? | query | boolean |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
url | string | 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
pin | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripció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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
confirm | boolean |
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
}GET/onboarding-links
Enlaces de conexión
Requiere el permiso whatsapp:manage. Los enlaces de la organización, más recientes primero.
| Parámetro | En | Descripción |
|---|---|---|
limit? | query | Entero de 1 a 100; uno mayor se recorta a 100, uno no numérico o menor que 1 responde 400 |
cursor? | query | nextCursor de la página anterior |
Ejemplo
curl "https://app.colibly.com/api/v1/onboarding-links" \
-H "Authorization: Bearer $COLIBLY_API_KEY"Respuesta 200
{
"data": [
{
"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"
}
],
"nextCursor": null
}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ámetro | En | Descripción |
|---|---|---|
Idempotency-Key? | header | Clave ú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 cuerpo | Tipo | Descripción |
|---|---|---|
name? | string | Nombre de la cuenta que se creará (si no, el de Meta) |
reference? | string | Tu id del cliente; vuelve en el evento y en la redirección |
redirectUrl? | string | https; 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/onboarding-links/{id}
Obtener un enlace de conexión
Requiere el permiso whatsapp:manage. PENDING, COMPLETED (con accountId), CANCELED o EXPIRED; lastError si el cliente lo intentó y falló.
| Parámetro | En | Descripción |
|---|---|---|
id | ruta | string |
Ejemplo
curl "https://app.colibly.com/api/v1/onboarding-links/ID" \
-H "Authorization: Bearer $COLIBLY_API_KEY"Respuesta 200
{
"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"
}DELETE/onboarding-links/{id}
Cancelar un enlace de conexión
Requiere el permiso whatsapp:manage. Deja de funcionar al instante. 409 si ya se usó o ya estaba cancelado.
| Parámetro | En | Descripción |
|---|---|---|
id | ruta | string |
Ejemplo
curl -X DELETE "https://app.colibly.com/api/v1/onboarding-links/ID" \
-H "Authorization: Bearer $COLIBLY_API_KEY"Respuesta 200
{
"id": "cmobl_01",
"status": "CANCELED",
"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"
}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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripció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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
prefilledMessage | string | |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
code | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
prefilledMessage | string |
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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
code | ruta | string |
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ámetro | En | Descripción |
|---|---|---|
Idempotency-Key? | header | Clave ú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 cuerpo | Tipo | Descripción |
|---|---|---|
accountId | string | |
name | string | |
language? | string | Código de Meta: es, es_MX, en_US… |
category? | MARKETING | UTILITY | AUTHENTICATION | |
components | object | body 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
| Campo del cuerpo | Tipo | Descripción |
|---|---|---|
category? | MARKETING | UTILITY | AUTHENTICATION | Solo si la plantilla no está aprobada |
components | object | body 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ámetro | En | Descripción |
|---|---|---|
id | ruta | string |
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
}