WhatsApp in Frappe CRM: how it works and how to set it up

The three pieces you need

• Meta's WhatsApp Cloud API carries the messages. You need a WhatsApp Business account and a Meta developer app.
• Frappe WhatsApp (frappe_whatsapp), an app by Shridhar Patil, stores the account credentials, templates and every message as a WhatsApp Message document, and receives Meta's webhook. It is open source on GitHub and on the Frappe Cloud marketplace.
• Frappe CRM adds the WhatsApp tab to leads and deals, links messages to the right record, and notifies the assigned user.

The Frappe CRM documentation confirms that the integration needs the separate Frappe WhatsApp app. We checked everything here against Frappe CRM v1.87.0.

When the WhatsApp tab appears

The CRM checks two things, and the tab and settings only appear when both pass:

1. Installed: the WhatsApp Settings DocType exists, which means frappe_whatsapp is installed on the site. This shows the WhatsApp page under Settings > Integrations, for managers only.
2. Enabled: WhatsApp Settings has a Default Outgoing Account, and that WhatsApp Account has status Active. This shows the WhatsApp tab on lead and deal pages.

If the tab's missing after setup, check those two fields first. When the outgoing account is inactive or not set, the tab doesn't show and you won't see an error.

On every migrate, the CRM also gives Sales User and Sales Manager write, create and delete permission on WhatsApp Message, WhatsApp Templates and WhatsApp Settings, so sales users don't need any extra role setup.

Setup, step by step

1. Install the app

From Frappe Cloud's marketplace, or on a self-hosted bench:

bench get-app https://github.com/shridarpatil/frappe_whatsapp
bench --site crm.example.com install-app frappe_whatsapp

2. Get credentials from Meta

Follow Meta's Cloud API getting started guide to create the app, add a phone number and generate an access token. While you're on test credentials, Meta only delivers to numbers you've added on its side.

3. Create the WhatsApp Account

In the WhatsApp Account DocType, fill in:

Then set it as the Default Outgoing Account (and Default Incoming Account) in WhatsApp Settings. You can also reach these settings from the CRM under Settings > Integrations > WhatsApp.

4. Point Meta's webhook at your site

In the Meta app's WhatsApp configuration, set the callback URL to:

https://crm.example.com/api/method/frappe_whatsapp.utils.webhook.webhook

Use the same Webhook Verify Token as in the WhatsApp Account. Subscribe at least to messages (incoming messages) and message_template_status_update (template approvals). Meta can only deliver to your site if it's reachable over public HTTPS.

5. Create templates

Create templates in the WhatsApp Templates DocType, or create them in Meta and use Sync from Meta on the list view. You can only use a template once Meta has approved it.

How messages flow

Outgoing

From the WhatsApp tab, a user can send a template, a free-text reply, an attachment, an emoji reaction, or a reply to a specific message. Each one becomes a WhatsApp Message document linked to the lead or deal, sent to the record's mobile number. For a deal, that is the primary contact's number.

WhatsApp only lets a business start a conversation with an approved template, and free text works once the customer replies. The CRM documentation points this out too. In practice it means your team's first message to a new lead is always a template.

Incoming

Meta calls the webhook, frappe_whatsapp creates a WhatsApp Message, and the CRM tries to link it to a record by phone number, in this order:

1. A contact with that number who is the primary contact on a deal: the message goes on the deal.
2. An unconverted lead with that mobile number: the message goes on the lead.
3. Otherwise, a contact with that number, if one exists.

Numbers are compared after stripping spaces, dashes, brackets and the plus sign, then checked with a phone number parser. A lead saved as +91 98200 12345 can still match a message that arrives as 919820012345.

When an incoming message lands on a lead or deal, every user assigned to it gets a CRM notification and the open lead or deal page refreshes in real time. If the number doesn't match anything, the message is still saved, but it won't appear on any lead or deal and nobody gets notified.

Things that catch teams out

• Unknown numbers don't create leads. If WhatsApp is a lead source for you, capture the lead first, from a form or an ad, so replies have somewhere to land.
• Mobile number formats. Matching is forgiving about formatting, but a lead with the number in a different field, or a typo, will not match.
• Only sales roles see WhatsApp. The CRM's WhatsApp methods allow System Manager, Sales Manager and Sales User. Anyone else gets a permission error, even with access to the lead.
• Twilio's Frappe app gets in the way. If the separate twilio_integration app is installed, the CRM returns no WhatsApp messages. The CRM has Twilio calling built in, so you don't need that app.