WhatsApp

Connect WhatsApp Business to ORQO so that Chief of Staff 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 WhatsApp in ORQO

1. Navigate to Settings → Integrations in ORQO.
2. Find the WhatsApp tile and click Install. ORQO creates the integration and adds the empty credentials below, already linked to it.

3. Add Credentials

1. Go to Settings → Credentials.
2. Fill in each value:

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

They're already linked to the WhatsApp integration, so you don't need to attach them manually.

4. Configure the Webhook in Meta

First, copy your Webhook URL: in Settings → Integrations, click the WhatsApp card and copy the Webhook URL field. It ends in a long per-organization token (not an app name or ID) — copy it whole.

Then, 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 the full Webhook URL you copied from the WhatsApp card.
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: choose WhatsApp as the app, and set the address to the person's phone number in international format (e.g., +1234567890).

warning

Only registered Contacts can interact with Chief of Staff. 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. Chief of Staff 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. Chief of Staff 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 Chief of Staff 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.

Sending Files (Outbound)

Chief of Staff can send files back through WhatsApp — a document or artifact from a project's library, or a file someone shared earlier in the conversation.

Supported types:

• Documents — PDF, Word (.doc/.docx), Excel (.xls/.xlsx), PowerPoint (.ppt/.pptx), plain text (.txt)
• Images — JPEG, PNG, WebP
• Video — MP4, 3GP
• Audio — AAC, MP3, M4A, AMR, OGG, Opus
• Text-based files — Markdown (.md), CSV, JSON and similar arrive as a file with their original name (sent as plain text under the hood, since WhatsApp doesn't accept those MIME types directly)

Size limits (set by WhatsApp): documents up to 100 MB, video 16 MB, images 5 MB.

File types WhatsApp doesn't accept (for example GIF, SVG, HEIC, MOV, or ZIP) surface a clear error instead of silently disappearing, so you know to convert them first.

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
• Chief of Staff AI to understand what Chief of Staff can do