Delivery Receipts & Message Status

When you send a message via InstaMessage, we assign it a message_id and track its progress through various states (queued, sent, delivered, failed, read).

There are two ways to track message outcomes:

1. Webhooks – real-time push notifications to your server.
2. Message Status API – on-demand lookup by message_id (useful if a webhook was missed).

Every outbound message goes through a lifecycle:

• queued – accepted by InstaMessage and queued for sending
• sent – handed off to the upstream provider / channel
• delivered – confirmed as delivered (where supported)
• failed – failed to deliver (with optional error information)
• read – the end-user has read the message (channels that support read receipts, e.g. WhatsApp and RCS)

Different channels support different levels of detail. For example:

• SMS – typically supports queued, sent, delivered, failed
• WhatsApp – supports queued, sent, delivered, failed, and read (via status_detail / has_been_read)
• Messenger – supports delivery and read receipts where available
• RCS – supports queued, sent, delivered, failed, and read

For real-time updates, set up webhooks using the Webhook Quick-Start.

Webhooks are best-effort:
If your webhook endpoint is unavailable or does not respond with 200 OK, the message.status event will not be retried and may be missed.

You can always retrieve the latest status using the Message Status API below.

Delivery status events are sent when a message’s status changes.

• You may receive multiple message.status events for the same message.
• Each status transition is sent at most once.
• For WhatsApp, you will typically see delivered first, and then read later (if it gets read).

{
  "event_type": "message.status",
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "whatsapp",
  "to": "+447123456789",
  "status": "delivered",
  "timestamp": "2026-01-14T12:03:11Z"
}

{
  "event_type": "message.status",
  "message_id": "abc123XYZ789def",
  "conversation_id": "conv456ABC123",
  "channel": "whatsapp",
  "to": "+447123456789",
  "status": "read",
  "timestamp": "2026-01-14T12:10:04Z"
}

Use this endpoint to fetch the latest status of a single message by its message_id.

GET https://api.instamessage.co.uk/v1/messages/{message_id}

All requests must include your API key:

Authorization: Bearer YOUR_API_KEY

curl -X GET "https://api.instamessage.co.uk/v1/messages/msg_67890" \
  -H "Authorization: Bearer $IM_API_KEY"

{
  "message_id": "abc123XYZ789def",
  "channel": "sms",
  "contact": {
    "id": "contact_123",
    "name": "John Doe",
    "tel": "+447123456789"
  },
  "content": {
    "type": "text",
    "text": "Your delivery is on its way."
  },
  "created_at": "2026-01-14T12:02:10Z",
  "scheduled_at": null,
  "sent_at": "2026-01-14T12:02:12Z"
}

• message_id is the message identifier (this is the ID you also see in webhook payloads as message_id).
• contact.tel is the recipient phone number.
• content.type describes the message payload (e.g. text, template, etc.).
• Delivery status reflects the latest known state of the message.
• Webhooks remain the preferred source for real-time updates.

Statuses can include:

• queued
• sent
• delivered
• failed
• read (where supported, e.g. WhatsApp)

Practical guidance: treat delivered and failed as terminal outcomes for most channels. For WhatsApp, read may occur after delivered (but will not occur if the message is never opened).

{
  "code": 4002,
  "message": "Message not found"
}

  "code": 4001,
  "message": "Message ID not specified"
}

Authentication errors (missing/invalid API key) return standard 401/403 responses.

The Message Status API is designed to complement webhooks:

• Use webhooks (message.status) for real-time updates.

• Use Message Status when:

  • Your webhook endpoint was temporarily down

  • You want to reconcile status in a batch job

  • You need to manually inspect a specific message_id

A common pattern:

1. Send a message and store the message_id from the Send a Message response.

2. Receive message.status webhooks to update your internal records in real-time.

3. Call:

GET /v1/messages/{message_id}

if a webhook was missed or you want to verify the latest status on demand.

• Learn how to receive real-time events → Webhook Quick-Start
• Learn how to send messages → Send a Message
• Start with SMS → Getting Started – SMS
• Start with WhatsApp → Getting Started – WhatsApp
• Start with RCS → Getting Started – RCS