Saltar al contenido principal
POST
/
api
/
v1
/
meta-templates
/
send-bulk
/
curl -X POST https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/ \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "813497231850626",
    "template_name": "welcome_message",
    "language": "es",
    "recipients": [
      {
        "phone": "+5491112345678",
        "variables": {
          "name": "Juan Perez",
          "code": "ABC123"
        },
        "button_variables": {
          "button_0": "ABC-123"
        }
      },
      {
        "phone": "+5491187654321",
        "variables": {
          "name": "Maria Garcia",
          "code": "DEF456"
        },
        "button_variables": {
          "button_0": "DEF-456"
        }
      },
      {
        "phone": "+5491199887766",
        "variables": {
          "name": "Carlos Lopez",
          "code": "GHI789"
        },
        "button_variables": {
          "button_0": "GHI-789"
        }
      }
    ]
  }'

{
  "bulk_send_id": "a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "task_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
  "status": "queued",
  "template_name": "welcome_message",
  "total_recipients": 3,
  "unique_recipients": 3,
  "estimated_time_minutes": 0.4,
  "created_at": "2025-11-16T21:30:00Z",
  "whatsapp_phone_number": {
    "id": 123,
    "phone_number_id": "813497231850626",
    "display_phone_number": "+54 9 223 675-0780",
    "verified_name": "Mindo Software",
    "quality_rating": "GREEN",
    "messaging_limit_tier": "TIER_1000"
  },
  "quota_info": {
    "can_send": true,
    "quota_needed": 3,
    "quota_available": 997,
    "quota_total": 1000,
    "tier": "TIER_1000"
  }
}

​
Descripción

Este endpoint permite enviar un template de WhatsApp a múltiples destinatarios en una sola solicitud. Implementa un patrón asíncrono: al crear el envío, retorna un bulk_send_id que podés usar para consultar el progreso del envío. La API se encarga automáticamente de respetar los rate limits de Meta según el tier del número, distribuir los envíos y rastrear el estado de cada mensaje individual.

​
Header de autenticación

​
X-API-Key
string
requerido
Tu API Key de Mindo. Formato: mindo_xxxxxxxxxxxxxxxxxxxxxxxx

​
Parámetros del body

​
phone_number_id
string
requerido
ID de Meta del número de WhatsApp desde el cual se enviarán los mensajes. Podés obtenerlo con el endpoint Obtener cuentas de negocio.
​
template_name
string
requerido
Nombre del template aprobado a enviar. Debe tener estado APPROVED en Meta.
​
language
string
Idioma del template. Por defecto: "es". Ejemplos: "es", "en", "pt_BR".
​
recipients
array
requerido
Lista de destinatarios con sus variables personalizadas.

​
Respuesta (202 Accepted)

​
bulk_send_id
string (UUID)
ID único del envío masivo. Usar para consultar el progreso con Estado del envío.
​
task_id
string
ID de la tarea de procesamiento en segundo plano.
​
status
string
Estado inicial del envío. Siempre "queued" al crearse.
​
template_name
string
Nombre del template que se enviará.
​
total_recipients
integer
Total de destinatarios en la lista enviada.
​
unique_recipients
integer
Cantidad de destinatarios únicos después de la deduplicación automática.
​
estimated_time_minutes
float
Tiempo estimado de procesamiento en minutos, basado en el tier del número.
​
created_at
string (ISO 8601)
Fecha y hora de creación del envío.
​
whatsapp_phone_number
object
Información del número de WhatsApp que enviará los mensajes.
​
quota_info
object
Información de cuota y límites de envío.
curl -X POST https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/ \
  -H "X-API-Key: mindo_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "813497231850626",
    "template_name": "welcome_message",
    "language": "es",
    "recipients": [
      {
        "phone": "+5491112345678",
        "variables": {
          "name": "Juan Perez",
          "code": "ABC123"
        },
        "button_variables": {
          "button_0": "ABC-123"
        }
      },
      {
        "phone": "+5491187654321",
        "variables": {
          "name": "Maria Garcia",
          "code": "DEF456"
        },
        "button_variables": {
          "button_0": "DEF-456"
        }
      },
      {
        "phone": "+5491199887766",
        "variables": {
          "name": "Carlos Lopez",
          "code": "GHI789"
        },
        "button_variables": {
          "button_0": "GHI-789"
        }
      }
    ]
  }'

