WhatsApp Business Integration#

Connect your WhatsApp Business account via Meta OAuth for automated messaging with full feature support.

Overview#

Features#

• Send and receive text messages
• Rich media (images, videos, documents, audio)
• Message read receipts
• Typing indicators
• Message status tracking (sent, delivered, read)
• Interactive buttons and lists
• Message templates
• Automatic token management

Prerequisites#

• WhatsApp Business Account (not personal WhatsApp)
• Facebook Business Manager account
• Business verified with Meta

Don't have these? Follow Meta's [WhatsApp Business setup guide](https://business.facebook.com/wa/manage/home/).

Setup Guide#

Step 1: Connect via OAuth#

1. In Outeract console, go to Connections → Add Connection
2. Select WhatsApp Business
3. Click Connect with Meta
4. Log in to Facebook
5. Select your WhatsApp Business Account
6. Authorize Outeract to manage your WhatsApp messages
7. Connection is created automatically

Step 2: Webhook Configuration#

WhatsApp uses a shared webhook architecture:

• One webhook URL handles all WhatsApp connections
• Routing is automatic based on Business Account ID
• No per-connection webhook configuration needed

The shared webhook is automatically configured when your first WhatsApp connection is created.

Step 3: Verify Connection#

mutation {
  testPlatformConnection(id: "pc_whatsapp_123") {
    success
    message
    health {
      status
      lastCheckedAt
    }
  }
}

Sending Messages#

Text Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    toExternalId: "+14155551234"
    message: "Hello! Thanks for contacting us."
  ) {
    id
    status {
      success
      externalMessageId
    }
  }
}

Image Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    toExternalId: "+14155551234"
    message: "Check out our new product!"
    fileIds: ["file_xyz789"]
  ) {
    id
  }
}

Document Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    toExternalId: "+14155551234"
    message: "Here's your invoice"
    fileIds: ["file_invoice123"]
  ) {
    id
  }
}

Supported Message Types#

External ID Format#

WhatsApp uses E.164 phone numbers:

Always include the + prefix and country code.

Read Receipts & Typing#

Mark as Read#

mutation {
  markMessageAsRead(
    platformConnectionId: "pc_whatsapp_123"
    externalMessageId: "wamid.xyz123"
  ) {
    success
  }
}

Send Typing Indicator#

mutation {
  sendTypingIndicator(
    platformConnectionId: "pc_whatsapp_123"
    toExternalId: "+14155551234"
  ) {
    success
  }
}

Message Status Tracking#

Messages go through these statuses:

Query message status:

query {
  event(id: "evt_abc123") {
    id
    payload
    childEvents {
      id
      eventType  # message.delivered, message.read
      createdAt
    }
  }
}

24-Hour Messaging Window#

WhatsApp enforces a 24-hour messaging window:

• Inside window: Send any message type freely
• Outside window: Must use pre-approved templates

The window opens when a user messages you and closes 24 hours after their last message.

Message Templates#

For messages outside the 24-hour window:

mutation {
  sendTemplateMessage(
    platformConnectionId: "pc_whatsapp_123"
    toExternalId: "+14155551234"
    templateName: "order_confirmation"
    languageCode: "en_US"
    parameters: [
      { type: "body", index: 1, text: "John" },
      { type: "body", index: 2, text: "#12345" }
    ]
  ) {
    id
  }
}

Templates must be pre-approved in Meta Business Manager.

Rate Limits#

Message limits depend on your WhatsApp Business tier:

Outeract handles rate limiting automatically.

Webhook Events#

Inbound Message#

{
  "event_id": "evt_abc123",
  "event_type": "message.inbound",
  "payload": {
    "message": {
      "text": "Hello!",
      "role": "user"
    },
    "platform": "whatsapp",
    "external_message_id": "wamid.xyz123"
  },
  "edges": {
    "sent_by": {
      "external_id": "+14155559999"
    }
  }
}

Message Status Update#

{
  "event_id": "evt_xyz789",
  "event_type": "message.delivered",
  "payload": {
    "status": "delivered",
    "external_message_id": "wamid.abc456"
  }
}

WhatsApp Business Policies#

Permitted Use#

• Customer support
• Transaction notifications
• Appointment reminders
• Order updates

Prohibited Content#

• Spam or bulk messaging without consent
• Promotional messages outside templates
• Automated messages pretending to be human
• Adult, gambling, or sensitive content

See WhatsApp Business Policy for full guidelines.

Troubleshooting#

“Phone number not registered”#

• Recipient must have WhatsApp installed
• Verify phone number is correct E.164 format
• Check if number is blocked

“Outside 24-hour window”#

• Use a message template instead
• Templates must be pre-approved in Meta Business Manager

“Rate limit exceeded”#

• Check your tier in Meta Business Manager
• Messages will queue and retry automatically
• Upgrade tier for higher limits

“Invalid phone number”#

• Ensure E.164 format (+ prefix)
• Include country code
• No spaces or formatting

“Token expired”#

• OAuth tokens auto-refresh
• If issues persist, reconnect via OAuth

Security#

WhatsApp webhook signatures use HMAC-SHA256:

• Signature in X-Hub-Signature-256 header
• Validated against your App Secret
• Invalid signatures are rejected

Resources#

• Meta Business Manager
• WhatsApp Business API Documentation
• WhatsApp Business Policy
• Message Template Guidelines