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.
https://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"
}'import requests
msg_id = 9817263
response = requests.post(
f"https://wbiztool.com/api/v1/message/status/{msg_id}/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") == "Unknown message id":
print("No message with this ID in your workspace")
elif "status_text" not in result:
print("Request failed:", result.get("message", "no message in response"))
elif result["status"] == 1:
print("Sent")
elif result["status"] == 2:
print("Failed:", result["error"])
else:
print("Status:", result["status_text"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const msgId = 9817263;
const response = await fetch(`https://wbiztool.com/api/v1/message/status/${msgId}/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message === "Unknown message id") {
console.log("No message with this ID in your workspace");
} else if (!("status_text" in result)) {
console.error("Request failed:", result.message ?? "no message in response");
} else if (result.status === 1) {
console.log("Sent");
} else if (result.status === 2) {
console.log("Failed:", result.error);
} else {
console.log("Status:", result.status_text);
}<?php
$msgId = 9817263;
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
];
$ch = curl_init("https://wbiztool.com/api/v1/message/status/{$msgId}/");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') === 'Unknown message id') {
echo 'No message with this ID in your workspace';
} elseif (!isset($result['status_text'])) {
echo 'Request failed: ' . ($result['message'] ?? 'no message in response');
} elseif ($result['status'] === 1) {
echo 'Sent';
} elseif ($result['status'] === 2) {
echo 'Failed: ' . $result['error'];
} else {
echo 'Status: ' . $result['status_text'];
}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órioO 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órioSeu ID do Cliente da API, em Configurações → Chaves API.
api_keystringobrigatórioSua chave de API, na mesma página.
Usar o cliente oficial#
O cliente Python chama este endpoint para você.
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"
}
| Campo | Tipo | Descrição |
|---|---|---|
status | integer | O código de status da mensagem. Veja a tabela abaixo. |
status_text | string | Nome do status: Created, Sent, Failed, Cancelled ou Expired. |
message | string | Mesmo valor de status_text. |
error | string ou null | Por que a mensagem falhou. Sempre presente; vazio ("" ou null) quando não há erro. |
Valores de status#
status | status_text | Significado |
|---|---|---|
0 | Created | Na fila ou agendada, aguardando envio. |
1 | Sent | Enviada do seu número de WhatsApp. |
2 | Failed | Nã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. |
3 | Cancelled | Cancelada antes de ser enviada, por exemplo com Cancelar mensagem. |
4 | Expired | Nã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"
}
| Mensagem | Como corrigir |
|---|---|
Unknown message id | Nã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 Error | Envie 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 Id | Envie client_id como número. Retornado com HTTP 403. |
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. |
Dicas#
- Prefira webhooks para atualizações em tempo real: informe
webhookao 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
statusdeixar de ser0. 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/commsg_idno corpo está obsoleto. Ele retorna os mesmos campos. Ele também aceitaGETcomclient_id,api_keyemsg_idna query string, o que expõe sua chave de API em URLs e logs. Migre para este endpoint.