{
  "bulk_send_id": "a3f2b8c9-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "task_id": "7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
  "status": "queued",
  "template_name": "welcome_message",
  "total_recipients": 3,
  "unique_recipients": 3,
  "estimated_time_minutes": 0.4,
  "created_at": "2025-11-16T21:30:00Z",
  "whatsapp_phone_number": {
    "id": 123,
    "phone_number_id": "813497231850626",
    "display_phone_number": "+54 9 223 675-0780",
    "verified_name": "Mindo Software",
    "quality_rating": "GREEN",
    "messaging_limit_tier": "TIER_1000"
  },
  "quota_info": {
    "can_send": true,
    "quota_needed": 3,
    "quota_available": 997,
    "quota_total": 1000,
    "tier": "TIER_1000"
  }
}

​
Estados del envío

El campo status del envío masivo puede tener los siguientes valores:
EstadoDescripción
QUEUEDEnvío creado y en cola de procesamiento
PROCESSINGEnviando mensajes activamente
COMPLETEDTodos los mensajes procesados exitosamente
PARTIALProcesado con algunos fallos
FAILEDEl envío falló completamente
CANCELLEDEnvío cancelado manualmente
Usá el endpoint Estado del envío con el bulk_send_id para consultar el progreso en tiempo real, incluyendo contadores de mensajes enviados, entregados, leídos y fallidos.

​
Deduplicación automática

La API elimina automáticamente números de teléfono duplicados de la lista de recipients. El campo unique_recipients en la respuesta indica la cantidad real de destinatarios únicos que recibirán el mensaje, mientras que total_recipients refleja la cantidad original enviada.

​
Casos de uso

Envía un mensaje de bienvenida personalizado a una lista de nuevos clientes registrados.
import requests

new_customers = [
    {"phone": "+5491112345678", "name": "Juan Perez"},
    {"phone": "+5491187654321", "name": "Maria Garcia"},
    {"phone": "+5491199887766", "name": "Carlos Lopez"},
]

response = requests.post(
    "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
    headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "phone_number_id": "813497231850626",
        "template_name": "welcome_message",
        "recipients": [
            {"phone": c["phone"], "variables": {"name": c["name"]}}
            for c in new_customers
        ]
    }
)

bulk = response.json()
print(f"Envío creado: {bulk['bulk_send_id']}")
print(f"Destinatarios: {bulk['unique_recipients']}")
Envía códigos de verificación únicos a cada destinatario.
import requests
import secrets

users = [
    {"phone": "+5491112345678", "name": "Juan"},
    {"phone": "+5491187654321", "name": "Maria"},
]

recipients = [
    {
        "phone": user["phone"],
        "variables": {
            "name": user["name"],
            "code": secrets.token_hex(3).upper()
        }
    }
    for user in users
]

response = requests.post(
    "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
    headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "phone_number_id": "813497231850626",
        "template_name": "verification_code",
        "recipients": recipients
    }
)
Notifica a múltiples clientes sobre actualizaciones en sus pedidos.
const orders = [
  { phone: "+5491112345678", orderId: "ORD-001", status: "Enviado" },
  { phone: "+5491187654321", orderId: "ORD-002", status: "En camino" },
  { phone: "+5491199887766", orderId: "ORD-003", status: "Entregado" },
];

const response = await fetch(
  "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
  {
    method: "POST",
    headers: {
      "X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      phone_number_id: "813497231850626",
      template_name: "order_update",
      recipients: orders.map(o => ({
        phone: o.phone,
        variables: { order_id: o.orderId, status: o.status }
      }))
    })
  }
);

const data = await response.json();
console.log(`Envío ${data.bulk_send_id} creado para ${data.unique_recipients} destinatarios`);
Envía recordatorios personalizados con fecha y hora del evento.
import requests

attendees = [
    {"phone": "+5491112345678", "name": "Juan Perez"},
    {"phone": "+5491187654321", "name": "Maria Garcia"},
]

response = requests.post(
    "https://api.mindosoftware.com/api/v1/meta-templates/send-bulk/",
    headers={"X-API-Key": "mindo_xxxxxxxxxxxxxxxxxxxxxxxx"},
    json={
        "phone_number_id": "813497231850626",
        "template_name": "event_reminder",
        "recipients": [
            {
                "phone": a["phone"],
                "variables": {
                    "name": a["name"],
                    "event_name": "Webinar: Introducción a la API",
                    "event_date": "28 de noviembre, 18:00 hs"
                }
            }
            for a in attendees
        ]
    }
)

bulk = response.json()
print(f"Recordatorios enviados: {bulk['unique_recipients']}")
print(f"Tiempo estimado: {bulk['estimated_time_minutes']} minutos")