whatsapp-delivery-check

name	whatsapp-delivery-check
description	Given a TimelinesAI message_uid, poll GET /messages/{uid}/status_history and return the Sent / Delivered / Read timeline. Use after a send to confirm a message actually reached the recipient's device, or to answer "did X receive Y" questions from the user.
env	{"TIMELINES_AI_API_KEY":"required"}

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.