Consultar status do lote

Método

GET https://oapi.ogmma.com.br/v1/bulk/:batchId

Conceituação

Este endpoint permite consultar o status detalhado de um lote de envio em massa. Retorna informações sobre o progresso do envio, incluindo a quantidade de mensagens enviadas, falhadas e pendentes, além de um array com os erros ocorridos.

Utilize este endpoint para acompanhar o progresso de um envio em andamento ou para verificar o resultado final após a conclusão.

---

Atributos

Header

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

Parâmetros de URL

Atributo	Tipo	Obrigatório	Descrição
batchId	string	Sim	ID do lote retornado na criação

---

Request

cURL

curl -X GET "https://oapi.ogmma.com.br/v1/bulk/{batchId}" \
  -H "Authorization: Bearer {API_KEY}"

Node.js

const axios = require('axios');

const batchId = 'bulk_6651a3b2c4d5e6f7a8901234';

const response = await axios.get(
  `https://oapi.ogmma.com.br/v1/bulk/${batchId}`,
  {
    headers: {
      'Authorization': 'Bearer {API_KEY}'
    }
  }
);

console.log(response.data);

Python

import requests

batch_id = 'bulk_6651a3b2c4d5e6f7a8901234'

response = requests.get(
    f'https://oapi.ogmma.com.br/v1/bulk/{batch_id}',
    headers={
        'Authorization': 'Bearer {API_KEY}'
    }
)

print(response.json())

---

Response

200 - Success

Retorna o status detalhado do lote.

{
  "data": {
    "batchId": "bulk_6651a3b2c4d5e6f7a8901234",
    "status": "IN_PROGRESS",
    "name": "Campanha Junho 2025",
    "totalRecipients": 500,
    "progress": {
      "sent": 342,
      "failed": 8,
      "pending": 150
    },
    "errors": [
      {
        "to": "5511999990010",
        "error": "Numero nao esta registrado no WhatsApp.",
        "at": "2025-06-10T15:02:30Z"
      },
      {
        "to": "5511999990025",
        "error": "Timeout ao enviar mensagem.",
        "at": "2025-06-10T15:04:12Z"
      }
    ],
    "startedAt": "2025-06-10T15:00:00Z",
    "estimatedCompletion": "2025-06-10T15:25:00Z",
    "createdAt": "2025-06-10T14:59:50Z"
  }
}

Campos da resposta

Campo	Tipo	Descrição
batchId	string	Identificador único do lote
status	string	Status atual: QUEUED, IN_PROGRESS, COMPLETED, PARTIALLY_FAILED, CANCELLED
name	string	Nome identificador do lote
totalRecipients	number	Total de destinatários no lote
sent	number	Quantidade de mensagens enviadas com sucesso
failed	number	Quantidade de mensagens que falharam
pending	number	Quantidade de mensagens aguardando envio
progress	number	Percentual de progresso (0 a 100)
errors	object[]	Array com os erros ocorridos durante o envio
errors[].to	string	Número do destinatário que falhou
errors[].error	string	Descrição do erro
errors[].at	string	Data/hora em que o erro ocorreu (ISO 8601)
startedAt	string	Data/hora de início do processamento (ISO 8601)
estimatedCompletion	string	Data/hora estimada de conclusão (ISO 8601)
createdAt	string	Data/hora de criação do lote (ISO 8601)

400 - Bad Request

ID do lote inválido.

{
  "message": "O ID do lote informado é inválido.",
  "code": "BULK_BATCH_NOT_FOUND"
}

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.

{
  "message": "Limite de requisições excedido. Tente novamente em alguns segundos.",
  "code": "RATE_LIMIT_EXCEEDED"
}