Troubleshooting#

Solutions to common issues and debugging tips.

Quick Diagnostics#

Check Connection Health#

query {
  platformConnection(id: "pc_abc123") {
    id
    name
    health {
      status
      lastCheckedAt
      errorMessage
    }
  }
}

Test Connection#

mutation {
  testPlatformConnection(id: "pc_abc123") {
    success
    message
    health {
      status
      errorMessage
    }
  }
}

View Recent Events#

query {
  events(
    filters: { status: { equals: "failed" } }
    first: 10
    orderBy: { field: CREATED_AT, direction: DESC }
  ) {
    edges {
      node {
        id
        eventType
        status
        payload
        createdAt
      }
    }
  }
}

Common Issues#

Messages Not Sending#

Symptoms: sendMessage returns success but messages don’t arrive.

Possible Causes:

  1. Invalid recipient

    • Check external ID format
    • Verify recipient has the app installed
    • Ensure recipient hasn’t blocked you

  2. Platform rate limit

    • Check platform-specific quotas
    • Implement message queuing

  3. Token expired

    • For OAuth platforms: Reconnect
    • For token platforms: Update credentials

  4. Outside messaging window

    • WhatsApp/Instagram/Facebook: Use templates outside 24-hour window

Debugging:

query {
  event(id: "evt_abc123") {
    id
    status
    payload
    childEvents {
      eventType  # Check for failed status events
      payload
    }
  }
}

Messages Not Received#

Symptoms: Users send messages but they don’t appear in Outeract.

Possible Causes:

  1. Webhook not configured

    • Verify webhook URL in platform settings
    • Check webhook is verified

  2. Signature verification failing

    • Verify webhook secret matches
    • Check signing key/app secret

  3. Firewall blocking

    • Allow platform IPs
    • Ensure HTTPS is properly configured

  4. Connection inactive

    • Check connection health
    • Verify credentials are valid

Debugging:

# Test webhook endpoint
curl -X POST https://api.outeract.com/webhooks/test \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

OAuth Connection Failed#

Symptoms: OAuth flow completes but connection doesn’t work.

Possible Causes:

  1. Missing permissions

    • Re-authorize with required scopes
    • Check permission grants in platform dashboard

  2. Token exchange failed

    • Check app credentials in environment
    • Verify redirect URI matches

  3. Page/Account not linked

    • Instagram: Ensure linked to Facebook Page
    • WhatsApp: Verify Business Account setup

Solution:

  1. Delete the connection
  2. Re-run OAuth flow
  3. Ensure all permissions are granted

Webhook Verification Failed#

Symptoms: Platform can’t verify webhook URL.

Platform-Specific Solutions:

Meta (WhatsApp/Instagram/Facebook):

  • Verify VERIFY_TOKEN matches
  • Check URL returns challenge parameter
  • Ensure HTTPS certificate is valid

Slack:

  • Verify signing secret
  • Return challenge in response body

Telegram:

  • Use HTTPS URL
  • Certificate must be valid (or use setWebhook with certificate)

File Upload Failed#

Symptoms: Files fail to upload or send.

Possible Causes:

  1. File too large

    • Check platform limits (varies by platform)
    • WhatsApp: 100MB documents, 16MB media
    • Telegram: 50MB

  2. Unsupported format

    • Check platform-supported MIME types
    • Convert to supported format

  3. Storage error

    • Check storage configuration
    • Verify permissions

Solution:

mutation {
  uploadFile(file: $file) {
    id
    filename
    mimeType
    sizeBytes
    # Check these fields for issues
  }
}

Rate Limit Errors#

Symptoms: 429 errors or RATE_LIMITED code.

Solutions:

  1. API rate limit

    • Implement exponential backoff
    • Queue requests
    • Upgrade plan

  2. Platform rate limit

    • Check platform-specific limits
    • Implement per-platform queuing
    • Request quota increase

Example backoff:

import time

for attempt in range(5):
    try:
        result = api_call()
        break
    except RateLimitError:
        time.sleep(2 ** attempt)

Platform-Specific Issues#

WhatsApp#

“Phone number not registered”

  • Verify E.164 format: +14155551234
  • Recipient must have WhatsApp installed

“Template not found”

  • Template must be approved in Meta Business Manager
  • Check template name and language code

“Quality rating low”

  • Review blocked/reported messages
  • Improve message relevance

Telegram#

“Bot token invalid”

  • Get new token from @BotFather
  • Check for extra spaces

“Webhook not working”

  • Must use HTTPS
  • Run setWebhook API call

Slack#

“not_in_channel”

  • Invite bot with /invite @BotName
  • Or add chat:write.public scope

“invalid_auth”

  • Check bot token (starts with xoxb-)
  • Reinstall app to workspace

Instagram#

“Cannot message user”

  • User must have messaged you first
  • Check 24-hour window

Debugging Tools#

Enable Debug Mode#

mutation {
  updateApplication(
    config: { debug_responses_enabled: "enabled" }
  ) {
    id
    config
  }
}

Check Webhook Logs#

query {
  webhookDeliveryLogs(first: 20) {
    edges {
      node {
        id
        status
        statusCode
        requestBody
        responseBody
        errorMessage
        createdAt
      }
    }
  }
}

Test Webhook Endpoint#

# Using webhook.site
# 1. Go to https://webhook.site
# 2. Copy your unique URL
# 3. Create test subscription pointing to it
# 4. Trigger an event and inspect payload

Local Development#

# Using ngrok
ngrok http 3000

# Use the HTTPS URL for webhooks
# https://abc123.ngrok.io/webhooks

Getting Help#

Check Status#

Support#

Community#

Backward Rate Limits FAQ Forward