Pular para o conteúdo
Wbiztool

API de mensagens

API de status da mensagem

Verifique se uma mensagem que você enviou pela API ainda está na fila, já foi enviada ou falhou. Use-a para confirmar que mensagens importantes foram enviadas e descobrir por que alguma não foi.

POSThttps://wbiztool.com/api/v1/message/status/{msg_id}/

Corpo: JSON ou campos de formulário

Coloque o ID da mensagem na URL, substituindo {msg_id} pelo msg_id retornado por Enviar mensagem, Enviar para um grupo, Enviar para vários números ou Agendar mensagem. Por exemplo: https://wbiztool.com/api/v1/message/status/9817263/.

Exemplo rápido#

curl -X POST https://wbiztool.com/api/v1/message/status/9817263/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY"
  }'

Substitua 12345 e YOUR_API_KEY pelos seus próprios valores. Veja em Autenticação onde encontrá-los.

Parâmetros da requisição#

URL

msg_idintegerobrigatório

O ID da mensagem, como parte do caminho da URL. Ele precisa ser um número inteiro e pertencer ao espaço de trabalho da sua chave de API.

Corpo

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.

Usar o cliente oficial#

O cliente Python chama este endpoint para você.

Python
from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))

O cliente retorna os mesmos campos da API, então result["status"] é o estado da mensagem, não um indicador de sucesso. Erros de autenticação lançam requests.HTTPError; leia o motivo com e.response.json()["message"].

Resposta#

O endpoint retorna HTTP 200 com o estado atual da mensagem:

{
  "message": "Sent",
  "status": 1,
  "status_text": "Sent",
  "error": ""
}

Uma mensagem que falhou:

{
  "message": "Failed",
  "status": 2,
  "status_text": "Failed",
  "error": "Phone number invalid"
}
CampoTipoDescrição
statusintegerO código de status da mensagem. Veja a tabela abaixo.
status_textstringNome do status: Created, Sent, Failed, Cancelled ou Expired.
messagestringMesmo valor de status_text.
errorstring ou nullPor que a mensagem falhou. Sempre presente; vazio ("" ou null) quando não há erro.

Valores de status#

statusstatus_textSignificado
0CreatedNa fila ou agendada, aguardando envio.
1SentEnviada do seu número de WhatsApp.
2FailedNão pôde ser enviada, ou o envio foi interrompido. error informa o motivo. Se error for Sending was interrupted and may have been delivered. Check WhatsApp before resending., o destinatário pode já ter a mensagem, então não a reenvie automaticamente.
3CancelledCancelada antes de ser enviada, por exemplo com Cancelar mensagem.
4ExpiredNão foi enviada antes do prazo definido em expire_after_seconds.

Sent é o estado final de sucesso. Este endpoint não informa se a mensagem foi entregue no celular nem se foi lida.

Exemplos de valores de error para mensagens que falharam: Phone number invalid, Group not found, Image Url Error, File Url Error, Blocked Contact, File exceeds WhatsApp size limit (…), File type not supported, Sending was interrupted and may have been delivered. Check WhatsApp before resending.

Erros#

{
  "message": "Unknown message id",
  "status": 0,
  "status_text": "pending",
  "error": "Invalid message id"
}
MensagemComo corrigir
Unknown message idNão existe nenhuma mensagem com esse ID no espaço de trabalho da sua chave de API. Verifique o ID e se você está usando uma chave do mesmo espaço de trabalho.
Auth ErrorEnvie client_id e api_key. Um corpo JSON inválido (por exemplo, com uma vírgula sobrando no final) também retorna Auth Error.
Invalid Client IdEnvie client_id como número. Retornado com HTTP 403.
Auth Error: invalid api keyVerifique se a chave existe, não foi excluída e pertence a este client_id. Retornado com HTTP 400.

Dicas#

  • Prefira webhooks para atualizações em tempo real: informe webhook ao enviar a mensagem e o Wbiztool avisa você quando ela for enviada ou falhar, sem precisar consultar repetidamente. Mensagens canceladas e expiradas não disparam webhook, então verifique-as aqui.
  • Consultas periódicas: se você fizer polling, pare quando status deixar de ser 0. Deixe alguns segundos entre as verificações.
  • Muitas mensagens de uma vez: para verificar as mensagens de um dia inteiro, use Histórico de mensagens em vez de chamar este endpoint para cada ID.
  • Mensagens antigas são removidas: mensagens enviadas, com falha, canceladas e expiradas sem alterações por cerca de 90 dias retornam Unknown message id. O mesmo acontece com mensagens que ainda estão na fila 90 dias depois de criadas ou agendadas, em um número desconectado ou excluído.
  • Integrações antigas: POST /api/v1/msg_status/ com msg_id no corpo está obsoleto. Ele retorna os mesmos campos. Ele também aceita GET com client_id, api_key e msg_id na query string, o que expõe sua chave de API em URLs e logs. Migre para este endpoint.