WhatsApp Integration

Exact webhook URL (the one you paste in Meta)

Meta needs to know where to POST incoming WhatsApp messages. Replace YOUR-DOMAIN with your real domain:

https://YOUR-DOMAIN/api/webhooks/whatsapp

Example: if your install runs at https://app.acme.com, the webhook URL is:

https://app.acme.com/api/webhooks/whatsapp

Meta requires HTTPS with a valid SSL certificate. Self-signed certificates and HTTP URLs are rejected. If you're testing locally, use a tunnel like ngrok to get a public HTTPS URL.

Quick start (5 fields you need to fill in MailTrixy)

In MailTrixy go to Settings → Channels → WhatsApp → Configure and paste these five values from Meta's developer dashboard:

Common mix-up: the App Secret is NOT the Access Token and NOT the Verify Token. These are three different values on three different screens. Without the right App Secret, every inbound WhatsApp message is rejected with a 403 because MailTrixy verifies the HMAC signature on every webhook delivery.

How the integration works

WhatsApp Business API is provided by Meta. MailTrixy connects to Meta's Cloud API using a Permanent Access Token. Two communication directions:

• Outbound (you send) — MailTrixy calls Meta's Graph API endpoint POST /v22.0/{phone_number_id}/messages with your Access Token. Within the 24-hour customer messaging window, free-form text. Outside the window you must use approved Message Templates.
• Inbound (customer messages you) — Meta POSTs the message to your configured webhook URL. MailTrixy verifies the HMAC-SHA256 signature against your App Secret, then creates a conversation + message row in your inbox in real time.

AI-powered replies, auto-reply rules, knowledge-base context, and workflow automations all apply to WhatsApp threads the same way they apply to email threads.

Meta Business API Setup

WhatsApp Business API is provided by Meta (Facebook). You need a Meta Business account to get started.

1. Go to business.facebook.com and log in (or create a Meta Business account).
2. Navigate to developers.facebook.com and create a new app. Select Business type.
3. On the app dashboard, find WhatsApp in the product list and click Set Up.
4. You will be assigned a temporary Phone Number ID and WhatsApp Business Account ID for testing.
5. Generate a Permanent Access Token (System User token from Business Settings → System Users → Generate Token with whatsapp_business_messaging permission).

Business Verification

To send messages to customers (not just test numbers), Meta requires you to verify your business. This process takes 2–7 business days.

1. Go to Business Settings → Security Center → Start Verification.
2. Provide your business legal name, address, phone number, and website.
3. Upload a supporting document (business registration, utility bill, or bank statement).
4. Meta will review and approve (or request additional information).

Note: You can use the test phone number (provided by Meta) to develop and test your integration while waiting for verification. Test numbers can only message up to 5 pre-registered phone numbers.

Phone Number Setup

You can use your existing business phone number or a new dedicated number for WhatsApp.

• The number must be able to receive SMS or voice calls for verification.
• The number cannot already be registered with WhatsApp (personal or business app). If it is, you must delete the existing WhatsApp account first.
• Toll-free numbers and landlines work (Meta will verify via voice call).

In the Meta Developer dashboard, add your phone number under WhatsApp → Phone Numbers → Add Phone Number. Complete the verification process via SMS or voice call.

Once verified, copy the Phone Number ID and paste it into MailTrixy at Settings → Channels → WhatsApp → Phone Number ID.

Message Templates

WhatsApp requires that businesses use pre-approved message templates to initiate conversations with customers. Templates must be submitted to Meta for approval before use.

• When templates are needed: Only when you are sending the first message (initiating a conversation). If the customer messages you first, you can reply freely for 24 hours without a template.
• Template categories: Marketing, Utility (order updates, shipping), Authentication (OTP codes).
• Creating templates: Go to Meta Business Manager → WhatsApp Manager → Message Templates → Create Template.
• Variables: Use {{1}}, {{2}}, etc. as placeholders that MailTrixy will fill dynamically (customer name, order number, etc.).

