Broadcasts

Guia Rapida

Obtener tu organization_id y organization_address (ver Getting Started)
Obtener templates disponibles — GET .../whatsapp-management/templates
Crear el broadcast — POST .../broadcasts
Enviar el broadcast — POST .../broadcasts/{id}/send
Monitorear el progreso — GET .../broadcasts/{id}

Todos los endpoints bajo https://api.mirlo.com/v2/messages/organizations/{organization_id}

Crear Broadcast

Template SIN Variables

curl -X POST "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campaña Enero 2026",
    "organization_address": "100000000000001",
    "meta_template_id": "111222333444555",
    "recipients": [
      {"phone_number": "+521234567890"},
      {"phone_number": "+521234567891"}
    ]
  }'

Template CON Variables (ejemplo cobranza)

Cada destinatario recibe un mensaje personalizado con sus propias variables:

curl -X POST "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cobranza Enero 2026",
    "organization_address": "100000000000001",
    "meta_template_id": "555666777888999",
    "recipients": [
      {
        "phone_number": "+521234567890",
        "components": [
          {
            "type": "body",
            "parameters": [
              {"type": "text", "parameter_name": "nombre_cliente", "text": "Juan Perez"},
              {"type": "text", "parameter_name": "mes", "text": "Enero"},
              {"type": "text", "parameter_name": "monto", "text": "$599.00"},
              {"type": "text", "parameter_name": "link", "text": "https://pay.mirlo.com/abc123"}
            ]
          }
        ]
      },
      {
        "phone_number": "+521234567891",
        "components": [
          {
            "type": "body",
            "parameters": [
              {"type": "text", "parameter_name": "nombre_cliente", "text": "Maria Garcia"},
              {"type": "text", "parameter_name": "mes", "text": "Enero"},
              {"type": "text", "parameter_name": "monto", "text": "$799.00"},
              {"type": "text", "parameter_name": "link", "text": "https://pay.mirlo.com/def456"}
            ]
          }
        ]
      }
    ]
  }'

Template con Variables en HEADER y BODY

Si tu template tiene variables tanto en el header como en el body, incluye ambos componentes por recipient:

{
  "phone_number": "+521234567890",
  "components": [
    {
      "type": "header",
      "parameters": [
        {"type": "text", "parameter_name": "nombre_cliente", "text": "Juan Perez"}
      ]
    },
    {
      "type": "body",
      "parameters": [
        {"type": "text", "parameter_name": "producto", "text": "iPhone 15"},
        {"type": "text", "parameter_name": "fecha_entrega", "text": "25 de Enero"}
      ]
    }
  ]
}

Response

{
  "id": "12345678-abcd-1234-efgh-123456789abc",
  "organization_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "organization_address": "100000000000001",
  "name": "Cobranza Enero 2026",
  "status": "draft",
  "recipients_added": 3,
  "recipients_duplicates": 0
}

El broadcast se crea en estado draft. Guarda el id para enviarlo en el siguiente paso.

Enviar Broadcast

curl -X POST "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts/12345678-abcd-1234-efgh-123456789abc/send" \
  -H "X-API-Key: sk_live_tu_api_key"

Response:

{
  "broadcast": {
    "id": "12345678-abcd-1234-efgh-123456789abc",
    "status": "sending",
    "started_at": "2026-01-22T18:46:17.030Z",
    "phone_number": "+52 1 55 1234 5678"
  },
  "template": {
    "name": "bienvenida_cliente",
    "status": "APPROVED",
    "category": "MARKETING"
  }
}

Monitorear Progreso

Estado del Broadcast

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts/12345678-abcd-1234-efgh-123456789abc" \
  -H "X-API-Key: sk_live_tu_api_key"

Estado	Descripcion
`draft`	Creado, esperando envio
`pending`	Listo para enviar
`sending`	Enviando mensajes
`completed`	Todos los mensajes procesados
`failed`	Error en el envio

Estado de los Recipients

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts/12345678-abcd-1234-efgh-123456789abc/recipients" \
  -H "X-API-Key: sk_live_tu_api_key"

Estado	Descripcion
`pending`	Mensaje en cola, aun no enviado
`sent`	Enviado a WhatsApp
`delivered`	Entregado al dispositivo
`read`	Leido por el destinatario
`failed`	Error en el envio
`replied`	El destinatario respondio

Paginacion

GET .../broadcasts y GET .../broadcasts/{id}/recipients son paginados.

Parametro	Tipo	Descripcion
`skip`	number	Registros a saltar. Default: 0
`take`	number	Registros a retornar. Default: 100

Los parametros se llaman skip y take. Enviar limit u offset responde 400 "property limit should not exist".

curl -X GET "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts?skip=100&take=50" \
  -H "X-API-Key: sk_live_tu_api_key"

Response:

{
  "data": [ ... ],
  "total": 347,
  "skip": 100,
  "take": 50
}

total es la cantidad de registros que cumplen el filtro, no los devueltos en esta pagina: con el podes saber si quedan mas por recorrer.

Filtros del listado

Parametro	Tipo	Descripcion
`status`	string	`draft`, `pending`, `sending`, `completed` o `failed`
`created_by`	string	Member ID del creador (ver `.../broadcasts/creators`)
`include_metrics`	boolean	Agrega metricas por broadcast (entregados, respuestas, avance)

Agregar Mas Recipients

Si necesitas agregar mas destinatarios a un broadcast en estado draft:

curl -X POST "https://api.mirlo.com/v2/messages/organizations/{organization_id}/broadcasts/{id}/recipients" \
  -H "X-API-Key: sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": [
      {
        "phone_number": "+521234567893",
        "components": [
          {
            "type": "body",
            "parameters": [
              {"type": "text", "parameter_name": "nombre_cliente", "text": "Carlos Lopez"}
            ]
          }
        ]
      }
    ]
  }'

Maximo 1000 recipients por request. Puedes hacer multiples requests para agregar mas.

Asignacion a un Miembro

assigned_member_id asigna las conversaciones que genere el broadcast a un miembro del equipo.

Solo acepta miembros humanos. Pasar el ID de un agente de IA responde 400: las respuestas a una campana entran a la bandeja de un humano, no al agente.

Referencia de Endpoints

Todos bajo https://api.mirlo.com/v2/messages/organizations/{organization_id}

Metodo	Endpoint	Descripcion
POST	`.../broadcasts`	Crear broadcast
GET	`.../broadcasts`	Listar broadcasts
GET	`.../broadcasts/{id}`	Obtener broadcast
GET	`.../broadcasts/{id}/full`	Broadcast con recipients y template
PATCH	`.../broadcasts/{id}`	Actualizar (solo draft)
DELETE	`.../broadcasts/{id}`	Eliminar (solo draft)
POST	`.../broadcasts/{id}/recipients`	Agregar recipients
GET	`.../broadcasts/{id}/recipients`	Listar recipients
POST	`.../broadcasts/{id}/send`	Enviar broadcast

En esta pagina