Envio em massa

Descrição

Este endpoint permite enviar um template do WhatsApp para múltiplos destinatários em uma única requisição. Implementa um padrão assíncrono: ao criar o envio, retorna um bulk_send_id que você pode usar para verificar o progresso do envio. A API gerencia automaticamente os limites de taxa da Meta com base no nível do número, distribui os envios e rastreia o status de cada mensagem individual.

Header de autenticação

X-API-Key

string

obrigatório

Sua API Key da Mindo. Formato: mindo_xxxxxxxxxxxxxxxxxxxxxxxx

Parâmetros do body

phone_number_id

string

obrigatório

ID do número de telefone do WhatsApp na Meta a partir do qual as mensagens serão enviadas. Você pode obtê-lo no endpoint Obter contas de negócio.

template_name

string

obrigatório

Nome do template aprovado a ser enviado. Deve ter status APPROVED na Meta.

language

string

Idioma do template. Padrão: "es". Exemplos: "es", "en", "pt_BR".

recipients

array

obrigatório

Lista de destinatários com suas variáveis personalizadas.

Mostrar Propriedades de cada destinatário

phone

string

obrigatório

Número de telefone em formato internacional (ex.: "+5491112345678"). Sem espaços.

variables

object

Variáveis personalizadas para este destinatário. As chaves devem corresponder às variáveis do template.

button_variables

object

Variáveis para botões dinâmicos do template. As chaves usam o formato button_0, button_1, etc., onde o número corresponde ao índice do botão (começando em 0). Os valores são os sufixos dinâmicos ou payloads de cada botão.Importante: Botões do tipo URL suportam apenas 1 variável.

Resposta (202 Accepted)

bulk_send_id

string (UUID)

ID único do envio em massa. Use para verificar o progresso com Status do envio.

task_id

string

ID da tarefa de processamento em segundo plano.

status

string

Status inicial do envio. Sempre "queued" quando criado.

template_name

string

Nome do template a ser enviado.

total_recipients

integer

Total de destinatários na lista enviada.

unique_recipients

integer

Número de destinatários únicos após deduplicação automática.

estimated_time_minutes

float

Tempo estimado de processamento em minutos, baseado no nível do número.

created_at

string (ISO 8601)

Data e hora de criação do envio.

whatsapp_phone_number

object

Informações sobre o número do WhatsApp que enviará as mensagens.

Mostrar Propriedades de whatsapp_phone_number

integer

ID interno do número.

phone_number_id

string

ID do número de telefone do WhatsApp na Meta.

display_phone_number

string

Número formatado para exibição.

verified_name

string

Nome verificado pela Meta.

quality_rating

string

Classificação de qualidade do número (GREEN, YELLOW, RED).

messaging_limit_tier

string

Nível de limite de envio da Meta.

quota_info

object

Informações de cota e limites de envio.

Mostrar Propriedades de quota_info

can_send

boolean

Se o envio é possível com a cota atual.

quota_needed

integer

Cota necessária para este envio.

quota_available

integer

Cota disponível no momento.

quota_total

integer

Cota total do plano.

tier

string

Nível do WhatsApp do número.

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"
  }
}

Status do envio

O campo status do envio em massa pode ter os seguintes valores:

Status	Descrição
`QUEUED`	Envio criado e na fila para processamento
`PROCESSING`	Enviando mensagens ativamente
`COMPLETED`	Todas as mensagens processadas com sucesso
`PARTIAL`	Processado com algumas falhas
`FAILED`	Envio falhou completamente
`CANCELLED`	Envio cancelado manualmente

Use o endpoint Status do envio com o bulk_send_id para verificar o progresso em tempo real, incluindo contadores de mensagens enviadas, entregues, lidas e com falha.

Deduplicação automática

A API remove automaticamente números de telefone duplicados da lista de recipients. O campo unique_recipients na resposta indica o número real de destinatários únicos que receberão a mensagem, enquanto total_recipients reflete a contagem original enviada.

Casos de uso

Campanha de boas-vindas para novos clientes

Envie uma mensagem de boas-vindas personalizada para uma lista de clientes recém-cadastrados.

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"Envio criado: {bulk['bulk_send_id']}")
print(f"Destinatários: {bulk['unique_recipients']}")

Códigos de verificação em massa

Envie códigos de verificação únicos para cada destinatário.

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ções de status de pedidos

Notifique múltiplos clientes sobre atualizações dos seus pedidos.

const orders = [
  { phone: "+5491112345678", orderId: "ORD-001", status: "Enviado" },
  { phone: "+5491187654321", orderId: "ORD-002", status: "Em trânsito" },
  { phone: "+5491199887766", orderId: "ORD-003", status: "Entregue" },
];

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(`Envio ${data.bulk_send_id} criado para ${data.unique_recipients} destinatários`);

Lembretes de eventos

Envie lembretes personalizados com data e hora do 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: Introdução à API",
                    "event_date": "28 de novembro, 18:00"
                }
            }
            for a in attendees
        ]
    }
)

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

Começar

Contas de negócio

Mensagens

Contatos

Envio em massa

Descrição

Header de autenticação

Parâmetros do body

Resposta (202 Accepted)

Status do envio

Deduplicação automática

Casos de uso

Começar

Contas de negócio

Mensagens

Contatos

Envio em massa

​Descrição

​Header de autenticação

​Parâmetros do body

​Resposta (202 Accepted)

​Status do envio

​Deduplicação automática

​Casos de uso

Descrição

Header de autenticação

Parâmetros do body

Resposta (202 Accepted)

Status do envio

Deduplicação automática

Casos de uso