> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindosoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Envio em massa

> Envio em massa de mensagens de template do WhatsApp Business

## 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](/pt/api-reference/envio-masivo/estado-envio) 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

<ParamField header="X-API-Key" type="string" required>
  Sua API Key da Mindo. Formato: `mindo_xxxxxxxxxxxxxxxxxxxxxxxx`
</ParamField>

## Parâmetros do body

<ParamField body="phone_number_id" type="string" required>
  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](/pt/api-reference/cuentas-negocio/obtener-cuentas).
</ParamField>

<ParamField body="template_name" type="string" required>
  Nome do template aprovado a ser enviado. Deve ter status `APPROVED` na Meta.
</ParamField>

<ParamField body="language" type="string">
  Idioma do template. Padrão: `"es"`. Exemplos: `"es"`, `"en"`, `"pt_BR"`.
</ParamField>

<ParamField body="recipients" type="array" required>
  Lista de destinatários com suas variáveis personalizadas.

  <Expandable title="Propriedades de cada destinatário">
    <ParamField body="phone" type="string" required>
      Número de telefone em formato internacional (ex.: `"+5491112345678"`). Sem espaços.
    </ParamField>

    <ParamField body="variables" type="object">
      Variáveis personalizadas para este destinatário. As chaves devem corresponder às variáveis do template.
    </ParamField>

    <ParamField body="button_variables" type="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.
    </ParamField>
  </Expandable>
</ParamField>

## Resposta (202 Accepted)

<ResponseField name="bulk_send_id" type="string (UUID)">
  ID único do envio em massa. Use para verificar o progresso com [Status do envio](/pt/api-reference/envio-masivo/estado-envio).
</ResponseField>

<ResponseField name="task_id" type="string">
  ID da tarefa de processamento em segundo plano.
</ResponseField>

<ResponseField name="status" type="string">
  Status inicial do envio. Sempre `"queued"` quando criado.
</ResponseField>

<ResponseField name="template_name" type="string">
  Nome do template a ser enviado.
</ResponseField>

<ResponseField name="total_recipients" type="integer">
  Total de destinatários na lista enviada.
</ResponseField>

<ResponseField name="unique_recipients" type="integer">
  Número de destinatários únicos após deduplicação automática.
</ResponseField>

<ResponseField name="estimated_time_minutes" type="float">
  Tempo estimado de processamento em minutos, baseado no nível do número.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Data e hora de criação do envio.
</ResponseField>

<ResponseField name="whatsapp_phone_number" type="object">
  Informações sobre o número do WhatsApp que enviará as mensagens.

  <Expandable title="Propriedades de whatsapp_phone_number">
    <ResponseField name="id" type="integer">
      ID interno do número.
    </ResponseField>

    <ResponseField name="phone_number_id" type="string">
      ID do número de telefone do WhatsApp na Meta.
    </ResponseField>

    <ResponseField name="display_phone_number" type="string">
      Número formatado para exibição.
    </ResponseField>

    <ResponseField name="verified_name" type="string">
      Nome verificado pela Meta.
    </ResponseField>

    <ResponseField name="quality_rating" type="string">
      Classificação de qualidade do número (`GREEN`, `YELLOW`, `RED`).
    </ResponseField>

    <ResponseField name="messaging_limit_tier" type="string">
      Nível de limite de envio da Meta.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="quota_info" type="object">
  Informações de cota e limites de envio.

  <Expandable title="Propriedades de quota_info">
    <ResponseField name="can_send" type="boolean">
      Se o envio é possível com a cota atual.
    </ResponseField>

    <ResponseField name="quota_needed" type="integer">
      Cota necessária para este envio.
    </ResponseField>

    <ResponseField name="quota_available" type="integer">
      Cota disponível no momento.
    </ResponseField>

    <ResponseField name="quota_total" type="integer">
      Cota total do plano.
    </ResponseField>

    <ResponseField name="tier" type="string">
      Nível do WhatsApp do número.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
          }
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  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",
          "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"}
              }
          ]
      }
  )

  data = response.json()
  print(f"Bulk Send ID: {data['bulk_send_id']}")
  print(f"Destinatários: {data['unique_recipients']}")
  ```

  ```javascript JavaScript theme={null}
  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: "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" }
          }
        ]
      })
    }
  );

  const data = await response.json();
  console.log("Bulk Send ID:", data.bulk_send_id);
  console.log("Destinatários:", data.unique_recipients);
  ```
</RequestExample>

<ResponseExample>
  ```json 202 - Accepted theme={null}
  {
    "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"
    }
  }
  ```

  ```json 400 - Validação theme={null}
  {
    "phone_number_id": ["This field is required."],
    "recipients": ["This field is required."]
  }
  ```

  ```json 400 - Destinatários vazios theme={null}
  {
    "error": "recipients es requerido y no puede estar vacio"
  }
  ```

  ```json 404 - Template não encontrado theme={null}
  {
    "error": "Template 'welcome_message' (language: es) no encontrado en este business account"
  }
  ```

  ```json 404 - Número não encontrado theme={null}
  {
    "error": "Numero de WhatsApp con ID '813497231850626' no encontrado"
  }
  ```

  ```json 401 - Não autenticado theme={null}
  {
    "error": "Este endpoint requiere autenticacion con API Key (header X-API-Key)"
  }
  ```
</ResponseExample>

## 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                |

<Note>
  Use o endpoint [Status do envio](/pt/api-reference/envio-masivo/estado-envio) com o `bulk_send_id` para verificar o progresso em tempo real, incluindo contadores de mensagens enviadas, entregues, lidas e com falha.
</Note>

## 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

<AccordionGroup>
  <Accordion title="Campanha de boas-vindas para novos clientes">
    Envie uma mensagem de boas-vindas personalizada para uma lista de clientes recém-cadastrados.

    ```python theme={null}
    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']}")
    ```
  </Accordion>

  <Accordion title="Códigos de verificação em massa">
    Envie códigos de verificação únicos para cada destinatário.

    ```python theme={null}
    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
        }
    )
    ```
  </Accordion>

  <Accordion title="Notificações de status de pedidos">
    Notifique múltiplos clientes sobre atualizações dos seus pedidos.

    ```javascript theme={null}
    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`);
    ```
  </Accordion>

  <Accordion title="Lembretes de eventos">
    Envie lembretes personalizados com data e hora do evento.

    ```python theme={null}
    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")
    ```
  </Accordion>
</AccordionGroup>