Envío masivo de plantillas en WhatsApp

POST /v1/messages/send-bulk-template envía una plantilla aprobada de WhatsApp a una lista de contactos de una sola vez. Por ser plantillas, estos envíos valen fuera de la ventana de 24 horas: esta es la forma de iniciar una conversación con quien no ha hablado con usted recientemente. Scope: messages:create.

La plantilla debe estar aprobada en Meta de antemano. Esta llamada dispara una plantilla existente; no crea ni envía plantillas para aprobación.

Campos de la solicitud

Campo	Tipo	Obligatorio	Descripción
`inboxId`	string	Sí	Inbox (conexión de WhatsApp) que envía los mensajes.
`templateName`	string	Sí	Nombre de la plantilla como está registrada en WhatsApp Business.
`languageCode`	string	No	Formato `pt_BR`, `en_US` o solo `en`. Por defecto: `pt_BR`.
`components`	array	No	Parámetros dinámicos de la plantilla (vea abajo).
`contacts`	array	Condicional	Lista de `{ name, phone }`. Obligatorio si no envía un archivo.
`file`	archivo	Condicional	CSV o XLSX con las columnas `name` y `phone`. Obligatorio si no envía `contacts`.
`who_will_answer`	string	No	`AGENT`, `HUMAN` o `UNASSIGNED`. Vea Quién atiende después del envío.
`agentToActivate`	string	No	ID del agente de IA que responderá. Use junto con `who_will_answer: "AGENT"`.
`owner_user_id`	string	No	ID del usuario propietario de la conversación. Acepta `null`.
`attendant_user_id`	string	No	ID del usuario que atiende. Acepta `null`. Vale con `who_will_answer: "HUMAN"`.
`keep_existing_assignment`	boolean	No	`true` preserva la asignación actual e ignora los campos de arriba. Por defecto `false`.
`send_to_active_conversations`	boolean	No	`true` envía incluso a un contacto en conversación activa. Por defecto `false`.

phone necesita el código del país, sin símbolos: 5511999999999. name no puede estar vacío.

Enviar a una lista de contactos

cURL

curl -X POST https://api.nuvia.ai/v1/messages/send-bulk-template \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inboxId": "ID_DEL_INBOX",
    "templateName": "boas_vindas",
    "languageCode": "pt_BR",
    "components": [
      { "type": "body", "parameters": [{ "type": "text", "text": "Juan" }] }
    ],
    "contacts": [
      { "name": "Juan Silva", "phone": "5511999999999" },
      { "name": "María Santos", "phone": "5511888888888" }
    ]
  }'

Para listas grandes, envíe un archivo en lugar del array: multipart/form-data con el CSV o XLSX en el campo file y los demás campos en el formulario. El archivo necesita las columnas name y phone:

name,phone
Juan Silva,5511999999999
María Santos,5511888888888

Combinar archivo con components de parámetros dinámicos es un caso que vale la pena probar con pocos contactos antes de usarlo en producción. Si los parámetros no se aplican como usted espera, contacte al soporte.

Parámetros de la plantilla

Una plantilla aprobada tiene marcadores ({{1}}, {{2}}) y bloques: encabezado, cuerpo y botones. Esto se completa en components, y el número y el tipo de parámetros deben coincidir exactamente con la plantilla aprobada, de lo contrario Meta rechaza el envío.

Bloque (`type`)	Qué acepta en `parameters`
`header`	`text`, `image`, `video`, `document`
`body`	`text`, `currency`, `date_time`
`button`	`text` (botón de URL dinámica), `payload` (respuesta rápida)

Tipos de parámetro:

