Enviar mensagem em massa

Método

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

Conceituação

Este endpoint permite enviar a mesma mensagem para múltiplos destinatários de forma sequencial. A API enfileira todas as mensagens e as processa com um intervalo configurável entre cada envio, adicionando jitter automático para evitar detecção de automação.

Você pode agendar o envio para uma data futura utilizando o campo startAt. Caso não seja informado, o envio começa imediatamente.

A resposta retorna um batchId que pode ser utilizado para consultar o progresso, listar erros ou cancelar o envio.

---

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 que será utilizado para o envio
messageType	string	Sim	Tipo da mensagem: text, image, video, audio, document
content	object	Sim	Conteúdo da mensagem. Estrutura varia conforme o messageType
content.text	string	Condicional	Texto da mensagem. Obrigatório quando messageType = text
content.url	string	Condicional	URL da mídia. Obrigatório quando messageType = image, video, audio, document
content.caption	string	Não	Legenda da mídia. Disponível para image, video e document
content.fileName	string	Não	Nome do arquivo. Disponível para document
recipients	string[]	Sim	Array de números de telefone dos destinatários (formato: 5511999999999)
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.startAt	string	Não	Data/hora de início do envio no formato ISO 8601 (ex: 2025-06-15T14:00:00Z)
options.name	string	Não	Nome identificador do lote para facilitar consultas posteriores

---

Request

Envio de texto

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/bulk/send" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "6650f4c2e8b1a2d3f4567890",
    "messageType": "text",
    "content": {
      "text": "Olá! Temos uma promoção especial para você. Confira nosso catálogo atualizado."
    },
    "recipients": [
      "5511999990001",
      "5511999990002",
      "5511999990003",
      "5511999990004",
      "5511999990005"
    ],
    "options": {
      "delay": 3000,
      "name": "Campanha Junho 2025"
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/bulk/send',
  {
    channelId: '6650f4c2e8b1a2d3f4567890',
    messageType: 'text',
    content: {
      text: 'Olá! Temos uma promoção especial para você. Confira nosso catálogo atualizado.'
    },
    recipients: [
      '5511999990001',
      '5511999990002',
      '5511999990003',
      '5511999990004',
      '5511999990005'
    ],
    options: {
      delay: 3000,
      name: 'Campanha Junho 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',
    json={
        'channelId': '6650f4c2e8b1a2d3f4567890',
        'messageType': 'text',
        'content': {
            'text': 'Olá! Temos uma promoção especial para você. Confira nosso catálogo atualizado.'
        },
        'recipients': [
            '5511999990001',
            '5511999990002',
            '5511999990003',
            '5511999990004',
            '5511999990005'
        ],
        'options': {
            'delay': 3000,
            'name': 'Campanha Junho 2025'
        }
    },
    headers={
        'Authorization': 'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Envio de imagem

cURL

curl -X POST "https://oapi.ogmma.com.br/v1/bulk/send" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "6650f4c2e8b1a2d3f4567890",
    "messageType": "image",
    "content": {
      "url": "https://exemplo.com/promo-junho.jpg",
      "caption": "Confira nossas ofertas de Junho!"
    },
    "recipients": [
      "5511999990001",
      "5511999990002"
    ],
    "options": {
      "delay": 5000,
      "startAt": "2025-06-15T14:00:00Z",
      "name": "Promo Junho - Imagem"
    }
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://oapi.ogmma.com.br/v1/bulk/send',
  {
    channelId: '6650f4c2e8b1a2d3f4567890',
    messageType: 'image',
    content: {
      url: 'https://exemplo.com/promo-junho.jpg',
      caption: 'Confira nossas ofertas de Junho!'
    },
    recipients: [
      '5511999990001',
      '5511999990002'
    ],
    options: {
      delay: 5000,
      startAt: '2025-06-15T14:00:00Z',
      name: 'Promo Junho - Imagem'
    }
  },
  {
    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',
    json={
        'channelId': '6650f4c2e8b1a2d3f4567890',
        'messageType': 'image',
        'content': {
            'url': 'https://exemplo.com/promo-junho.jpg',
            'caption': 'Confira nossas ofertas de Junho!'
        },
        'recipients': [
            '5511999990001',
            '5511999990002'
        ],
        'options': {
            'delay': 5000,
            'startAt': '2025-06-15T14:00:00Z',
            'name': 'Promo Junho - Imagem'
        }
    },
    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_6651a3b2c4d5e6f7a8901234",
    "status": "QUEUED",
    "totalRecipients": 5
  }
}

400 - Bad Request

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

{
  "message": "O campo 'recipients' deve conter pelo menos 1 destinatário.",
  "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é 100 destinatários.",
  "code": "RATE_LIMIT_EXCEEDED"
}