Saltar al contenido principal
Cada cambio al contrato de la API pública aparece aquí: nuevos endpoints y campos el día que salen, y la rara corrección hecha antes de que un campo tenga uso real. Construye tu integración para que ignore los campos que no conoce, y revisa esta página cuando algo cambie.
​
Límite de capacidad
  • Nuevo 503 server_busy: cuando una clave tiene demasiadas solicitudes en curso a la vez, o la API está al máximo de capacidad, una solicitud devuelve 503 con Retry-After: 1. No se ejecutó y no cuenta contra tu límite de uso; reinténtala. Enviar hasta 100 destinatarios por envío de plantilla, en vez de una llamada por destinatario, lo evita. Consulta límites de uso.
​
Webhooks
  • conversation.assigned trae más datos: el nombre y email del compañero (assignee), cómo se asignó (strategy, assigned_by, self_assigned) y una URL a la conversación (url), para que una herramienta sin código publique una alerta útil sin llamar a la API. Consulta el catálogo de eventos.
​
Formularios de WhatsApp
​
Webhooks
Ciarem ahora puede llamar a tu servidor cuando algo cambia, así que ya no tienes que consultar una y otra vez. Empieza por la guía de webhooks.
  • Endpoints de webhook: registra hasta 10 URLs HTTPS por organización y elige qué eventos recibe cada una (/v1/webhook-endpoints: listar, crear, leer, actualizar, eliminar). También disponible para los administradores en el panel, en Configuración → Webhooks.
  • Diez tipos de evento: contact.created, contact.updated, contact.deleted, contact.merged, contact.funnel_stage.changed, contact.owner.changed, conversation.created, conversation.assigned, conversation.closed y messages.inbound. Los eventos de contacto llevan el contacto completo. Consulta el catálogo de eventos.
  • Solicitudes firmadas: cada solicitud lleva un encabezado Ciarem-Signature, un HMAC-SHA256 hecho con el secreto de firma whsec_ del endpoint. Consulta Verificar firmas.
  • Reintentos y un registro de entregas: una entrega fallida se reintenta durante un máximo de 3 días, y cada entrega de los últimos 30 días se puede leer con GET /v1/webhook-endpoints/{id}/deliveries y enviar de nuevo con POST /v1/webhook-deliveries/{id}/redeliver. Consulta Entregas y reintentos.
  • Eventos de prueba: POST /v1/webhook-endpoints/{id}/test envía un evento ahora mismo y devuelve lo que respondió tu servidor. GET /v1/webhook-event-samples devuelve el cuerpo de ejemplo de cada tipo de evento.
  • Incluido en los mismos planes que la API: Growth, Scale y la prueba gratuita.
​
Baja de marketing por WhatsApp
  • Los contactos ahora incluyen marketing_opt_out (booleano, solo lectura): true cuando el contacto se dio de baja del marketing por WhatsApp. No se puede cambiar desde la API. Ve Baja de marketing por WhatsApp.
  • POST /v1/templates/{id}/send: una plantilla de marketing no se envía a un destinatario cuyo marketing_opt_out es true. La solicitud se acepta igual y los demás destinatarios se envían; al destinatario dado de baja no se le envía ni se le cobra. Las plantillas de utilidad y autenticación no cambian. Lee marketing_opt_out en el contacto para dejar fuera a esos destinatarios desde el inicio.
​
La API llega al plan Growth
  • La API ahora está incluida en el plan Growth, no solo en Scale. Growth obtiene todos los endpoints con un presupuesto de 10 solicitudes/segundo; Scale sigue en 20 solicitudes/segundo y la prueba en 5 solicitudes/segundo. Las claves creadas durante una prueba que continuó en Growth vuelven a funcionar sin ningún cambio.
  • Cambio incompatible: scale_plan_required ahora es plan_upgrade_required. El detalle del 403 para un plan activo sin la API (Solo) cambió de nombre, porque Scale ya no es el único plan que la incluye. Si tu integración compara contra el texto anterior, actualízala. Consulta Autenticación.