`type`	Campos	Ejemplo
`text`	`text`	`{ "type": "text", "text": "Juan" }`
`image`	`image.link`	`{ "type": "image", "image": { "link": "https://..." } }`
`video`	`video.link`	`{ "type": "video", "video": { "link": "https://..." } }`
`document`	`document.link`, `document.filename`	`{ "type": "document", "document": { "link": "https://...", "filename": "factura.pdf" } }`
`currency`	`currencyCode`, `currencyAmount`	`{ "type": "currency", "currencyCode": "BRL", "currencyAmount": 150.5 }`
`date_time`	`dateTime` (ISO 8601)	`{ "type": "date_time", "dateTime": "2026-01-31T23:59:59Z" }`
`payload`	`payload`	`{ "type": "payload", "payload": "producto_1" }`

Imagen, video y documento entran en el encabezado por URL pública HTTPS. No necesita subir ningún archivo ni preparar nada antes. Basta con que la URL sea accesible por Meta.

Ejemplos por tipo de plantilla

Encabezado con imagen

Plantilla: encabezado de imagen + ¡Hola {{1}}! Descubre nuestra promoción de {{2}}.

"components": [
  {
    "type": "header",
    "parameters": [
      { "type": "image", "image": { "link": "https://example.com/promo.jpg" } }
    ]
  },
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "Juan" },
      { "type": "text", "text": "Black Friday" }
    ]
  }
]

Botón con URL dinámica

Plantilla: Su pedido #{{1}} ha sido confirmado. + botón que apunta a .../track/{{1}}.El index del botón es una string y comienza en "0":

"components": [
  { "type": "body", "parameters": [{ "type": "text", "text": "12345" }] },
  {
    "type": "button",
    "sub_type": "url",
    "index": "0",
    "parameters": [{ "type": "text", "text": "12345" }]
  }
]

Documento en el encabezado

Plantilla: encabezado de documento + Hola {{1}}, aquí está su factura.

"components": [
  {
    "type": "header",
    "parameters": [
      {
        "type": "document",
        "document": {
          "link": "https://example.com/factura.pdf",
          "filename": "factura_enero.pdf"
        }
      }
    ]
  },
  { "type": "body", "parameters": [{ "type": "text", "text": "Juan Silva" }] }
]

Importe monetario y fecha

Plantilla: Su factura de {{1}} por un valor de {{2}} vence el {{3}}.

"components": [
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "Enero/2026" },
      { "type": "currency", "currencyCode": "BRL", "currencyAmount": 150.5 },
      { "type": "date_time", "dateTime": "2026-01-31T23:59:59Z" }
    ]
  }
]

El formato final (R$ 150,50, 31/01/2026) lo aplica WhatsApp, según el idioma del dispositivo de quien recibe el mensaje.

Las plantillas de carrusel no se aceptan en este endpoint. Use el envío individual de plantilla.

Quién atiende después del envío

La plantilla abre o reabre una conversación, y alguien tiene que responder cuando el contacto reaccione. Estos campos definen quién.

`who_will_answer`	Efecto
`AGENT`	El agente de IA asume. Indique cuál en `agentToActivate`.
`HUMAN`	Un atendente humano asume. Indique quién en `attendant_user_id`.
`UNASSIGNED`	La conversación queda sin responsable definido.
(ausente)	Preserva a quien ya estaba atendiendo la conversación.

Para la asignación, owner_user_id y attendant_user_id aceptan tres estados, y la diferencia entre dos de ellos es fácil de confundir:

un ID de usuario asigna la conversación a esa persona
null es la elección explícita de “Sin asignar”, y limpia a quien estaba ahí
omitir el campo significa que usted no opinó, y la asignación actual queda como está

Cuando los dos vienen completos, el propietario tiene precedencia: la conversación queda con owner_user_id.

keep_existing_assignment: true preserva la asignación actual e ignora el who_will_answer: la IA no asume la conversación aunque usted pida AGENT. Si su envío necesita activar el agente, no mande ese campo como true.Por defecto es false, así que las integraciones existentes por API key no cambian de comportamiento.

Contactos ya en conversación activa

