# Create a WhatsApp Campaign A WhatsApp campaign lets you deliver marketing, utility, and authentication messages straight to your contacts' phones through WhatsApp, using approved message templates to reach large numbers of customers quickly. This page walks you through creating a campaign on a WhatsApp channel. ## Requirements Your system must be running firmware version `84.20.0.21` or later. :::note The Message Campaign feature is available only on firmware `84.20.0.21` and later. If you do not see the **Message Campaign** menu, check your firmware version and update first. ::: ## Before you begin Have the following in place before you build a campaign. **WhatsApp channel**: Configure a channel that is linked to your WhatsApp Business Account. See [Set up a WhatsApp Channel](/pbx/contact-center-guide/set-up-a-whatsapp-channel/). :::caution Confirm that your WhatsApp account's messaging limit is high enough to cover the volume you plan to send. If a campaign exceeds the limit, some messages will fail to deliver. ::: ![WhatsApp Business Account showing an available messaging limit](/images/pbx/sufficient-wa-message-limit.png) **Message template**: Create your templates in your WhatsApp Business Account ahead of time. WhatsApp must approve a template before it can be used, so allow time for review. Once approved, refresh the template list in Cloud Voice so the templates are synchronized and ready to select for your campaign. For details, see [View WhatsApp Message Templates](/pbx/contact-center-guide/view-whatsapp-message-templates/). :::note Template variable names may contain only lowercase letters and numbers. Avoid underscores and special characters, which can prevent the variable from working correctly. ::: **Contact list**: Assemble the phone numbers you want to reach. :::note A single campaign can include up to 1,000 contacts. ::: You can attach contacts to a campaign in any of these ways: - Type contact numbers in by hand. - Import a CSV file (a plain-text spreadsheet where each value is separated by a comma) of phone numbers. The file must meet these conditions: - **Format**: UTF-8 encoded `.CSV` (UTF-8 is a text encoding that supports international characters) - **Size**: under 50 MB - **File name**: fewer than 127 characters - **Columns**: include a `Number` field with phone numbers in E.164 format (the international standard: a plus sign, the country code, then the subscriber number, for example `+1xxxxxxxxxx`), as shown below. ![CSV file with a Number column of E.164 phone numbers](/images/pbx/msg-campaign-contact-list.png) - Pull contacts directly from an existing company phonebook. Numbers stored in the phonebook must already be in E.164 format, as shown below. ![Phonebook contact whose number is stored in E.164 format](/images/pbx/number-format.png) **Message routing target** *(optional)*: If you want the campaign to open sessions (conversation threads an agent can pick up and reply to) automatically, set up the destination in advance. This can be an extension (an individual user's line) or a [message queue](/pbx/contact-center-guide/create-a-message-queue/). ## Create the campaign 1. Sign in to the Cloud Voice management portal and go to **Messaging > Message Campaign**, then click **Add**. 2. Complete the **Basic** section: - **Name**: A label that helps you recognize the campaign. - **Message Channel**: The WhatsApp channel to use. - **Sender**: The WhatsApp phone number that messages are sent from. - **Recipient**: Choose recipients using one of the methods below. **Enter numbers manually** 1. Select **Input & Import**. 2. Click **Add** and type each phone number in E.164 format (for example, `+1xxxxxxxxxx`). ![Recipient panel with manually entered phone numbers](/images/pbx/manually-add-number.png) **Import a CSV file** 1. Select **Input & Import**. 2. Click **Import**. 3. In the pop-up window, click **Browse** and choose your file. 4. Click **Import**. ![Import dialog for uploading a CSV of recipient numbers](/images/pbx/import-message-contact.png) **Use an existing phonebook** 1. Select **Phonebooks**. 2. From the **Phonebooks** drop-down list, pick the phonebook you want. 3. From the **Number Type** drop-down list, choose the number type. The system collects the phone numbers that match the selected types. ![Recipient panel set to pull numbers from a phonebook](/images/pbx/message-phonebook.png) 3. In the **Message Content** section, set up the template to send. 1. Click **WhatsApp Message Template**, then search for and select the template you want. ![Template picker for choosing an approved WhatsApp template](/images/pbx/search-and-select-template.png) :::tip Keep your first run small. Send to a few numbers you control so you can confirm the template, media, and variable values look correct before launching to your full contact list. ::: 2. If the template contains media or variable placeholders, upload the media files and provide a value for every variable. ![Template editor with fields for filling in variable values](/images/pbx/edit-template-variables.png) :::note - The right-hand panel shows a live preview of the finished message. - For a location, paste a Google Maps URL and the system fills in the place name and coordinates automatically. You still need to type the street address into the `{{Address}}` variable yourself. ::: ![Location template with an address entered for the Address variable](/images/pbx/location-message-template.png) 4. In the **Sending Rules** section, decide when the messages go out and how sessions are handled. 1. Under **Send Time**, choose one of the following: | Option | What it does | | --- | --- | | **Send Now** | Sends the campaign as soon as you save it. | | **Schedule Sending** | Sends the campaign at a date and time you set. | | **Do NOT Send, Save as Draft** | Stores the campaign as a draft so you can edit or send it later. | ![Scheduler for choosing a future send date and time](/images/pbx/specified-date-and-time.png) :::caution **Send Now** delivers to every recipient the moment you click **Save**, and WhatsApp messages cannot be recalled once sent. If you are not certain the campaign is ready, choose **Do NOT Send, Save as Draft** or **Schedule Sending** instead. ::: 2. Under **Send Mode**, choose whether sessions are created: | Option | What it does | | --- | --- | | **Create session and send message** | Opens a session for each contact when the campaign sends, and assigns it to the target you selected (an extension or a message queue). | | **Send messages directly without creating session** | Sends the messages without opening any session. These messages do not appear in **External Chat Logs**. | :::note When a contact already has an active session, the campaign message is delivered to that existing session rather than creating and assigning a new one to your target. ::: ![Send Mode set to create sessions with a routing target selected](/images/pbx/message-target.png) 5. Click **Save**. ## Result The campaign is created and appears in the campaign list. - If you chose to send right away, the status shows **Executing** and messages go out to the listed numbers immediately. ![Campaign list entry with an Executing status](/images/pbx/immediate-campaign-wa.png) - If you scheduled the campaign, the status shows **Scheduled** and messages send automatically at the set time. ![Campaign list entry with a Scheduled status](/images/pbx/scheduled-campaign-wa.png) Once a campaign reaches **Completed**, you can review its outcome from the campaign list. :::note - To resend any messages that failed, click the retry icon ![Retry](/images/pbx/Restore.png). - To reuse a campaign's settings, click the duplicate icon ![Duplicate](/images/pbx/role%20management_copy.png) to copy it. ::: - For a quick summary, look at the **Result** and **Response Rate** columns. ![Campaign list showing Result and Response Rate columns](/images/pbx/glance-at-campaign-result.png) - For a full delivery breakdown, click the details icon ![Details](/images/pbx/detail.png). ![Detailed delivery report for a completed campaign](/images/pbx/view-campaign-details.png)