Track message delivery signals and status

tyntec’s WhatsApp Business API sends notifications to inform the message status between the company and the user to customers. When a message is sent successfully, you receive a notification when the message is sent, delivered, and read.

In this tutorial, you will learn:

The order of these notifications in the API may not reflect the actual timing of the message status. To determine the timing, view the timestamp.

Notification Types

Name	Description	WhatsApp Mobile Equivalent
sent	The server received a message sent by your business. To receive notifications for sent messages, set the sent_status setting to true in the application settings. Sent status notification is disabled by default.	One checkmark
delivered	Message sent by your business was delivered to the user’s device.	Two checkmarks
read	Message sent by your business was read by the user read notifications will only be available for those users that have read receipts enabled. For users that do not have it enabled, you will only receive the delivered notification.	Two blue checkmarks
failed	Message sent by your business was unable to send. A reason for the failure will be included in the callback.	Red error triangle
deleted	The user has deleted the message sent to your business.	The message is replaced in WhatsApp mobile with a note reading, “This message was deleted.”

ℹ️ For the status to be read, it must have been delivered. In scenarios such as when a user is on the chat screen, and a message arrives, the message is delivered and read simultaneously. In this case, the delivery notification will not be sent back, as it is implied that a message has been delivered if it has been read.

How to query message status

You can query your message status directly on tyntec’s WhatsApp API with the following endpoint:

Method	Operation
GET	`https://api.tyntec.com/chat-api/v2/messages/{message-id}/status`

ℹ️ You can also check how to mark user messages as ‘Read’ in our API reference here

Looking up the message status might be interesting if you haven’t set up a notification webhook or manually query the status.

The following example explains how you can check the message status:

curl https://api.tyntec.com/conversations/v3/messages/77185196-664a-43ec-b14a-fe97036c697f/status \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

Below will be the returning code if your message did not go through:

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
 "status": "failed"
}

ℹ️ If your message failed to go through, you can check the history in the next section — Querying the Message History.

How to query message history

You can query your message history directly on tyntec’s WhatsApp API.

curl https://api.tyntec.com/conversations/v3/messages/77185196-664a-43ec-b14a-fe97036c697f/events \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

This code will trigger a response such as:

{
    "messageId": "d5e8278d-db38-403a-8df3-2f9169040aa0",
    "events": [
        {
            "timestamp": "2021-04-07T07:01:18.691Z",
            "event": "MessageStatus::accepted"
        },
        {
            "channel": "whatsapp",
            "timestamp": "2021-04-07T07:01:19.014Z",
            "event": "MessageStatus::dispatched"
        },
        {
            "channel": "whatsapp",
            "timestamp": "2021-04-07T07:01:19.064Z",
            "event": "MessageStatus::channelFailed",
            "details": {
                "code": "whatsapp::error::470",
                "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
            }
        },
        {
            "timestamp": "2021-04-07T07:01:19.464Z",
            "event": "MessageStatus::failed",
            "details": {
                "code": "tyntec::error:noFurtherChannelAvailable",
                "message": "No further channel after Channel[whatsapp] available"
            }
        }
    ]
}

Companies can mark messages received by their users as “read”, indicating that the message was seen by an agent/chatbot of the company, boosting engagement transparency. This is shown as the double checkmark that is already known in the WhatsApp user base.

Whenever you receive an inbound message from the user:

{
    "messageId": "ABEGSRcolTdUAhCDTh0Viu2YwDb751d6V33t",
    "channel": "whatsapp",
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "receivedAt": "2019-11-19T15:30:25Z",
    "content": {
        "contentType": "text",
        "text": "Peng",
        "media": null,
        "location": null
    },
    "event": "MoMessage",
    "whatsapp": {
        "senderName": "Peter Daum @ tyntec"
    },
    "timestamp": "2019-11-19T15:30:25Z"

Take the message-id – in this case, ABEGSRcolTdUAhCDTh0Viu2YwDb751d6V33t – and execute.

PUT

https://api.tyntec.com/conversations/v3/messages/ABEGSRcolTdUAhCDTh0Viu2YwDb751d6V33t

with the json payload.

{
               "status" : "read"
}

ℹ️ You can also check how to mark user messages as ‘Read’ in our API reference here.

Channel | WhatsApp Business

Message Tracking

Track message delivery signals and status

Notification Types

How to query message status

How to query message history