Saltar al contenido
Wbiztool

API de mensajería

API de estado de mensajes

Comprueba si un mensaje que enviaste a través de la API sigue en cola, ya se envió o falló. Úsala para confirmar que los mensajes importantes salieron y para averiguar por qué alguno no lo hizo.

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

Cuerpo: JSON o campos de formulario

Pon el ID del mensaje en la URL, sustituyendo {msg_id} por el msg_id que devolvió Enviar mensaje, Enviar a un grupo, Enviar a varios números o Programar mensaje. Por ejemplo: https://wbiztool.com/api/v1/message/status/9817263/.

Ejemplo 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"
  }'

Sustituye 12345 y YOUR_API_KEY por tus propios valores. Consulta Autenticación para saber dónde encontrarlos.

Parámetros de la solicitud#

URL

msg_idintegerobligatorio

El ID del mensaje, como parte de la ruta de la URL. Debe ser un número entero y pertenecer al espacio de trabajo de tu clave API.

Cuerpo

client_idintegerobligatorio

Tu ID de cliente de la API, de Configuración → Claves API.

api_keystringobligatorio

Tu clave API, de esa misma página.

Usar el cliente oficial#

El cliente de Python llama a este endpoint por ti.

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"))

El cliente devuelve los mismos campos que la API, así que result["status"] es el estado del mensaje, no un indicador de éxito. Los errores de autenticación lanzan requests.HTTPError; lee el motivo con e.response.json()["message"].

Respuesta#

El endpoint devuelve HTTP 200 con el estado actual del mensaje:

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

Un mensaje que falló:

{
  "message": "Failed",
  "status": 2,
  "status_text": "Failed",
  "error": "Phone number invalid"
}
CampoTipoDescripción
statusintegerEl código de estado del mensaje. Consulta la tabla de abajo.
status_textstringNombre del estado: Created, Sent, Failed, Cancelled o Expired.
messagestringEl mismo valor que status_text.
errorstring or nullPor qué falló el mensaje. Siempre está presente; vacío ("" o null) cuando no hay error.

Valores de estado#

statusstatus_textSignificado
0CreatedEn cola o programado, esperando a enviarse.
1SentEnviado desde tu número de WhatsApp.
2FailedNo se pudo enviar o el envío se interrumpió. error indica el motivo. Si error es Sending was interrupted and may have been delivered. Check WhatsApp before resending., es posible que el destinatario ya tenga el mensaje, así que no lo reenvíes automáticamente.
3CancelledCancelado antes de enviarse, por ejemplo con Cancelar mensaje.
4ExpiredNo se envió antes de su plazo expire_after_seconds.

Sent es el estado final de éxito. Este endpoint no indica si el mensaje se entregó en el teléfono ni si se leyó.

Ejemplos de valores de error en mensajes fallidos: 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.

Errores#

{
  "message": "Unknown message id",
  "status": 0,
  "status_text": "pending",
  "error": "Invalid message id"
}
MensajeCómo solucionarlo
Unknown message idNo existe ningún mensaje con ese ID en el espacio de trabajo de tu clave API. Revisa el ID y comprueba que usas una clave del mismo espacio de trabajo.
Auth ErrorEnvía client_id y api_key. Un cuerpo JSON no válido (por ejemplo, con una coma final) también devuelve Auth Error.
Invalid Client IdEnvía client_id como número. Se devuelve con HTTP 403.
Auth Error: invalid api keyComprueba que la clave existe, que no se ha eliminado y que pertenece a este client_id. Se devuelve con HTTP 400.

Consejos#

  • Para actualizaciones en tiempo real, mejor webhooks: pasa webhook al enviar el mensaje y Wbiztool te avisará cuando se envíe o falle, sin que tengas que consultar periódicamente. Los mensajes cancelados y caducados no activan ningún webhook, así que consúltalos aquí.
  • Consultas periódicas: si consultas periódicamente, para en cuanto status deje de ser 0. Deja unos segundos entre consultas.
  • Muchos mensajes a la vez: para revisar los mensajes de todo un día, usa Historial de mensajes en lugar de llamar a este endpoint para cada ID.
  • Los mensajes antiguos se purgan: los mensajes enviados, fallidos, cancelados y caducados sin cambios durante unos 90 días devuelven Unknown message id. Lo mismo ocurre con los mensajes que siguen en cola 90 días después de crearse o de su hora programada, en un número desconectado o eliminado.
  • Integraciones antiguas: POST /api/v1/msg_status/ con msg_id en el cuerpo está obsoleto. Devuelve los mismos campos. También acepta GET con client_id, api_key y msg_id en la query string, lo que expone tu clave API en URL y registros. Cámbiate a este endpoint.