Por defecto, un contacto que está en conversación activa no recibe la plantilla. Entra en errors con el motivo ACTIVE_CONVERSATION_BLOCKED, y los demás contactos siguen normalmente. La protección existe para que la plantilla no atropelle una atención en curso, con el contacto recibiendo un envío de campaña en medio de una conversación con una persona. Para enviar de todos modos, use send_to_active_conversations: true.

La respuesta es parcial

El procesamiento es síncrono y un contacto con error no interrumpe a los demás. La respuesta trae el resultado consolidado:

{
  "totalProcessed": 100,
  "sentCount": 95,
  "errorCount": 5,
  "sentContacts": [
    { "conversationId": "65f1a2b3c4d5e6f7a8b9c0d1", "phoneNumber": "5511999999999" }
  ],
  "errors": [
    { "row": 5, "contact": "Juan Silva", "error": "Número de teléfono inválido" },
    { "row": 23, "contact": "María Santos", "error": "Plantilla no encontrada para este inbox" }
  ]
}

Un 200 no significa que todos lo recibieron. Lea siempre errorCount y errors. Si se ignora ese bloque, las fallas de envío pasan desapercibidas. row señala la línea del archivo o el índice en el array contacts.

Reenviar a quienes fallaron es responsabilidad de su integración: no hay retry automático.

Límites que vale la pena conocer

Tier de la cuenta en WhatsApp: Meta limita el número de conversaciones únicas iniciadas por día (1.000, 10.000 o 100.000, según el tier de su cuenta). El envío respeta ese tope: por encima de él, los envíos empiezan a fallar.
Tamaño de medios: imagen hasta 5 MB (JPG, PNG), video hasta 16 MB (MP4, 3GPP), documento hasta 100 MB (PDF, DOC/DOCX, XLS/XLSX, PPT/PPTX, TXT), audio hasta 16 MB.
Enlaces de medios: deben ser URLs HTTPS públicas, accesibles por Meta. Una URL detrás de un login o de una red interna falla.
Tamaño del lote: envíe en bloques de hasta 1.000 contactos por solicitud.

Buenas prácticas

Pruebe con un solo contacto

Envíe primero a su propio número y verifique el resultado en el dispositivo. Un parámetro fuera de orden solo aparece en el mensaje final.

Normalice los teléfonos antes

Use el formato internacional sin símbolos (5511999999999). Un número inválido se convierte en una línea en errors, no en una excepción.

Guarde los conversationId

sentContacts devuelve la conversación creada para cada contacto: es por ella que se hace seguimiento de la respuesta, vía webhooks o GET /v1/messages/conversation/{id}.

Trate los errores como cola de reprocesamiento

Reenvíe solo las líneas de errors, después de corregir el motivo.

Próximos pasos

Webhooks

Reciba las respuestas de quienes fueron impactados por el envío.

Referencia de la API

Contrato completo del endpoint y de los demás envíos.

Primeros pasos

Guías

Envío masivo de plantillas en WhatsApp

Campos de la solicitud

Enviar a una lista de contactos

Parámetros de la plantilla

Ejemplos por tipo de plantilla

Quién atiende después del envío

Contactos ya en conversación activa

La respuesta es parcial

Límites que vale la pena conocer

Buenas prácticas

Próximos pasos

Webhooks

Referencia de la API

​Campos de la solicitud

​Enviar a una lista de contactos

​Parámetros de la plantilla

​Ejemplos por tipo de plantilla

​Quién atiende después del envío

​Contactos ya en conversación activa

​La respuesta es parcial

​Límites que vale la pena conocer

​Buenas prácticas

​Próximos pasos

Webhooks

Referencia de la API

Campos de la solicitud

Enviar a una lista de contactos

Parámetros de la plantilla

Ejemplos por tipo de plantilla

Quién atiende después del envío

Contactos ya en conversación activa

La respuesta es parcial

Límites que vale la pena conocer

Buenas prácticas

Próximos pasos