Envio em massa - Mindo API

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

POST

api

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

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

Consultar contato Status do envio

​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