> **Before you begin:** This module must be enabled first. Go to **Settings → System Upgrade**,
> find **WhatsApp** in the list of available modules, and activate it. Then return to this guide.
Module Overview
The **WhatsApp** module lets you send WhatsApp messages to your customers, leads, and employees directly from the CRM — the same way you already send SMS or Email. It supports three connection providers, with **OpenWA** — a free, self-hosted, open-source WhatsApp connection — as the recommended option.
What you can do with this module
- Send a WhatsApp message to one person or to a whole list of phone numbers at once.
- Send plain text messages or messages with an attached image, video, audio file, or document.
- Reuse saved message templates and insert dynamic shortcodes (name, phone number, and more) that are filled in automatically for each recipient.
- Send instantly, or place messages in a queue that goes out automatically on a schedule you control.
- Connect multiple WhatsApp numbers to OpenWA as separate **sessions**, mark one as the default, and optionally restrict a session to specific team members.
- Schedule an entire send for a future date and time.
- See every WhatsApp message sent to or received from a person directly on their profile page.
- Automatically block sending to numbers on your Blocked Phones list.
- Trigger WhatsApp messages automatically from Automation workflows (for example, when a lead changes status).
Typical use cases
- Sending appointment reminders or order updates to customers over WhatsApp instead of SMS.
- Sending a bulk announcement to a list of leads, spread out automatically over time instead of all at once.
- Automatically messaging a customer's assigned salesperson through an Automation workflow whenever a new lead is created.
Activating the Module
https://VIDEO_PLACEHOLDER_URL
- Open the CRM and click **Settings** in the main navigation menu.
- Go to **System Upgrade**.
- Find **WhatsApp** in the list of available modules.
- Click **Activate**.
> **Note:** You need administrator access to activate modules.
Choosing a WhatsApp Provider
https://VIDEO_PLACEHOLDER_URL
Once the module is active, open **Settings → WhatsApp** to configure it.
- In the **Provider** dropdown, choose which service will actually deliver your messages:
- **OpenWA** — a self-hosted, open-source connection. No monthly fees, but you must run your own server. This is the recommended provider.
- **wallmessage.com** — a hosted third-party service.
- **autochat.ir** — a hosted third-party service.
- The settings fields below the dropdown change depending on the provider you pick — only the fields relevant to OpenWA are described in this guide (see [Other Provider Options](#other-provider-options) for the other two).
- Click **Save WhatsApp Settings** after making changes.
Setting Up OpenWA (Self-Hosted)
https://VIDEO_PLACEHOLDER_URL
OpenWA is a separate, free program that you (or your IT administrator) install on a server you control. It connects to WhatsApp on your behalf, and the CRM talks to it over the internet or your local network. Before selecting OpenWA as your provider, deploy and configure your own OpenWA server — see the **View Quick Start Guide** link shown in the settings page for installation instructions.
Once your OpenWA server is running, its console prints a startup message similar to this:
javascript
🟢 Welcome to OpenWA - WhatsApp API Gateway
[api] [OpenWA] LOG [AuthService] 📊 Dashboard: http://localhost:2785
[api] [OpenWA] LOG [AuthService] 📚 API Docs: http://localhost:2785/api/docsThe address next to **Dashboard** is exactly what you need for the **OpenWA Server URL** field below.
OpenWA settings fields
| Field | What to enter |
|---|---|
| **OpenWA Server URL** | The base address of your OpenWA server, **including the port number**, with nothing added after it. Using the example above, enter `http://localhost:2785`. Do **not** add `/api` or any other path — the CRM adds that automatically. If the CRM and the OpenWA server run on different machines, replace `localhost` with that server's real IP address or domain name. |
| **API Key** | The API key configured on your OpenWA server. This is set in the OpenWA server's own configuration file — it is **not** shown in the startup console log pictured above, so check your server's configuration or ask whoever installed it. |
| **Request Timeout (seconds)** | How long the CRM waits for a reply from the OpenWA server before giving up. The default of 30 seconds is enough for most cases — increase it if messages with attachments regularly fail to send in time. |
| **Enable Media Messages** | Set to **Yes** to allow sending images, videos, audio, and documents through OpenWA. Set to **No** if your OpenWA server or session does not support media sending. |
- Fill in the fields above and click **Save WhatsApp Settings**.
> **Note:** The server URL, API key, timeout, and media toggle apply to your whole OpenWA server. Each WhatsApp number you connect to it is configured separately as a **session** — see the next section.
Managing WhatsApp Sessions
https://VIDEO_PLACEHOLDER_URL
An OpenWA server can host more than one connected WhatsApp number at the same time — each one is called a **session**. The CRM needs at least one session on record before it can send anything through OpenWA, and you can create as many as you have connected numbers.
Finding a session's identifier
Open your OpenWA dashboard and copy the identifier of the WhatsApp session you connected. It is **not** a name you choose — it is a value your OpenWA server generates, and it looks like this:
javascript
a76cf94c-9d0a-4cf1-bcc1-70f3ed68af01You will paste this exact value into the CRM when creating the session below.
Creating a session
In **Settings → WhatsApp**, scroll to **WhatsApp Sessions**:
- Click **New Session**.
- Fill in the fields:
| Field | Description |
|---|---|
| **Name** | A label for your own reference (for example, "Sales Team" or "Support Line"). It is not sent to OpenWA. |
| **Session Identifier** | **Required.** The identifier copied from your OpenWA dashboard, such as `a76cf94c-9d0a-4cf1-bcc1-70f3ed68af01`. The message cannot be sent without a valid identifier here — this is the single most important field on this form. |
| **Status** | **Enable** or **Disable** this session. A disabled session cannot be selected when sending or testing. |
| **is Default** | Only one session can be default. The default session is used automatically whenever no specific session is chosen — for Automation-triggered messages, queued sends, and scheduled sends created without picking one. |
| **Allowed Users** | Optional. Search and select specific WordPress users who may choose this session when sending a message. Leave empty to let anyone with WhatsApp send permission use it. |
- Click **Save**.
The sessions table shows every session's name, identifier, allowed users (or "All users" if unrestricted), default status, and active status, with **Edit** and **Remove** actions. The default session cannot be removed — set another session as default first if you need to delete it.
Testing the Connection
https://VIDEO_PLACEHOLDER_URL
After saving your settings, an **OpenWA Test** section appears on the same page (only while OpenWA is the selected provider) so you can confirm the connection works before sending real messages.
- **Save your WhatsApp settings first** — the test always uses the currently saved configuration, not whatever is typed in the fields above but not yet saved.
- Choose which **Session** to test from the dropdown (see [Managing WhatsApp Sessions](#managing-whatsapp-sessions)). If no session exists yet, an alert tells you to create one first.
- In the **Recipient number** field, enter a WhatsApp number in international format, digits only (no `+` sign, no spaces or dashes) — for example `6281234567890`.
- Click **send test**.
- Wait for the result message:
- **"Successfully sent"** means the CRM reached your OpenWA server and it accepted the message.
- Any other message describes exactly what went wrong (see [Troubleshooting](#troubleshooting)).
Other Provider Options
If you prefer a hosted service instead of running your own server, the **Provider** dropdown also offers:
- **wallmessage.com** — requires an **API Token/authkey** and an **appkey** from your wallmessage.com account.
- **autochat.ir** — requires an **API Token/authkey** from your autochat.ir account.
Both share the same **Sender Name** field, and the same **Send schedule** / **Number of send per time** queue settings described in [The WhatsApp Queue](#the-whatsapp-queue). Everything described from [Sending a WhatsApp Message](#sending-a-whatsapp-message) onward in this guide works identically no matter which provider you choose.
Sending a WhatsApp Message
https://VIDEO_PLACEHOLDER_URL
You can open the **Send WhatsApp Message** window from two places:
- The WhatsApp icon on a user's or lead's profile page — sends to that one person.
- The **WhatsApp** button available above most contact lists (Users, Leads, Target Groups, and similar list pages) — sends to one or many selected recipients at once.
Message window fields
| Field | Description |
|---|---|
| **WhatsApp Session** | *(OpenWA only)* Which connected WhatsApp number sends this message — see [Managing WhatsApp Sessions](#managing-whatsapp-sessions). Only sessions you are allowed to use appear here; it defaults to the default session. If none are available to you, an alert asks you to contact your administrator instead of showing the dropdown. |
| **Message Type** | **Text** for a plain message, or **File** to attach an image, video, audio file, or document with an optional caption. |
| **Message** / **Caption** | The message text (or the caption for a file). You can type your own text, load a saved pattern, or insert shortcodes — see [Templates and Shortcodes](#templates-and-shortcodes). |
| **Receivers** | One phone number per line. A live counter shows how many rows (recipients) you have entered. |
| **Remove duplicate phone from list** | Click to instantly remove any repeated numbers from the Receivers box. |
| **Fast Send** | When **on**, all recipients are messaged immediately while you wait, in the same request. Turn this **off** for a large number of receivers, so the send runs safely in the background instead. |
| **Ignore the Send Queue!** | When **on**, each message is sent straight to your WhatsApp provider right away. When **off**, messages are placed in the [WhatsApp Queue](#the-whatsapp-queue) and sent automatically according to your queue schedule — the recommended choice for larger lists, to avoid looking like spam. |
| **Ignore blocked phone** | When **on**, messages are sent even to numbers on your [Blocked Phones](#blocked-phone-numbers) list. Use only when necessary. |
| **Scheduled Message** | When **on**, pick a future **Send Date** and **Time** — the whole send is triggered automatically at that moment instead of right away. See [Scheduling a Message for Later](#scheduling-a-message-for-later). |
- Click **send**. A results panel shows how many messages were processed and lets you click **Update results** to refresh the live count as sending continues.
> **Note:** If you have permission to view the [WhatsApp Queue](#the-whatsapp-queue), the window also shows a live count of messages currently waiting to be sent, with a link to manage them.
Templates and Shortcodes
https://VIDEO_PLACEHOLDER_URL
Using a saved pattern
Inside the **Send WhatsApp Message** window, any saved template created with the type **Wall Message** appears as a one-click button under **Patterns**. Click it to load that template's text straight into the **Message** field.
Creating and managing templates
Templates are shared with the SMS and Email modules and managed from **Tools → Message Template**:
- Click **New Template**.
- Choose **Wall Message** as the **template type**.
- Enter a **Title**.
- Choose **Message Type** (**Text** or **File**, same as in the send window) and write the message (or upload a file and caption).
- Click **Save**.
Use the **Edit** and **Remove** icons in the template list to update or delete existing templates.
Shortcodes
Shortcodes are placeholders that the CRM automatically replaces with real information about each recipient when the message is sent. Click any shortcode button to insert it into your message, or type it manually:
| Shortcode | Replaced with |
|---|---|
| `{user_login}` | The recipient's username |
| `{first_name}` | First name |
| `{last_name}` | Last name |
| `{full_name}` | Official full name |
| `{user_email}` | Email address |
| `{phone}` | Phone number |
| `{role}` | User role |
| `{display_name}` | Display name |
| `{company_name}` | Company/institution name |
| `{your_usermeta}` | A custom profile field — replace `your_usermeta` with the actual field's key |
Example: `Hi {first_name}, your order is ready for pickup!` sends a personalized message to every recipient.
The WhatsApp Queue
https://VIDEO_PLACEHOLDER_URL
Messages sent with **Ignore the Send Queue!** turned off are not sent immediately — they are placed in the WhatsApp Queue and sent out automatically in small batches, based on two settings at the top of **Settings → WhatsApp**:
| Setting | Description |
|---|---|
| **Send schedule** | How often the CRM checks the queue and sends the next batch (for example, every 5 minutes, hourly, and so on). |
| **Number of send per time** | How many queued messages are sent each time the schedule runs. |
To manage the queue itself, go to **Tools → WhatsApp Queue**:
- View every message still waiting to be sent (text, attached file, sender, receiver, and date).
- Click the **eye icon** to view a queued message's full content.
- Click the **trash icon** to remove a single message from the queue, or select multiple rows and remove them together, before it is sent.
Scheduling a Message for Later
https://VIDEO_PLACEHOLDER_URL
Turning on **Scheduled Message** in the send window (instead of sending right away) lets you pick a future **Send Date** and **Time**. The entire send — to every recipient you entered — is triggered automatically once that moment arrives. The window also shows the current **Server Time**, so you can pick a date and time relative to the server's clock rather than your own.
Manage every scheduled send (SMS, Email, and WhatsApp together) from **Tools → Scheduled Message**:
- See the **Send Date**, who created it, and when it was created.
- Click the **edit icon** to change a scheduled message before it goes out.
- Click the **trash icon** to cancel it.
WhatsApp History on Profiles
https://VIDEO_PLACEHOLDER_URL
Open any **user** or **lead** profile and look for the **WhatsApp** tab. It lists every WhatsApp message linked to that phone number — both messages sent to them and messages sent by them (if they are also a CRM user who has sent WhatsApp messages) — showing:
- The message text and any attached file.
- **Successful** or **Unsuccessful** delivery status.
- The date it was sent.
- Whether it was **received from** or **sent to** the other party, with a link to their profile when known.
Use the **eye icon** to view a message and the **trash icon** to remove it from the history.
Blocked Phone Numbers
The **Ignore blocked phone** option (in the [send window](#sending-a-whatsapp-message)) checks each recipient against your shared **Blocked Phones** list — the same list used by the SMS module. If a number is on this list, it is skipped automatically unless you turn that option on.
Manage the list from the SMS settings page (**Blocked Phones**), where you can also configure the reasons customers can select to unsubscribe.
Sending WhatsApp Messages Automatically
https://VIDEO_PLACEHOLDER_URL
If you use the **Automation** module, you can add a **WhatsApp** action to any automation workflow so a message is sent automatically when the workflow runs — for example, to the profile itself, to specific users, to a form's configured "responsible" person, or to everyone in a chosen role. Configure the message text, an optional attached file, and the recipients inside the workflow's WhatsApp settings section. This uses the same shortcodes described in [Templates and Shortcodes](#templates-and-shortcodes). See the Automation module guide for full details on building workflows.
Permissions and Roles
Access to this module is controlled by capabilities assigned to user groups, listed under the **WallMessage** permission group (plus a few shared capabilities used by other messaging modules).
| Capability | What it allows |
|---|---|
| **Permission to send message with WallMessage** | Allows opening the Send WhatsApp Message window and sending messages. |
| **Permission to delete WallMessages in user profile** | Allows removing entries from the [WhatsApp History tab](#whatsapp-history-on-profiles) on profiles. |
| **Permission to delete WallMessages in the queue** | Allows removing messages from the [WhatsApp Queue](#the-whatsapp-queue). |
The **WhatsApp Queue**, **Message Template**, and **Scheduled Message** pages each additionally require their own page-view permission before they appear in the **Tools** menu for a given user group. Viewing the [WhatsApp tab on profiles](#whatsapp-history-on-profiles) requires its own separate view permission as well, listed as **"Permission to view the history of WhatsApp in profile."**
Creating, editing, or deleting entries under [Managing WhatsApp Sessions](#managing-whatsapp-sessions) requires the same access as the general system Settings area — day-to-day users who only send messages do not need this; it is meant for administrators. Who may *use* an already-created session when sending a message is a separate matter, controlled per-session by its **Allowed Users** list.
Setting permissions
- Go to **Settings → Groups** (or your user permissions panel).
- Select the group you want to configure.
- Find the **WallMessage** section (and the Message Template / Scheduled Message / WhatsApp Queue entries) in the permissions list.
- Check or uncheck the capabilities as needed.
- Save changes.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Test always fails, even though the message actually arrives on the phone | An older version of the plugin — this has been fixed. | Update the CRM plugin to the latest version and try the test again. |
| "No OpenWA session is configured" | No session exists yet, or the one chosen is disabled. | Create or enable a session under [Managing WhatsApp Sessions](#managing-whatsapp-sessions), and mark one as default. |
| "cURL request failed" or a connection error | The **OpenWA Server URL** is wrong, the port is missing, or the OpenWA server is not running. | Confirm the OpenWA server is running and re-check the **Dashboard** address from its console log, including the port number. |
| "OpenWA request failed (HTTP 401)" or similar authentication error | The **API Key** does not match the one configured on the OpenWA server. | Re-check the API key in your OpenWA server configuration and update the settings field. |
| "OpenWA request failed (HTTP 404)" | The **Session Identifier** on the session you are sending through does not match a session that exists on the OpenWA server. | Open the OpenWA dashboard, confirm the exact identifier, and update it on the session in [Managing WhatsApp Sessions](#managing-whatsapp-sessions). |
| The send window shows "No WhatsApp session is available to you" | No active session exists, or every existing session's **Allowed Users** list excludes you. | Ask an administrator to create a session, enable one, or add you to a session's Allowed Users. |
| Media (image/video/file) messages are not sent | **Enable Media Messages** is set to **No**. | Set it to **Yes** and save the settings, provided your OpenWA server and session support media. |
Practical Examples
Example 1 — One-off customer message
**Scenario:** A customer asks a question and you want to reply on WhatsApp from their profile.
**Steps:** Open their profile, click the WhatsApp icon, type your reply, leave **Ignore the Send Queue!** on, and click **send**.
**Result:** The message is delivered immediately through your configured provider and appears in their **WhatsApp** history tab.
Example 2 — Bulk announcement to a list of leads
**Scenario:** You want to notify 500 leads about a promotion without looking like a spam blast.
**Setup:**
- **Fast Send:** Off
- **Ignore the Send Queue!:** Off
- **Message:** loaded from a saved pattern with a `{first_name}` shortcode
**Result:** All 500 messages are placed in the WhatsApp Queue and sent out gradually according to your **Send schedule** and **Number of send per time** settings, each personalized with the recipient's first name.
Example 3 — Scheduling a reminder for tomorrow morning
**Scenario:** You want a reminder message to go out at 9:00 AM tomorrow, not right now.
**Setup:**
- **Scheduled Message:** On
- **Send Date / Time:** tomorrow, 09:00
**Result:** The message queues up now but is only actually sent once the server clock reaches that date and time. You can review or cancel it beforehand from **Tools → Scheduled Message**.
Example 4 — Two connected numbers, one restricted to support
**Scenario:** Your company has a sales WhatsApp number and a support WhatsApp number, both connected to the same OpenWA server, and only the support team should be able to send from the support number.
**Setup:**
- **Session "Sales"** — Allowed Users left empty (open to everyone), marked as default.
- **Session "Support"** — Allowed Users set to the support team's accounts.
**Result:** Everyone sees "Sales" in the send window's session dropdown; only support team members also see and can pick "Support." Automation workflows and queued messages that do not specify a session use "Sales," since it is the default.
Best Practices
- **Test your connection after every settings change.** Use the OpenWA Test section (or check a real send) before relying on the module for real customers.
- **Give every connected WhatsApp number its own session with a clear name.** It makes the sessions table, the send window's dropdown, and the test picker easy to use correctly when more than one number is connected.
- **Restrict sensitive sessions with Allowed Users.** For example, keep a support line's session limited to the support team, while leaving a general sales session open to everyone with send permission.
- **Turn off Fast Send for large recipient lists.** It keeps the sending process running safely in the background instead of tying up the request.
- **Prefer the queue over instant sending for bulk messages.** Turning off **Ignore the Send Queue!** spreads messages out automatically and looks less like spam.
- **Use shortcodes in templates.** A personalized message performs better than a generic one, and templates keep your wording consistent.
- **Keep Enable Media Messages off if you do not send attachments.** There is nothing to gain from enabling it, and it avoids extra failure points.
- **Review the Blocked Phones list periodically.** It is shared with SMS, so keeping it accurate protects both channels.
- **Assign the delete permissions carefully.** Only give queue and history deletion rights to users who should be able to remove messages that others sent.