WhatsApp Integration

WhatsApp is the dominant first-touch channel in Dubai real estate. A buyer on Property Finder, Bayut, or your own site usually clicks the chat icon before they pick up the phone, and they expect a reply in seconds, in the language they wrote in. Hadar treats WhatsApp as a first-class CRM surface: every inbound message becomes a lead event, every outbound reply is logged against the same timeline as voice and email, and every consent change is audit- logged for UAE PDPL.

Two providers are supported. UltraMsg wraps WhatsApp Web on a hosted instance and is ideal for early-stage workspaces — you can be live in under an hour without a Meta Business Manager. Meta WhatsApp Business Cloud API is the long-term path: required for templated marketing, branded sender display, higher tier limits, and any cross-region traffic above a few thousand conversations per month. Both providers route through the same Hadar inbox, so you can start on UltraMsg and migrate without changing any downstream workflow. All configuration lives under Integrations > WhatsApp, and tokens are stored per-tenant in integration_tokens, envelope-encrypted at rest.

1. UltraMsg setup (default for launch)

Create an UltraMsg account at ultramsg.com and provision an instance against the WhatsApp number you actually answer in production. We recommend a dedicated SIM rather than a personal number — switching numbers later requires re-opting-in your contact base.
In the UltraMsg dashboard, copy the Instance ID and the Token.
In Hadar, paste both into Integrations > WhatsApp > UltraMsg. We hit the UltraMsg /instance/status endpoint before saving — if the instance is not authenticated on WhatsApp Web, the save is rejected with a clear error rather than persisting a half-broken integration.
Configure the UltraMsg webhook to point at https://api.hadar-ai.com/v1/webhooks/whatsapp/<tenant_id> using the per-tenant secret shown in the integration card. Hadar verifies the HMAC signature on every inbound event and rejects unsigned payloads at the edge.

2. Meta Cloud API setup (Enterprise path)

For tenants on Growth-with-Meta or Enterprise, provision Meta Business Manager, claim a WhatsApp Business Account, complete business verification, and add a phone number. Generate a system-user access token with the whatsapp_business_messaging and whatsapp_business_management scopes and paste it into Integrations > WhatsApp > Meta Cloud API. Hadar takes care of the webhook subscription on the WhatsApp Business Account, verifies the X-Hub signature on every callback, and pulls your existing templates into the local Templates table so you can use them immediately.

3. The 24-hour customer service window

After a contact sends you a message, you have a rolling 24-hour window to reply with free-form content — text, media, voice notes, files. Outside that window you may only send pre-approved message templates. Hadar enforces this rule server-side: the composer in the inbox automatically switches to template selection when the window has closed, and the API will return WINDOW_CLOSEDrather than silently dropping a free-form send. The deadline is shown as a live countdown on every conversation so agents never wonder “can I still reply normally?”.

4. Opt-in capture

UAE PDPL and Meta's Commerce Policy both require explicit, recorded opt-in before any unsolicited outreach. Hadar captures consent three ways and writes the consent string, timestamp, source, and IP hash to contact_consents so it is auditable years later.

Inbound message: any contact who messages your number is implicitly opted-in for the rolling 24-hour service window.
Public lead-capture form: the WhatsApp-consent checkbox is configurable and supports a double opt-in for marketing — the contact must reply YES to your first WhatsApp message before the lead is marked as marketable.
Manual:operators can record verbal consent in the lead detail panel. Hadar prompts for the exact wording used and stores it alongside the operator's user ID.

5. Templates and Meta approval

Submit and manage templates from WhatsApp > Templates. Each template is reviewed by Meta — typically 24 to 48 hours — before it becomes sendable. Hadar ships a Dubai-real-estate starter pack covering viewing-booking confirmations, area summaries, post-viewing follow-up nudges, agent introductions, and listing shares. Every template exists in both Arabic and English; you can clone, customise, and submit in a single click. Approved templates appear in the composer with their localisation badge so an agent sending an Arabic-first thread never accidentally fires the English variant.

6. AR/EN bilingual messaging and voice notes

Hadar auto-detects the language of every inbound message and persists it on the conversation. Agents can reply in either language; the AI assistant suggests replies in the thread language by default and offers a one-tap translation if the agent prefers to type in their stronger language. Voice notes inbound from the contact are transcribed and translated into the operator's preferred language. Voice notes outbound from the operator are synthesised through the same ElevenLabs voice as your voice agent, so brand voice stays consistent across channels.

7. Lead-to-WhatsApp routing (under 30 seconds)

New leads from Property Finder, Bayut, Dubizzle, your own site, or a Meta Lead Ad land in Hadar within a few seconds. If the lead carries a phone number and an opt-in signal, Hadar immediately drafts the first message in the lead's detected language, fires it through the WhatsApp provider, and writes the event to the lead timeline — typical end-to-end latency is well under 30 seconds from portal capture to message-sent. The agent gets a notification with the draft and can intervene at any point: edit before send, hold for review, or hand off to a human entirely.

8. Webhook delays, DLQ replay, and troubleshooting

WhatsApp webhooks occasionally arrive out of order or are dropped by the provider during regional incidents. Hadar buffers every inbound event through a dead-letter queue: if the processing handler fails (decryption error, downstream timeout, schema mismatch), the payload is parked and retried with exponential backoff. Workspace admins can review and manually replay parked events from Integrations > WhatsApp > Event log. If you see your inbox lagging live conversations, check the event log first — a stuck event is almost always the cause and replay typically resolves it inside a minute.

For deeper failures (template send returning ERROR_TEMPLATE_PARAM_MISMATCH, signature failures, or the UltraMsg instance dropping authentication), the lead timeline carries a trace_id on every event — pass that ID to support@hadar-ai.com and we will pull the request through our logs without needing additional context.

9. Quality, rate limits, and opt-out

Meta scores every business phone number on conversational quality. Hadar surfaces the current rating (Green / Yellow / Red), the 24-hour message cap from your tier, and a soft warning if your opt-out rate creeps above 0.5%. Sustained low quality triggers an automatic conservative-send mode that throttles outbound velocity and forces template approval on every new send until the rating recovers. Inbound STOP, UNSUBSCRIBE, إلغاء, and similar keywords automatically write a revocation to contact_consents and exclude the contact from all future marketing sends.