WhatsApp

Connect WhatsApp Business to ORQO so that Doorkeeper can receive and respond to WhatsApp messages, including images, video, audio, and documents.

Category	Communication
Capabilities	Send + Receive
Adapter path	/whatsapp
Auth method	System User token

Prerequisites

• A Meta Business account (business.facebook.com)
• A WhatsApp Business App created in the Meta Developer portal
• A System User with a permanent access token
• Access to the ORQO Settings area

Setup

1. Set Up Meta Business and WhatsApp

If you haven't already:

1. Go to developers.facebook.com and create an app with WhatsApp integration.
2. Under the WhatsApp section, note your Phone Number ID and WhatsApp Business Account ID.
3. Create a System User in your Meta Business settings with the whatsapp_business_messaging permission.
4. Generate a permanent access token for the System User.

info

The Meta Developer portal provides a test phone number you can use during development. For production, you need a verified phone number.

2. Install the WhatsApp App in ORQO

1. Navigate to Settings > Apps in ORQO.
2. Find WhatsApp in the app catalog and click Install.
3. The app is created with the correct adapter URL and capabilities.

3. Add Credentials

After installation, the credentials checklist shows what's required:

Credential	Type	Description
WHATSAPP_ACCESS_TOKEN	api_key	System User permanent access token
WHATSAPP_PHONE_NUMBER_ID	api_key	Your WhatsApp phone number ID
WHATSAPP_APP_SECRET	api_key	App secret from Meta Developer portal (for webhook signature verification)
WHATSAPP_VERIFY_TOKEN	api_key	A secret string you choose (used for initial webhook verification)

Create these credentials in Settings > Credentials, then assign them to the WhatsApp App. The credential dropdown is filtered to show only relevant credentials.

4. Configure the Webhook in Meta

In the Meta Developer portal:

1. Navigate to your WhatsApp app's Configuration page.
2. Under Webhook, click Edit.
3. Set the Callback URL to:

   https://your-orqo-domain.com/api/v1/webhooks/:app_id

   Replace :app_id with the App ID shown on the WhatsApp app card in ORQO.
4. Set the Verify Token to the same value you stored as WHATSAPP_VERIFY_TOKEN.
5. Click Verify and Save. Meta sends a GET request with a challenge — ORQO verifies the token and responds automatically.
6. Subscribe to the messages webhook field.

5. Add Contacts

For each person who should be able to message ORQO through WhatsApp:

1. Go to Settings > Contacts and create a Contact.
2. Add a Contact Channel linked to the WhatsApp App.
3. Set the channel address to the person's phone number in international format (e.g., +1234567890).

warning

Only registered Contacts can interact with Doorkeeper. Messages from unknown WhatsApp numbers are silently rejected.

6. Verify the Connection

Click Verify on the WhatsApp app card in ORQO. This tests the connection to the adapter.

Send a WhatsApp message to your business number from a registered Contact. Doorkeeper should respond.

Available Tools

The WhatsApp adapter exposes MCP tools that agents can use in workflows:

Tool	Description
send_whatsapp_message	Send a message to a WhatsApp number
get_whatsapp_profile	Get profile information for a WhatsApp number

These tools are discovered automatically when the App is verified and can be assigned to agents via Skills.

Platform-Specific Behavior

Attachments and Media Processing

WhatsApp supports rich media. When a Contact sends an image, voice message, audio file, or document, ORQO processes each type automatically:

• Voice messages — Recorded using WhatsApp's push-to-talk button, voice messages are automatically transcribed to text. Doorkeeper processes them as regular messages, so users can speak their requests instead of typing. Supported formats: OGG/Opus, WebM/Opus, MP3, WAV, MP4.
• Images — Passed to the LLM with vision support, so Doorkeeper can see and describe visual content. If the image contains text (screenshots, photos of documents, etc.), the text is automatically extracted via OCR and included alongside the image for accurate quoting and analysis.
• Documents — Can be saved to a project's document library.
• Audio files — Regular audio files (forwarded recordings, podcasts, music) are treated as file attachments, not transcribed. Only voice messages recorded in WhatsApp are auto-transcribed.

Webhook Security

WhatsApp uses two layers of verification:

1. Initial setup — Meta sends a GET request with your verify token to confirm the webhook URL.
2. Ongoing messages — Every webhook POST includes an X-Hub-Signature-256 header with an HMAC-SHA256 signature using your app secret. ORQO verifies this signature on every request.

Session Management

WhatsApp conversations persist across messages. To start a fresh conversation, send any of these:

• reset
• new session
• clear session
• start over

What's Next

• Apps & Channels for the full architecture
• Configure Webhooks for detailed webhook setup
• Doorkeeper AI to understand what Doorkeeper can do