Diagnosing Missing Delivery Receipts in Reach Messaging

The Problem: Delivery Receipts Not Arriving

When using Reach to send critical notifications, you expect delivery receipts to confirm messages reached recipient devices. If these receipts aren't appearing in your webhook callbacks or API responses, you're operating blind to message status.

Common Causes and Diagnostic Table

Symptom	Possible Cause	Diagnostic Check
No webhook callbacks received	Delivery receipts disabled in settings	Verify receipt toggle in dashboard
Webhook returns 500 error	Endpoint timeout or crash	Check server logs for 10s timeout
Status shows 'unknown'	Carrier doesn't support delivery confirm	Review carrier compatibility docs
API shows 'sent' only	Receipt opt-in not enabled per message	Check message-level delivery_status flag

Ordered Diagnostic Steps

1. Verify Dashboard Configuration
   Navigate to Reach dashboard > Settings > Delivery Receipts. Ensure the toggle is enabled for your webhook endpoint. Without this, no receipts will be generated regardless of message content. Run this check in your browser with admin access:

   curl -X GET https://api.reach.com/v1/receipts/settings
     -H "Authorization: Bearer YOUR_API_KEY"

   Expected response includes "enabled": true. If missing, enable via dashboard UI or API.
2. Test Webhook Endpoint Responsiveness
   Delivery receipts require your endpoint to respond within 10 seconds. Longer responses trigger exponential backoff retries that may exhaust after 3 attempts. From your server, test the exact webhook path Reach will call:

   curl -X POST https://yourdomain.com/webhook/reach
     -H "Content-Type: application/json"
     -d '{"test": true}'

   Your endpoint must return HTTP 200 within 10 seconds. Check server logs for timing. If your application performs database writes or external API calls, consider queuing them asynchronously.
3. Send Test Message with Receipt Request
   Create a message explicitly requesting delivery status:

   curl -X POST https://api.reach.com/v1/messages
     -H "Authorization: Bearer YOUR_API_KEY"
     -H "Content-Type: application/json"
     -d '{
       "to": "+15551234567",
       "body": "Test message",
       "delivery_receipt": true
     }'

   The API response should include a message_id. Query this message after 30 seconds:

   curl -X GET https://api.reach.com/v1/messages/{message_id}
     -H "Authorization: Bearer YOUR_API_KEY"

   Check if delivery_status field appears with value "delivered".
4. Inspect Webhook Delivery Logs
   In the Reach dashboard, navigate to Monitoring > Webhook Logs. Filter by your endpoint URL and recent timestamps. Look for:
   • HTTP 200 responses (success)
   • Retry attempts (indicates timeout or error)
   • Payload structure matching the receipt format
   If logs show 4xx/5xx responses, your endpoint is rejecting valid payloads. Common issues include missing authentication headers or malformed JSON parsing.

Fixes Based on Findings

Fix: Enable Delivery Receipts Globally

If dashboard settings show receipts disabled, toggle them on and save. For existing integrations, this retroactively enables receipts for all future messages.

Fix: Optimize Webhook Response Time

Implement immediate 200 response with background processing:

// Express.js example
app.post('/webhook/reach', async (req, res) {
  // Immediately acknowledge
  res.status(200).send('OK');
  
  // Process asynchronously
  process.nextTick(() => handleReceipt(req.body));
});

Fix: Handle Carrier Limitations

For international carriers that don't support delivery confirmation, implement fallback tracking:

if (message.delivery_status === 'unknown' && message.sent_to_carrier_supports_receipt === false) {
  // Use read receipts or delivery window
  scheduleStatusCheck(message.id, 5 * 60 * 1000); // 5 minutes
}

Escalation Criteria

Contact Reach support if:

• All diagnostic steps pass but receipts still don't arrive after 15 minutes
• Webhook logs show successful delivery but your server never receives callbacks
• API consistently returns errors when querying message status

When escalating, provide:

1. Specific message IDs tested
2. Timestamps of sent messages
3. Webhook endpoint URL
4. Screenshots of webhook delivery logs

Verification Checklist

After implementing fixes, verify with this 3-step process:

1. Send a test message with delivery_receipt: true
2. Confirm webhook callback arrives within 60 seconds
3. Query API message endpoint and verify delivery_status field populates correctly

Limitation: Delivery timing varies by carrier and may experience delays of several minutes. Receipt status of 'unknown' for international messages is expected behavior when carriers don't support confirmation.