API de Difusiones #

Una difusión es un envío saliente: una audiencia, un mensaje de apertura, un canal y un horario. Opcionalmente, también nombra al Agente de IA que gestiona las respuestas que recibe. La API de Difusiones le permite crear, fijar precios, lanzar y supervisar esos envíos desde su propio código en lugar de desde el panel de control. Para obtener información sobre el producto en sí, consulte la guía de Difusiones.

• URL base — https://api.youraiconnector.com/v1
• Autenticación — tu clave de API (consulta Autenticación)
• Errores y paginación — consulta Errores y paginación

Todos los ejemplos a continuación muestran la forma de consulta ?apiKey= en cURL y el encabezado X-API-Key en JavaScript y Python; cualquiera de los dos funciona en todos los endpoints.

En el explorador de API. Cada endpoint en esta página se encuentra en la especificación OpenAPI publicada, por lo que puede explorar sus campos exactos y ejecutar solicitudes en vivo en el explorador de API.

Cómo se compone un envío #

Enviar una difusión requiere cuatro llamadas, no una:

1. Crear la difusión con su audiencia, canal y horario; comienza como un Draft.
2. Establecer el mensaje de apertura. En WhatsApp Business, eso significa enviar una plantilla para su aprobación (o elegir una que ya haya sido aprobada). En cualquier otro canal, es texto sin formato.
3. Estimar el costo si desea verificar el precio antes de gastar nada (opcional).
4. Lanzarla. El lanzamiento realiza una verificación completa (audiencia, mensaje, aprobación de plantilla, remitente conectado) e inicia el envío o le indica exactamente qué falta.

No se envía nada hasta que usted llama al lanzamiento.

El objeto de difusión #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Las marcas de tiempo se devuelven como milisegundos de época (execution_date, created_at, last_modified_at, …), y cualquier referencia de contacto se devuelve como una cadena de ruta como contacts/uid_whatsapp_15551234567.

Campos que usted establece #

Cualquier cosa que envíe como user_id, id, status o source_campaign_id se ignora al crear y se descarta al actualizar; el estado solo cambia a través de los endpoints de lanzamiento, pausa y reanudación a continuación.

Campos que mantiene la plataforma #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, los contadores de lotes y contacts (los contactos individuales adjuntos desde el panel de control, leídos como cadenas de ruta). Léalos, no los escriba.

Estados #

Crear una difusión #

