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#

Open the connection in the console and run a health check. It reports whether the connection is valid, a summary message, and the per-test results with the time of the last check.

Sending Messages#

Text Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    recipientUserId: "user-uuid"
    message: "Hello! Thanks for contacting us."
  ) {
    id
    eventTypeName
  }
}

Image Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    recipientUserId: "user-uuid"
    message: "Check out our new product!"
    fileIds: ["file_xyz789"]
  ) {
    id
  }
}

Document Message#

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    recipientUserId: "user-uuid"
    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"
    recipientUserId: "user-uuid"
  ) {
    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, use the template parameter on sendMessage:

mutation {
  sendMessage(
    platformConnectionId: "pc_whatsapp_123"
    recipientUserId: "user-uuid"
    template: {
      name: "order_confirmation"
      language: "en_US"
      components: [
        {
          type: "body"
          parameters: [
            { type: "text", value: "John" }
            { type: "text", value: "#12345" }
          ]
        }
      ]
    }
  ) {
    id
    eventTypeName
  }
}

Outeract uses a generic template model that is translated into the WhatsApp Cloud API format. For WhatsApp-specific fields (e.g. button sub-types, currency parameters), use the extras dict on components or parameters:

{
  "name": "order_confirmation",
  "language": "en_US",
  "components": [
    {
      "type": "button",
      "extras": { "sub_type": "quick_reply", "index": "0" },
      "parameters": [
        { "type": "text", "value": "Yes" }
      ]
    }
  ]
}

You can also provide message alongside template. The text is stored in the event payload but the template is what gets sent to WhatsApp.

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”#

• Outeract detects this error (WhatsApp error codes 131047/131026) and returns an OUTSIDE_MESSAGING_WINDOW error
• The failed message event is still recorded with delivery_status.failed_at set and delivery_status.error_type of messaging_window_closed
• Use the template parameter on sendMessage to send a pre-approved message template instead of free-form text
• 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