Pular para o conteúdo
Wbiztool

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.

POSThttps://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
  }'

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ório

Seu ID do Cliente da API, em Configurações → Chaves API.

api_keystringobrigatório

Sua chave de API, na mesma página.

Filtros

start_datestringobrigatório

Primeiro dia a incluir, no formato DD-MM-YYYY, por exemplo 01-09-2026.

end_datestringobrigatório

Fim do intervalo, no formato DD-MM-YYYY. Este dia em si não é incluído. Veja Intervalo de datas.

whatsapp_clientintegeropcional

Retorna 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.

pageintegeropcional

Nú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. 0 ou um número negativo retorna total com um history vazio.

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_date como 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" }
  ]
}
CampoTipoDescrição
messagestringSuccess quando a requisição funcionou; caso contrário, o erro.
statusintegerSempre 0. Não o use para detectar sucesso.
totalintegerNúmero de mensagens no intervalo de datas, somando todas as páginas. Presente apenas em caso de sucesso.
historyarrayAté 200 mensagens nesta página, das mais antigas para as mais recentes. Vazio quando há erro.
history[].idintegerID da mensagem, o mesmo msg_id retornado no envio.
history[].msg_typestringText, Image ou File.
history[].contactstringO número de telefone do destinatário com código do país, ou o nome do grupo para mensagens de grupo.
history[].message_statusstringVeja a tabela abaixo.

Valores de status da mensagem#

message_statusSignificado
PendingNa fila ou agendada, ainda não enviada (status 0).
SentEnviada do seu número de WhatsApp (status 1).
DeliveredReservado, não é retornado atualmente.
ReadReservado, não é retornado atualmente.
FailedNão pôde ser enviada, ou o envio foi interrompido (status 2). Use Status da mensagem para ver o error.
CancelledCancelada antes de ser enviada (status 3).
ExpiredNã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": [] }
MensagemComo corrigir
Errorstart_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 ErrorEnvie client_id e api_key.
Invalid Client IdEnvie client_id como número. Retornado com HTTP 403, sem history.
Auth Error: invalid api keyVerifique 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 apisUse 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 history por Failed e chame Status da mensagem com cada id para ver por que falhou. Antes de tentar de novo, confira o error: 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 webhook ao enviar a mensagem em vez de consultar este endpoint repetidamente.