Whatsapp Delivery Check

WhatsApp delivery check

Check whether a previously-sent WhatsApp message was actually delivered. TimelinesAI's POST /messages returns a message_uid that is a receipt, not a delivery confirmation — the real delivery status comes from GET /messages/{uid}/status_history.

When to use

• After a transactional send, confirm delivery before telling the user "message sent".
• Answer "did John actually receive the invoice I sent this morning?" from the human user.
• Retroactively check whether an old message was read.
• Aggregate delivery stats across many messages for response-time analytics.

Invocation payload

{
  "message_uid": "a8f9b2c1-..."
}

Implementation

curl -sS -H "Authorization: Bearer $TIMELINES_AI_API_KEY" \
  "https://app.timelines.ai/integrations/api/messages/$MESSAGE_UID/status_history"

Response shape

{
  "status": "ok",
  "data": [
    {"status": "Sent",      "timestamp": "2026-04-12 12:28:40 +0000"},
    {"status": "Delivered", "timestamp": "2026-04-12 12:28:41 +0000"},
    {"status": "Read",      "timestamp": "2026-04-12 12:31:15 +0000"}
  ]
}

The data array is in chronological order. Each entry is a state transition.

Interpretation

| Latest status | What it means | |---|---| | Sent | TimelinesAI accepted the send and pushed it to WhatsApp. The recipient's device has NOT confirmed delivery yet. | | Delivered | The recipient's device has received the message. They haven't opened the chat yet. | | Read | The recipient opened the chat (with read receipts enabled on their end). They've seen it. |

Typical timing on an active number: Sent → Delivered within ~1 second. Delivered → Read can take minutes or hours depending on when the recipient opens their phone. For customers with read receipts disabled, you'll never see Read — treat Delivered as the strongest signal you'll get.

Return value

Return the full status history as structured data so the caller can decide what to do:

{
  "message_uid": "a8f9b2c1-...",
  "latest_status": "Delivered",
  "latest_timestamp": "2026-04-12 12:28:41 +0000",
  "sent_at": "2026-04-12 12:28:40 +0000",
  "delivered_at": "2026-04-12 12:28:41 +0000",
  "read_at": null
}

For a natural-language answer to the human user:

> "Yes — your invoice message to John was delivered at 12:28 UTC this morning, but he hasn't opened the chat yet (or has read receipts disabled)."

Failure modes

| Response | Meaning | What to do | |---|---|---| | {"status":"error","message":"Message uid ... not found"} | Typo in the uid, or the uid belongs to a different workspace | Don't retry; check the uid | | {"status":"error","message":"Not authenticated"} | Wrong token | Check $TIMELINES_AI_API_KEY | | Empty data: [] array | Send was accepted but no state transition has landed yet | Wait a second and retry once |

What this skill deliberately does NOT do

• Does not poll continuously — call it once per user question. For real-time delivery tracking, poll on a timer from a different process.
• Does not interpret "missing Read status" as "unread" — many users disable read receipts, which means Read never arrives even if they've seen the message. Only assert Read is positive evidence, not not Read as negative evidence.
• Does not correlate across workspaces — UIDs are workspace-local. If sender and recipient are in different TimelinesAI workspaces, the message_uid the sender got is NOT the same UID the recipient's workspace assigned. See docs/state-persistence.md for cross-workspace correlation patterns.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: InitechSoftware
• Source: InitechSoftware/openclaw-whatsapp-skills
• License: MIT
• Homepage: https://timelines.ai/guides/openclaw-whatsapp-skills

Install and usage instructions live in the source repository linked above.