Skip to main content

​
Overview

WhatsApp uses acknowledgment (ACK) statuses to indicate the delivery and read status of messages. Periskope displays these statuses using visual indicators to help you understand the current state of your messages. Important Notes:
  • ACK values are monotonic - they only increase (never decrease) once a message is sent
  • For group chats, check the delivery_info object in the message payload for detailed participant-level delivery (delivered_count) and read (read_count) statistics
  • The ACK status reflects the highest acknowledgment level achieved so far

​
Message Status Types

​
Message Failed

ack: -1
The message has failed to be sent. This indicates a delivery failure. What to do: Please retry sending the message or restart the phone connection.

​
Pending Send

ack: 0
The message is not sent yet. It’s queued and waiting to be sent to the WhatsApp server. What this means: The message is in your outbox and will be sent when the connection is available.

​
Sent to WhatsApp

ack: 1
Message has been sent to the WhatsApp servers, BUT is awaiting confirmation from WhatsApp What this means:
  • Messages typically should not be in the 1 state for more than a couple of seconds. If it is, please reset the connection and scan the QR again

​
Delivered to WhatsApp

ack: 2
Message was delivered to the WhatsApp servers, but is awaiting delivery confirmation from all recipients What this means:
  • For individual chats: Awaiting delivery confirmation from the recipient
  • For group chats: The message has been delivered to at least one participant (but not necessarily all), but awaiting delivery confirmation from the rest. Check delivery_info.delivered_count for the exact number of participants who received it

​
Delivered to all recipients

ack: 3
Message was delivered to all recipients What this means: For private chats, it was delivered to the recipient. For group chats, all group participants have received the message on their devices

​
Read by all

ack: 4 or 5
Message was read (or played in case of audio/video messages) by all the recipients (blue double tick). What this means:
  • For individual chats: The message has been read by the recipient. This status will typically appear only if the recipient has read receipts enabled in their WhatsApp privacy settings.

​
Understanding Group Chat Delivery

For group chats, the ack value provides a summary status, but the delivery_info object in the message payload contains detailed statistics:
  • delivered_count: Number of participants who have received the message
  • read_count: Number of participants who have read the message
Example:
  • A group with 10 participants might have ack: 2 (delivered to at least one) but delivery_info.delivered_count: 7 (delivered to 7 participants)
  • The ack value will increase to 3 only when all participants have received it

​
Troubleshooting

​
Message Stuck at Status 0 or 1

  • Check your phone connection status
  • Try restarting your phone on Periskope
  • Ensure that WhatsApp on your phone is updated to the latest version
  • Verify your internet connection is stable

​
Message Failed (Status -1)

  • Ensure that WhatsApp on your phone is updated to the latest version
  • Verify the recipient’s phone number is correct and not formatted incorrectly
  • Check if the recipient has blocked your number
  • Try restarting your phone on Periskope
  • For group chats, verify the group still exists and your number hasn’t been removed

​
ACK Status Not Advancing

  • ACK values are monotonic (they never decrease)
  • If a message shows ack: 2 for a long time, it may mean:
    • The recipient hasn’t read it yet (for individual chats)
    • Not all group participants have read it (for group chats)
    • Read receipts are disabled
  • Network issues or WhatsApp server delays can also cause status updates to be delayed

​
API Integration

When integrating with Periskope’s API, these status codes are returned as integers in the message object’s ack field. For group chats, also check the delivery_info object: 
{
  "ack": 2,
  "delivery_info": {
      "read": {
          "[email protected]": 1737976090690
      },
      "pending": [],
      "delivered": {
          "[email protected]": 1737976082277
      },
      "read_count": 1,
      "delivered_count": 1
  }
}
You can use these values to build custom notification systems or delivery tracking in your applications.

​
Webhook Integration

You can track acknowledgment status changes in real-time using the message.ack.updated webhook event, which fires whenever a message’s acknowledgment status changes. The webhook payload will include both the ack value and, for group chats, the updated delivery_info with current counts.