Enviar template em massa

Método

POST https://oapi.ogmma.com.br/v1/bulk/send/template

Conceituação

Este endpoint permite enviar templates personalizados para múltiplos destinatários de forma sequencial. Disponível apenas para canais WABA (WhatsApp Business API).

A principal vantagem em relação ao envio em massa comum é a possibilidade de personalizar os parâmetros do template para cada destinatário individualmente. Por exemplo, você pode enviar uma mensagem de cobrança onde o nome e o valor são diferentes para cada pessoa.

Os templates devem ser previamente aprovados no Meta Business Manager antes de serem utilizados.

---

Atributos

Header

Atributo	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Bearer {API_KEY} - Chave de autenticação
Content-Type	string	Sim	application/json

Body

Atributo	Tipo	Obrigatório	Descrição
channelId	string	Sim	ID do canal WABA que será utilizado para o envio
templateName	string	Sim	Nome do template aprovado no Meta Business Manager
language	string	Sim	Código do idioma do template (ex: pt_BR, en_US)
recipients	object[]	Sim	Array de destinatários com seus parâmetros personalizados
recipients[].to	string	Sim	Número de telefone do destinatário (formato: 5511999999999)
recipients[].parameters	object	Sim	Parâmetros de personalização do template para este destinatário
recipients[].parameters.body	string[]	Não	Parâmetros do corpo do template, na ordem em que aparecem
recipients[].parameters.header	string[]	Não	Parâmetros do cabeçalho do template
recipients[].parameters.buttons	object[]	Não	Parâmetros dos botões do template
options	object	Não	Opções de configuração do envio
options.delay	number	Não	Intervalo em milissegundos entre cada envio. Mínimo: 1000. Padrão: 3000
options.name	string	Não	Nome identificador do lote para facilitar consultas posteriores

---

Request

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/bulk/send/template" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "6650f4c2e8b1a2d3f4567890",
    "templateName": "lembrete_pagamento",
    "language": "pt_BR",
    "recipients": [
      {
        "to": "5511999990001",
        "parameters": {
          "body": ["Maria Silva", "R$ 150,00", "15/07/2025"]
        }
      },
      {
        "to": "5511999990002",
        "parameters": {
          "body": ["João Santos", "R$ 320,00", "20/07/2025"]
        }
      },
      {
        "to": "5511999990003",
        "parameters": {
          "body": ["Ana Oliveira", "R$ 89,90", "18/07/2025"]
        }
      }
    ],
    "options": {
      "delay": 3000,
      "name": "Cobrança Julho 2025"
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/bulk/send/template',
  {
    channelId: '6650f4c2e8b1a2d3f4567890',
    templateName: 'lembrete_pagamento',
    language: 'pt_BR',
    recipients: [
      {
        to: '5511999990001',
        parameters: {
          body: ['Maria Silva', 'R$ 150,00', '15/07/2025']
        }
      },
      {
        to: '5511999990002',
        parameters: {
          body: ['João Santos', 'R$ 320,00', '20/07/2025']
        }
      },
      {
        to: '5511999990003',
        parameters: {
          body: ['Ana Oliveira', 'R$ 89,90', '18/07/2025']
        }
      }
    ],
    options: {
      delay: 3000,
      name: 'Cobrança Julho 2025'
    }
  },
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://oapi.ogmma.com.br/v1/bulk/send/template',
    json={
        'channelId': '6650f4c2e8b1a2d3f4567890',
        'templateName': 'lembrete_pagamento',
        'language': 'pt_BR',
        'recipients': [
            {
                'to': '5511999990001',
                'parameters': {
                    'body': ['Maria Silva', 'R$ 150,00', '15/07/2025']
                }
            },
            {
                'to': '5511999990002',
                'parameters': {
                    'body': ['João Santos', 'R$ 320,00', '20/07/2025']
                }
            },
            {
                'to': '5511999990003',
                'parameters': {
                    'body': ['Ana Oliveira', 'R$ 89,90', '18/07/2025']
                }
            }
        ],
        'options': {
            'delay': 3000,
            'name': 'Cobrança Julho 2025'
        }
    },
    headers={
        'Authorization': 'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

---

Response

202 - Accepted

O lote foi criado e enfileirado para processamento.

{
  "data": {
    "batchId": "bulk_6651a3b2c4d5e6f7a8905678",
    "status": "QUEUED",
    "totalRecipients": 3
  }
}

400 - Bad Request

Parâmetros inválidos na requisição.

{
  "message": "O template 'lembrete_pagamento' requer 3 parâmetros no body, mas foram informados 2 para o destinatário '5511999990001'.",
  "code": "VALIDATION_ERROR"
}

401 - Unauthorized

Chave de API inválida ou ausente.

{
  "message": "Chave de API inválida ou expirada.",
  "code": "UNAUTHORIZED"
}

429 - Too Many Requests

Limite de requisições excedido ou lote acima do permitido pelo plano.

{
  "message": "Limite de destinatários por lote excedido. Seu plano permite até 1.000 destinatários.",
  "code": "RATE_LIMIT_EXCEEDED"
}