API de mensagens
API de histórico de mensagens
Obtenha uma lista das mensagens do seu espaço de trabalho em um intervalo de datas, com o status de cada uma. Use-a para conferir o que foi enviado, montar relatórios ou encontrar mensagens que falharam para reenviar.
https://wbiztool.com/api/v1/report/Corpo: JSON (necessário para as páginas após a primeira) ou campos de formulário
O histórico abrange todas as mensagens do espaço de trabalho da sua chave de API, sejam elas enviadas pela API, pelo painel ou por uma campanha. Os resultados vêm com 200 por página, das mais antigas para as mais recentes. Os mesmos dados estão disponíveis na página Relatórios.
Exemplo rápido#
curl -X POST https://wbiztool.com/api/v1/report/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": 1
}'import requests
page = 1
history = []
while True:
response = requests.post(
"https://wbiztool.com/api/v1/report/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": page, # must be a JSON number, not a string
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") != "Success" or "total" not in result:
print("Failed:", result.get("message", "no message in response"))
break
history.extend(result["history"])
if page * 200 >= result["total"]:
break
page += 1
failed = [m for m in history if m["message_status"] == "Failed"]
print(len(history), "messages,", len(failed), "failed")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const history = [];
let page = 1;
while (true) {
const response = await fetch("https://wbiztool.com/api/v1/report/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
start_date: "01-09-2026",
end_date: "08-09-2026",
page, // must be a JSON number, not a string
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message !== "Success" || !("total" in result)) {
console.error("Failed:", result.message ?? "no message in response");
break;
}
history.push(...result.history);
if (page * 200 >= result.total) break;
page += 1;
}
const failed = history.filter((m) => m.message_status === "Failed");
console.log(`${history.length} messages, ${failed.length} failed`);<?php
$history = [];
$page = 1;
do {
$ch = curl_init('https://wbiztool.com/api/v1/report/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'start_date' => '01-09-2026',
'end_date' => '08-09-2026',
'page' => $page, // an integer, so json_encode sends a number
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') !== 'Success' || !isset($result['total'])) {
echo 'Failed: ' . ($result['message'] ?? 'no message in response');
break;
}
$history = array_merge($history, $result['history']);
$page++;
} while (($page - 1) * 200 < $result['total']);
echo count($history) . ' messages';Substitua 12345 e YOUR_API_KEY pelos seus próprios valores. Veja em Autenticação onde encontrá-los.
Parâmetros da requisição#
Autenticação
client_idintegerobrigatórioSeu ID do Cliente da API, em Configurações → Chaves API.
api_keystringobrigatórioSua chave de API, na mesma página.
Filtros
start_datestringobrigatórioPrimeiro dia a incluir, no formato
DD-MM-YYYY, por exemplo01-09-2026.end_datestringobrigatórioFim do intervalo, no formato
DD-MM-YYYY. Este dia em si não é incluído. Veja Intervalo de datas.whatsapp_clientintegeropcionalRetorna somente as mensagens enviadas deste número de WhatsApp, usando o ID dele nas configurações do WhatsApp. Não envie para obter as mensagens de todos os seus números.
pageintegeropcionalNúmero da página, começando em
1(o padrão). Cada página contém até 200 mensagens. Envie-o como número JSON.0ou um número negativo retornatotalcom umhistoryvazio.
Intervalo de datas#
As datas são interpretadas como meia-noite do início daquele dia no horário padrão da Índia (IST, UTC+5:30), e as mensagens são filtradas pela data em que foram criadas (colocadas na fila ou agendadas), não pela data de envio. O intervalo vai de start_date 00:00 até end_date 00:00, portanto:
"start_date": "01-09-2026", "end_date": "08-09-2026"retorna de 1 a 7 de setembro. O dia 8 de setembro não é incluído.- Para obter um único dia, defina
end_datecomo o dia seguinte:"start_date": "15-09-2026", "end_date": "16-09-2026". - Se as duas datas forem iguais, você não recebe nenhuma mensagem.
Paginação#
Cada resposta contém total, o número de mensagens em todo o intervalo, e até 200 delas em history. Solicite page 2, 3 e assim por diante até que page × 200 seja pelo menos total.
Resposta#
Uma requisição bem-sucedida retorna HTTP 200:
{
"message": "Success",
"status": 0,
"total": 3,
"history": [
{ "id": 9817263, "msg_type": "Text", "contact": "919876543210", "message_status": "Sent" },
{ "id": 9817264, "msg_type": "File", "contact": "919812345670", "message_status": "Failed" },
{ "id": 9817265, "msg_type": "Image", "contact": "Sales Team Mumbai", "message_status": "Pending" }
]
}
| Campo | Tipo | Descrição |
|---|---|---|
message | string | Success quando a requisição funcionou; caso contrário, o erro. |
status | integer | Sempre 0. Não o use para detectar sucesso. |
total | integer | Número de mensagens no intervalo de datas, somando todas as páginas. Presente apenas em caso de sucesso. |
history | array | Até 200 mensagens nesta página, das mais antigas para as mais recentes. Vazio quando há erro. |
history[].id | integer | ID da mensagem, o mesmo msg_id retornado no envio. |
history[].msg_type | string | Text, Image ou File. |
history[].contact | string | O número de telefone do destinatário com código do país, ou o nome do grupo para mensagens de grupo. |
history[].message_status | string | Veja a tabela abaixo. |
Valores de status da mensagem#
message_status | Significado |
|---|---|
Pending | Na fila ou agendada, ainda não enviada (status 0). |
Sent | Enviada do seu número de WhatsApp (status 1). |
Delivered | Reservado, não é retornado atualmente. |
Read | Reservado, não é retornado atualmente. |
Failed | Não pôde ser enviada, ou o envio foi interrompido (status 2). Use Status da mensagem para ver o error. |
Cancelled | Cancelada antes de ser enviada (status 3). |
Expired | Não foi enviada antes do prazo definido em expire_after_seconds (status 4). |
Os tiques de entrega e de leitura não são registrados no momento, então as mensagens enviadas sempre aparecem como Sent. Delivered e Read são valores reservados; se algum dia aparecerem, trate-os como Sent.
Erros#
Os erros retornam HTTP 200 com status igual a 0, salvo indicação em contrário:
{ "message": "Error", "status": 0, "history": [] }
| Mensagem | Como corrigir |
|---|---|
Error | start_date ou end_date está ausente ou não está no formato DD-MM-YYYY, o corpo JSON não é válido (geralmente por uma vírgula sobrando no final) ou a requisição não foi um POST. |
Auth Error | Envie client_id e api_key. |
Invalid Client Id | Envie client_id como número. Retornado com HTTP 403, sem history. |
Auth Error: invalid api key | Verifique se a chave existe, não foi excluída e pertence a este client_id. Retornado com HTTP 400, sem history. |
Demo Account can not access apis | Use uma conta normal. |
Dicas#
- Consulte o histórico em intervalos pequenos: um dia ou uma semana de cada vez mantém baixo o número de páginas.
- Encontre mensagens que falharam: filtre
historyporFailede chame Status da mensagem com cadaidpara ver por que falhou. Antes de tentar de novo, confira oerror:Sending was interrupted and may have been delivered…significa que o destinatário pode já ter a mensagem. - Mensagens antigas são removidas: mensagens que chegaram a um status final e não mudaram por cerca de 90 dias podem ser removidas e deixar de aparecer aqui, assim como as mensagens que ainda estão na fila 90 dias depois de criadas ou agendadas, em um número desconectado ou excluído.
- Acompanhamento em tempo real: para reagir quando as mensagens forem enviadas, informe um
webhookao enviar a mensagem em vez de consultar este endpoint repetidamente.
