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 is pending - sent to WhatsApp server, awaiting acknowledgment or delivery confirmation. What this means:
  • The message has been sent to WhatsApp servers
  • For messages with delivery confirmation: awaiting delivery confirmation
  • For messages without delivery confirmation: sent to WhatsApp but no delivery confirmation received

​
Delivered (Individual Chat)

ack: 2
Message was sent to WhatsApp servers and delivered to the recipient’s device. What this means:
  • For individual chats: The message has been delivered to the recipient’s device
  • For group chats: The message has been delivered to at least one participant (but not necessarily all). Check delivery_info.delivered_count for the exact number of participants who received it

​
Delivered (Group Chat - All Participants)

ack: 3
Message was delivered to all participants in the group. What this means: All group participants have received the message on their devices. For individual chats, this status is typically not used (ack: 2 is sufficient).

​
Read by Recipient

ack: 4
Message was read by the recipient (blue double tick). What this means:
  • For individual chats: The message has been read by the recipient
  • For group chats: At least one participant has read the message. Check delivery_info.read_count for the exact number of participants who have read it
Note: Read receipts require both sender and recipient to have read receipts enabled in their WhatsApp privacy settings.

​
Read by All (Group Chat)

ack: 5
Message was read by all participants in the group (blue double tick). What this means: The message has been read by all participants of the group chat. This status is typically only used in group chats.

​
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

​
Read Receipts Not Showing (ack stays at 2 or 3)

  • Read receipts depend on the recipient’s privacy settings
  • Some recipients may have read receipts disabled globally
  • In group chats, read receipts require participants to have them enabled
  • The ack value will only advance to 4 or 5 if read receipts are enabled and the message is actually read
  • For group chats, check delivery_info.read_count to see how many participants have read the message even if ack hasn’t advanced

​
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.