​
Los filtros de fecha de contactos usan fechas absolutas
  • GET /v1/contacts: property_filter ya no acepta fechas relativas. Una condición sobre una propiedad DATE recibe una fecha YYYY-MM-DD, por ejemplo custom_birthday:gte:2026-09-01. Un valor preset: como preset:1w ahora devuelve 400 con invalid_property_filter. Nunca estuvieron documentadas: se resuelven en la zona horaria de quien mira el panel, algo que una integración no puede controlar. Calcula las fechas de tu lado.
  • tz ahora está documentado en GET /v1/contacts: la zona horaria IANA en la que se leen created_from / created_to. Por defecto usa la zona horaria de la organización y, si no hay, UTC.
​
Acceso en la prueba gratuita, límites por segundo y 403 que dicen qué hacer
  • La API está abierta durante la prueba gratuita. Una organización en prueba obtiene todos los endpoints, con un presupuesto menor, para construir y probar una integración antes de pagar.
  • Los límites de uso ahora son por segundo: 20 solicitudes/segundo en Scale, 5 solicitudes/segundo durante la prueba, compartidas entre las claves de la organización. Los encabezados X-RateLimit-* no cambian; Retry-After en un 429 ahora es siempre 1.
  • GET /v1/me gana trial (booleano), que es true mientras la organización está en su prueba gratuita. plan ahora reporta el código real del plan en vez de siempre "scale".
  • 403 más claros. scale_plan_required ahora significa solo que la organización está en un plan activo por debajo de Scale y tiene que subir de plan. Dos nuevos detalles cubren el resto: trial_expired (la prueba terminó sin método de pago) y subscription_required (cancelada, o suspendida por falta de pago). Consulta Autenticación.
​
Plantillas de WhatsApp, envíos y campañas
La API ya puede enviar.
  • Plantillas de WhatsApp: listar, leer, crear y eliminar (/v1/templates). Crear una plantilla también la envía a Meta para aprobación en la misma llamada, así que regresa como PENDING; consúltala hasta que Meta la pase a APPROVED o REJECTED.
  • GET /v1/templates/{id}/send-requirements: qué necesita una plantilla antes de poder enviarse. Incluye los tokens de variables, cuáles de ellos se resuelven solos desde el contacto, slots de catálogo, botones de URL dinámicos, superficies de medios, y el motivo cuando una plantilla no se puede enviar nunca. Léelo antes de tu primer envío en vez de descubrirlo a través de 422s.
  • POST /v1/templates/{id}/send: hasta 100 destinatarios en una llamada, cada uno identificado por contact_id o phone y con sus propios variables, url_suffixes, coupon_code, lto_expiration y medios. recipients acepta un solo objeto o un arreglo, así que enviar a una persona no necesita envoltura. Los encabezados de medios aceptan una URL pública (header_media_url / card_media_urls), que descargamos del lado del servidor. Devuelve 202 y la campaña que creó.
    • Un phone que no coincide con ningún contacto crea uno, así que un envío puede hacer crecer tu CRM.
    • Envía Idempotency-Key y reintentar es seguro: la misma clave devuelve la campaña original durante 24 horas en vez de enviar de nuevo.
    • La solicitud se rechaza completa (nada encolado, nada cobrado) si falta una variable, si una clave no la usa la plantilla, si una URL de medios no se puede descargar, o si el lote excede lo que queda del límite de mensajería de 24 horas de WhatsApp.
  • Campañas: GET /v1/broadcasts y GET /v1/broadcasts/{id} para el progreso (sent / failed / pending siempre suman requested), GET /v1/broadcasts/{id}/recipients para el resultado de cada destinatario, y POST /v1/broadcasts/{id}/cancel para abandonar el resto sin enviar. Los mensajes que WhatsApp ya aceptó no se pueden recuperar.
  • GET /v1/channels/whatsapp/phones: los números conectados desde los que puede salir un envío, para que channel_id sea descubrible. Opcional cuando tu cuenta de WhatsApp tiene exactamente un número; obligatorio cuando tiene más.
​
Lanzamiento de v1
La primera superficie pública de la API de Ciarem:
  • Contactos: CRUD completo (/v1/contacts).
  • Metadatos de CRM: propiedades y etapas del funnel, CRUD completo (/v1/properties, /v1/funnel-stages).
  • Conversaciones: historial de solo lectura (/v1/conversations), cada mensaje con un sender de contact, agent, ai o system.
  • /v1/me: identidad de la organización, plan, zona horaria e idioma.
  • Claves de API oak_ ligadas a la organización, 60 solicitudes/minuto por organización.