Message status

Every outgoing message goes through a lifecycle of status updates. wakit tracks these automatically via WhatsApp webhooks.

Status flow

pending → sent → delivered → read
                           → failed

Status fields

The status column on the messages table is a JSON object with timestamps:

{
  "pending": "2026-05-06T03:39:23+00:00",
  "sent": "2026-05-06T03:39:24+00:00",
  "delivered": "2026-05-06T03:39:25+00:00",
  "read": "2026-05-06T03:39:30+00:00"
}

Status	Meaning
`pending`	Message inserted in database, not yet sent
`sent`	WhatsApp Cloud API accepted the message
`delivered`	Message delivered to the recipient's device
`read`	Recipient opened/read the message
`failed`	Message could not be sent (includes error details)

Failed messages

When a message fails, the status object includes a failed timestamp and an errors array with details from Meta:

{
  "pending": "2026-05-06T03:39:23+00:00",
  "failed": "2026-05-06T03:39:24+00:00",
  "errors": [
    {
      "error": {
        "code": 131042,
        "type": "OAuthException",
        "message": "(#131042) Business eligibility payment issue",
        "error_data": {
          "details": "Payment method is not set up or has been removed",
          "messaging_product": "whatsapp"
        },
        "fbtrace_id": "A1NdQYqM-yB..."
      }
    }
  ]
}

Common error codes

Code	Name	Description
100	Invalid parameter	Missing or malformed parameter (e.g. template variable)
131042	Payment issue	Business hasn't set up or has removed their payment method
131047	Re-engagement	Trying to send a free-form message outside the 24h service window
131051	Unsupported message type	The message type is not supported for this recipient
130429	Rate limit	Too many messages sent — throughput limit reached
132000	Template params mismatch	Number of template variables doesn't match the template
132001	Template not found	Template name doesn't exist in the specified language
132015	Template paused	Template has been paused by Meta
133004	Server unavailable	Meta servers temporarily unavailable
368	Account restricted	Account temporarily banned for policy violations
80007	WABA rate limit	WhatsApp Business Account rate limit reached

For the full list, see the Meta WhatsApp Cloud API error codes reference.

Query by status

Messages that failed to send:

const { data } = await supabase
  .from('messages')
  .select('*')
  .eq('direction', 'outgoing')
  .not('status->failed', 'is', null);

Unread outgoing messages:

const { data } = await supabase
  .from('messages')
  .select('*')
  .eq('direction', 'outgoing')
  .is('status->read', null)
  .not('status->delivered', 'is', null);

Real-time status updates

supabase
  .channel('status')
  .on(
    'postgres_changes',
    {
      event: 'UPDATE',
      schema: 'public',
      table: 'messages',
      filter: `organization_id=eq.${orgId}`,
    },
    (payload) => {
      console.log('Status update:', payload.new.status);
    }
  )
  .subscribe();

Webhooks

Configure a webhook for messages / update to get notified on your server when status changes. See Webhooks.