MailTrixy syncs your approved templates automatically. You can select which template to use when starting a new WhatsApp conversation from the dashboard.

Credentials in MailTrixy

Settings → Channels → WhatsApp expects four values:

• Phone Number ID — from Meta Dev Portal → WhatsApp → API Setup.
• Access Token — permanent System User token recommended. Temporary tokens expire in 24 h.
• Verify Token — any random string you choose; Meta echoes it back during webhook registration.
• App Secret — required. From Meta Dev Portal → App Settings → Basic → "App secret" (click Show). Used to verify webhook HMAC-SHA256 signatures. Without it, every inbound webhook is rejected with 403.

App Secret is not the Access Token and not the Verify Token. It is a separate value on the App Settings page. A common misconfiguration is pasting the wrong value — the webhook will log "Signature did not match any active integration secret" and ignore the payload.

Webhook Configuration

Webhooks allow Meta to notify MailTrixy when new WhatsApp messages arrive.

1. In the Meta Developer Dashboard, go to WhatsApp → Configuration.
2. Set the Callback URL to: https://yourdomain.com/api/webhooks/whatsapp
3. Set the Verify Token to the same value you saved in MailTrixy.
4. Subscribe to the following webhook fields:
   • messages — incoming messages
   • message_status — delivery receipts (sent, delivered, read)
5. Click Verify and Save.

Important: Your server must be accessible over HTTPS with a valid SSL certificate. Meta will not send webhooks to HTTP URLs or self-signed certificates.

Signature verification

Every webhook delivery from Meta includes an X-Hub-Signature-256 header. MailTrixy recomputes the signature with your saved App Secret and rejects any request that doesn't match. If you see repeated "Signature did not match any active integration secret" warnings in storage/logs/laravel.log:

1. Confirm the App Secret in Settings is exactly what Meta shows in App Settings → Basic (click Show; it starts with a letter/digit, 32+ chars).
2. The App Secret belongs to the App whose Phone Number ID you're using — using Secret A with App B's phone number will fail.
3. Re-save the integration after pasting to trigger a fresh credential encryption.

Status updates

Meta sends sent, delivered, read, and failed status webhooks. MailTrixy maps them as follows:

• sent → delivery_status = sent, sent_at set.
• delivered → delivery_status = delivered, delivered_at set.
• read → delivery_status stays delivered (its stored enum doesn't include "read"), but opened_at is set — that timestamp is the source of truth for read receipts in the UI.
• failed → delivery_status = failed, Meta's error message is stored in delivery_error (truncated to fit the column).

Common issues

• "Signature did not match any active integration secret" — App Secret is missing, empty, or belongs to a different App. See "Signature verification" above.
• "Unsupported post request. Object with ID '…' does not exist" when Mailtrixy tries to mark a message as read — the Access Token stored in your integration is for a different App or has been revoked. Re-paste a fresh permanent System User token.
• Inbound message saves but no auto-reply fires — the rule's Exact phrase match requires the trimmed, lower-cased message to equal the keyword exactly. Either switch the match type to "Contains", or have the customer send the exact keyword.

Testing

Before going live, test the integration thoroughly:

1. Send a test message: From your personal WhatsApp, send a message to the WhatsApp Business number you configured.
2. Check MailTrixy: The message should appear in your MailTrixy inbox within a few seconds.
3. Reply from MailTrixy: Type a reply in MailTrixy and send it. The message should arrive on your personal WhatsApp.
4. Test AI reply: If AI is enabled for the WhatsApp channel, verify that AI-generated drafts appear (or auto-send, depending on your settings).
5. Test templates: From MailTrixy, start a new conversation using a message template. Verify the template is sent correctly with variables filled in.

If messages are not arriving, check the Webhook Logs section in MailTrixy (Settings → Channels → WhatsApp → Logs) for error details.