POST /broadcasts — crea una Draft.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Respuesta (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Listar difusiones #

GET /broadcasts — todas las difusiones de la cuenta, de la más reciente a la más antigua.

Parámetros de consulta

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Respuesta (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Obtener una difusión #

GET /broadcasts/{broadcastId} — devuelve { "success": true, "broadcast": { ... } }. Úselo para consultar un envío en curso: total_contacts_sent, unique_contacts_replied, overall_reply_rate y credits_used se actualizan a medida que avanza. |

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Una difusión que no existe en su cuenta devuelve 404.

Actualizar una difusión #

PUT /broadcasts/{broadcastId} — envíe solo los campos que desea cambiar. También puede dirigirse a una sola clave dentro de un objeto anidado con una ruta de puntos, p. ej., "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Un cuerpo vacío devuelve 400. Hay dos reglas que vale la pena conocer:

• opener_media es todo o nada. Envíe el objeto completo o null para eliminar el archivo adjunto. Una ruta de puntos hacia él (opener_media.name) será rechazada con 400, porque un archivo adjunto parcialmente actualizado describiría un archivo que no existe.
• El estado no es editable. Utilice lanzar, pausar y reanudar.

El mensaje de apertura #

Cada difusión lleva su mensaje de apertura en whats_app_template. Lo que esto significa depende del canal:

• WhatsApp Business — debe ser una plantilla aprobada por WhatsApp. Utilice uno de los dos endpoints a continuación.
• Cualquier otro canal (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — el body del mismo campo es simplemente el texto que se envía. Enviarlo a través del endpoint a continuación lo almacena y lo marca como listo sin involucrar a WhatsApp en absoluto.

Enviar una plantilla para su aprobación #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Respuesta (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status es lo que dice WhatsApp: pending mientras está siendo revisado, approved cuando es utilizable, rejected si fue rechazado. En un canal que no es de WhatsApp, vuelve directamente como approved con template_sid: null; no hay nada que revisar.

Cosas que le detendrán:

• Enviar mientras una plantilla anterior sigue bajo revisión devuelve 400. Espere primero a la decisión.
• Editar una plantilla que ya está aprobada mantiene la aprobada activa hasta que la nueva regrese, por lo que una difusión en curso nunca pierde su apertura.
• En un número de WhatsApp conectado directamente a través de Meta, no se puede enviar una difusión con una imagen o vídeo adjunto (400); los archivos adjuntos son compatibles en la línea gestionada de WhatsApp Business y en WhatsApp Web.

Usar una plantilla que ya tenía aprobada #

POST /broadcasts/{broadcastId}/template/select — copia una plantilla ya aprobada de su biblioteca de plantillas a la difusión, por lo que no hay nada que esperar.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Respuesta (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

La aprobación se verifica por nuestra parte desde el registro de la biblioteca; usted solo envía el id. Recibirá un 400 si la difusión no es un borrador de WhatsApp, si la plantilla no está aprobada, si es una plantilla de seguimiento en lugar de una de apertura, o si la difusión tiene un archivo adjunto (las plantillas de la biblioteca son solo de texto). Un id de plantilla que no esté en su cuenta devuelve 404.

Estimar el coste #

POST /broadcasts/{broadcastId}/estimate-cost — calcula el precio del envío antes de comprometerse con él. Disponible en difusiones whatsapp y sms; cualquier otro canal devuelve 400. La difusión necesita un list_id, ya que la estimación cuenta la audiencia.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

Respuesta de WhatsApp (200) — créditos, desglosados por país de destino:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

Respuesta por SMS (200) — Dólares estadounidenses, basados en los precios en tiempo real de Twilio para su propia cuenta de Twilio:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Lea billing_mode antes de mostrar un número. Le indica quién recibe la facturación:

Los SMS sin credenciales de Twilio conectadas siguen devolviendo los recuentos de segmentos, con estimatedCostUsd: 0 — no hay precios que consultar.

Iniciar una difusión #

POST /broadcasts/{broadcastId}/launch

El inicio comprueba todo primero y solo entonces hace avanzar la difusión. No existe el inicio parcial: o comienza, o nada cambia y recibe un error explicando el motivo.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Respuesta (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status es donde aterrizó la difusión:

• Scheduled — execution_date está en el futuro.
• Sending — comenzó ahora.
• Pending Approval — la plantilla de WhatsApp todavía está bajo revisión. Se enviará automáticamente tan pronto como se apruebe la plantilla; no vuelva a llamar al inicio.

Solo se puede iniciar una difusión Draft (o una Pending Approval cuya plantilla haya sido aprobada desde entonces); cualquier otra cosa devuelve 400.

Por qué se rechaza un inicio #

Cada uno de estos se devuelve como 400 con un mensaje error en lenguaje sencillo:

Pausar y reanudar #

POST /broadcasts/{broadcastId}/pause detiene una difusión Sending o Scheduled y elimina todo lo que esté en cola.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Pausar una transmisión Pending Approval la devuelve a Draft en su lugar; aún no se había programado nada, por lo que no hay nada que reanudar. Cualquier otro estado devuelve 400.

POST /broadcasts/{broadcastId}/resume reinicia una transmisión Paused:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Respuesta (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Se reanuda en Sending, o vuelve a Scheduled si su execution_date sigue estando en el futuro. Solo se puede reanudar una transmisión Paused.

Seguir enviando después de una pausa por baja interacción #

POST /broadcasts/{broadcastId}/override-engagement-guard

Mientras una transmisión se envía por lotes, medimos cuántas personas respondieron a cada lote antes de iniciar el siguiente. Si casi nadie responde, la transmisión se pausa automáticamente: un envío que sigue insistiendo en el silencio es la forma más rápida de que un número sea filtrado o bloqueado. Es el botón Continuar de todos modos en el panel de control.

Debido a que la tasa de respuesta que causó la pausa no puede cambiar mientras la transmisión está detenida, un resume simple volvería a ser pausado en la siguiente comprobación. Este endpoint es la decisión de continuar de todos modos: registra la anulación en esa transmisión y levanta la pausa en la misma llamada si la transmisión se pausó por baja interacción.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Respuesta (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — la transmisión se pausó por baja interacción y ahora se está ejecutando de nuevo; status es donde se reanudó.
• resumed: false — no se levantó nada, la anulación simplemente se registra para futuras comprobaciones. Eso es lo que obtienes si la transmisión nunca se pausó o se pausó por una razón diferente (la pausaste manualmente, se alcanzó un límite de envío o demasiados envíos dieron error). Esas pausas no se levantan aquí; reanúdala tú mismo una vez que hayas solucionado la causa.

La anulación se aplica solo a esta transmisión. No es una configuración de la cuenta y es seguro llamarla dos veces.

Duplicar una transmisión #

POST /broadcasts/{broadcastId}/duplicate — copia la audiencia, el mensaje y la configuración en una nueva Draft. Todo lo relacionado con la ejecución anterior (contadores, lotes, programación, estadísticas de respuesta) comienza desde cero.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Respuesta (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Una copia nunca hereda una aprobación de WhatsApp activa: en una copia de WhatsApp, la plantilla llega necesitando tu confirmación, y en una copia a otro canal, se elimina y el texto se convierte en el mensaje de apertura simple. Copiar a SMS también elimina cualquier archivo adjunto, ya que los SMS no pueden enviarlos.

Eliminar una transmisión #

DELETE /broadcasts/{broadcastId}

curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Se rechaza una difusión Sending o Scheduled con 400: póngala en pausa primero.

Difusiones que reflejan una campaña clásica #

Las campañas clásicas que envían mensajes también aparecen en Difusiones, y la API las devuelve junto con las difusiones nativas (llevan un source_campaign_id). Se comportan de forma ligeramente distinta, ya que la campaña sigue estando al mando:

• Editar la audiencia, el mensaje o la programación funciona y se aplica a la campaña.
• El canal, el agente de respuesta, el archivo adjunto y todos los contadores de ejecución son de solo lectura aquí: 400 si intenta cambiarlos. Cámbielos en la campaña.
• Iniciar devuelve 400 indicándole el editor de la campaña.
• Pausar y reanudar funcionan y actúan sobre la campaña.
• Eliminar devuelve 400: elimine la campaña en su lugar, y su entrada en Difusiones desaparecerá con ella.
• Duplicar genera una difusión nativa independiente, que es la forma admitida de trasladar una campaña probada.

Errores #

Las solicitudes fallidas devuelven {"success": false, "error": "<message>"} con estos estados:

Próximos pasos #

• Guía de difusiones: el producto detrás de estos endpoints, incluyendo el ritmo y el comportamiento de seguridad
• API de contactos: cree la lista a la que se envía una difusión
• API de plantillas: gestione las plantillas de WhatsApp aprobadas que puede seleccionar
• API de webhooks: suscríbase a Broadcast Started y Broadcast Completed en lugar de realizar sondeos