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"
            }
        }
    ]
}

How to mark user messages as "Read"

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.