Modules
WhatsApp

WhatsApp

Overview

This feature integrates with WhatsApp Business Platform. WhatsApp Business Platform is a service provided by Meta (formerly Facebook) that enables businesses to communicate with their customers on WhatsApp. The service is designed to help businesses manage customer conversations at scale, and to provide a more efficient and secure way to communicate with customers. Note that WhatsApp Business Platform is distinct from WhatsApp Business and WhatsApp that you may have on your phone. Refer to https://business.whatsapp.com/products/business-platform (opens in a new tab).

With WhatsApp Business Platform you communicate with your contacts using a service such as EIIƎ. You do not use a WhatsApp app directly. The platform provides opportunities to manage and automate messaging at scale. Your WhatsApp Business Platform will ues one (or more) dedicated business phone number not linked to other WA accounts. The account is owned by your business.

Meta has multiple policies to protect the WhatsApp brand that affect how you can use the service. Users of this service need to be aware of the policies.

  • Businesses must maintain opt-in records before messaging users, and only message users that opted in.
  • You typically initiate a conversation with a template message. You can continue a conversation with text / chat messages within 24 hours of an inbound message. Thereafter, continue or start a new conversation with a template message.
  • Initiate conversation with template messages

The EIIƎ integration helps you and your business to comply with features for managing opt-in records, sending template messages and continuing conversations in 24-hour chat windows.

You can create and manage templates from your WhatsApp Business Account.

Concepts

Key Meta / WhatsApp concepts & terms to be familiar with: WhatsApp Business Platform

  • distinct form WhatsApp (consumer) app and WhatsApp Business app.
  • WhatsApp Business Account - and associated WABA_ID
  • App 'owned by' the WhatsApp Business Account, and the app_id
  • Phone number(s) linked to the WABA - Opt-in / Consent
  • Templates, managing templates, template approval, sending template messages
  • Components of templates & template messages
  • Conversation windows (rolling 24h window)
  • Sending text messages
  • Messaging Limits : https://developers.facebook.com/docs/whatsapp/messaging-limits/ (opens in a new tab)
  • Webhooks from WhatsApp
  • Access Key
  • Shared WABA vs On Behalf-of models

App Features

Opt-in records

A feature enabling our customers to manage opt-in records of their customers. Meta mandates that all recipients of messages have opted in to receive the category of message that you send them. The app feature provides for records of consent covering scope (the category of message they opt-in to receive), consent language, date opted in, any message and / or document, consent medium, phone number, referrer, opted out date and reason.

Contact Groups

A feature to create and manage groups of contacts to send template messages to. Each group has a name and scope (aligned to WhatsApp template categories). Groups are then list of members. Only members with an active opt-in to the scope can be added to the group. (Note : we currently do not automatically remove members from the group if they withdraw consent...) Be aware of messaging limits imposed by Meta. By default, business phone numbers are initially limited to 250 business-initiated conversations in a 24 hour period, increasing to 1000 customers/24h after validation. See this page for Meta information on messaging limits: https://developers.facebook.com/docs/whatsapp/messaging-limits/ (opens in a new tab) Sending a template message to a group of 10 members counts as 10 business-initiated conversations.

EIIƎ App limitations...TBD

WhatsApp Templates

This is accessible from the WhatsApp pop-up selecting the view/edit button next to the template selector. The view is a selected table view of templates available to the customer's WhatsApp Business Account. Data here is fetched from the meta API. Selecting a template displays a preview of the template with a list of the parameters of the templates. This includes dynamic parameters for url type buttons on templates. Note users cannot edit templates within the app. Head over to WhatsApp Business Manager page (Meta) to manage templates.

WhatsApp Pop-up

Provides tabs to send template messages, and to view / continue conversations. This is currently implemented as a pop-up dialog, but may be better suited to a page. Access this using the WhatsApp icon/menu item from the 'My Communications' tray on the nav bar.

Send WhatsApp Template tab:

This includes a selector for choosing templates, a preview of the template, feature to manage parameters, selector to choose which number to send from and selectors to send to individual or send to group. The Template selector lists the approved templates linked to the WABA. View/Edit button adjacent takes user to the WhatsApp Templates view.

Selecting a template displays a preview of the template, including header, body, footer and any buttons.

If the template has parameters uses can update these parameters in the tool below the preview. A slider allows user to display the placeholders in the preview or the parameter values. The list of parameters is derived from the template definition as retrieved from the API. Users can edit the parameters directly and see the changes in the preview.

The app records a history of parameters previously used with the template. A history button displays a list of the 5 most recent outgoing messages and the example parameters configured in the template definition. Selecting from the list updates all parameters to the selected version. The app design includes DB_SCHEMA.whatsapp_template_message table and DB_SCHEMA.whatsapp_template_message_top5 view to store and retrieve this data set.

When sending the same template to a group of users it may be necessary to personalise the message to the individual. The app includes a feature to set any field to first name, last name or name of the individual based on their contact record. Note this feature is only applicable when sending to groups. The app design handles this by setting the parameter to {{first_name}} in this view, then processing this in the back end substituting with data from the contact.

A business may have more than one phone number available to send messages from, as configured in WhatsApp Business Account. These can be configured in EIIƎ. If more than one number is configured then users will see a Send From selector, enabling them to select which number to send from. If the configuration has only one number then this selector is not displayed.

Send to Individual tab selector shows a contact selector. This lists the contacts with opt-in records for the category of the template. View/edit button navigates to the Opt-In Records view. The app design retrieves the contact's phone number from the opt-in.

Send to Group tab selector shows a group selector, listing groups with scope matching the template scope. View/edit button navigates to the Contact Groups view. Selecting a group displays a list of group members (list is collapsed by default). Form has basic number check, alerting users if any phone numbers in the opt-in records are incomplete.

WhatsApp Conversation (Chat) tab:

The Conversations tab provides a list of opted-in contacts and a chat window.

Contacts lists initials all users with active WhatsApp opt-in. Hover over the initials to se additional contact detail. Reduce the list by entering any filter. An icon adjacent to the i will show if there is any conversation history, if a conversation is within the 24h window since last inbound message, and pending if the most recent message was inbound and within the 24h window. The list sorts with most recent inbound message at the top. Hide or show the contact list by toggling the chevron button.

Selecting any contact will display the conversation history in a chat window. Chat window shows inbound and outbound messages, including outbound template messages. Most recent messages are at the bottom. Ticks next to the outbound messages show delivered, read or fail to send status.

If the conversation is within the window you can send text messages using the input at the bottom of the view. If your business has multiple WhatsApp phone numbers configured then select the phone number to use.

New inbound and outbound messages will show at the bottom of the list.

Configuration data

The app integrates with WhatsApp Business Platform using information from the customer's WhatsApp Business Account, a system access token and an 'app' configured in WhatsApp developer section. Information required for the app is:

  • WhatsApp Business Account (WABA) ID. EIIƎ app will use this to request list of templates available to use.

  • Each customer requires a WhatsApp App configured on the WABA. IPGN Solutions can assist with this, if required. This will include details such as a logo, link to customer's privacy statement and terms indicating conformance with Meta WhatsApp policy requirements. Customers should complete business verification for the app, and enter Customer's Data Protection Officer for GDPR conformance. Setup webhooks to connect to IPGN webhook receiver. Subscribe to messages webhooks.

  • System access token, created by system user for the account. The token must be linked to this app. EIIƎ app will use this to authorise requests and posts sent to the WhatsApp API on behalf of the WABA.

  • WhatsApp phone number(s) linked to the (WABA), with the associated phone number whatsapp_id. EIIƎ app will use this in requests to send messages.

  • Customer should prepare message templates. These templates can then be sent using the EIIƎ app interface.

Setting up your WhatsApp Business Account

This is an outline of instructions to customers for setting up their WhatsApp Business Platform for integration to EIIƎ app.

The EIIƎ app will integrate with your WhatsApp Business Account. This requires a WhatsApp Business Account (WABA) and a WhatsApp App. This section outlines the steps to set up the WhatsApp Business Account and the WhatsApp App.

What you need from IPGN

IPGN will provide you with the following information:

  • WhatsApp App ID & App Name prepared by IPGN
  • IPGN Solutions Business ID
  • Webhook receiver URL & App Verification Token

You will need

  • Access to your Meta Business Suite with admin rights
  • Phone number, not linked to other WhatsApp, capable of receiving voice and / or text
  • Credit card (this may already be setup in your Meta Business Suite).
  • Contact email about the Meta app (Meta may send important messages about updates, violations, enforcements and account recovery to this address. Please use an actively monitored address that can be used to send and receive emails. Do not enter an email alias.)
  • Logo (1024 x 1024). (You can upload a JPG, GIF, or PNG file. The size of the image must be between 512 x 512 and 1024 x 1024 pixels. File size limit 5 MB.)
  • Link / URL to your privacy policy and to your terms of service.
  • Data Protection Officer details

Steps

Go to Meta Business Suite: https://business.facebook.com/ (opens in a new tab) Go to settings for the business asset - ours set with 2FA - recommended.

Create a WhatsApp Business Account

Under accounts, go to WhatsApp accounts. Add a new WhatsApp account - you'll be prompted for a phone number (not linked to any other WhatsApp account). From this view you can access Payment settings and WhatsApp Manager. Go to Payment settings, then Payment Methods, and add payment method (credit card) if necessary.

Create a WhatsApp App

Go back to Settings for the Business Portfolio https://business.facebook.com/latest/settings (opens in a new tab), under Accounts select Apps.

Select Add, then Connect an App ID. Connect to App ID provided by IPGN.

Share with IPGN

Back in the Portfolio settings https://business.facebook.com/latest/settings (opens in a new tab), go to Users -> Partners and Add - Give Partners access to your assets. Enter our business ID. Share assets ... Select Apps, Share app that you added.

App & Webhooks

The next stages require a Meta developer account.

This can be by customer, or customer can nominate IPGN - either via partner route or by adding an IPGN team member as a user.

If required, create a developer account: https://developers.facebook.com/docs/development/register (opens in a new tab).

You can go direct here if you have a developer account: https://developers.facebook.com/ (opens in a new tab).

Developers requires access to the new app

Go to the apps page: https://developers.facebook.com/apps (opens in a new tab). If the OGV in EIIƎ app is there then we're good, otherwise we need to add you as a user to the WhatsApp account - go to the account at https://business.facebook.com/latest/settings/whatsapp_account (opens in a new tab), select the app then People and add. If the user isn't in the list of options, then go up to the business portfolio settings, Users -> People and invite the developer.

In the Developer side, access the new App.

Complete App settings - basic, including:

  • contact email
  • logo
  • URLs for privacy and terms.

Advance settings as default should be fine.

Jump down to the WhatsApp section

QuickStart - should be complete (may need to link the app to the WhatsApp business account)

API setup - we'll test sending a message from here.

  • Generate access token (this will be a temporary token - we'll update this later)
  • From - should display the number entered when setting up the WhatsApp business account
  • To - in Development mode the number may need verified
  • Select Send Message - watch for result!

Go to Configuration - this is where we connect the WhatsApp messaging to the EIIƎ app backend.

  • Enter the staging callback URL and token provided by IPGN, then Verify & Save.
  • Scroll down the list to messages, select v20.0 (if it's an option) and switch to Subscribed. Keep a note of the API version number you selected and share this with IPGN. This instructs the Meta WhatsApp app to send messages to the EIIƎ app backend.

Next, create the permanent token. We'll use this token to authorise your EIIƎ configuration to send messages (and request templates) on your behalf:

Go back to portfolio settings https://business.facebook.com/latest/settings (opens in a new tab)

Go to Users -> System users. If there isn't an Admin user already then add one.

Select the Admin user.

We'll add the new app as an assigned asset, if it's not already there.

  • Click the ... (3 dots) button and select Assign Assets.

Choose the app, select Develop App access and hit Assign assets.

Then, generate the access token.

  • Select the app,
  • Chose token expiry as Never (otherwise we all have to generate new tokens and update the EIIƎ configuration before the token expires in 60 days. We will forget and the app will stop working!).
  • Select whatsapp_business_management and whatsapp_business_messaging permissions.
  • Generate token. Be sure to copy the token!

Finally, go back to the app in developer mode and switch the app from Development to Live.

Share with IPGN:

  • WABA ID
  • WhatsApp phone number & phone id
  • Webhook API version number.
  • System Access Token

EIIƎ Setup

Setup currently requires manual setup of entries in database tables. - We'll save an encrypted version of the customer's access token. Encrypt the token using the api-key-encryptor app (https://github.com/ipgn/api-key-encryptor (opens in a new tab)). Follow the instructions in the README.MD file. You'll need the IPGNS_256_KEY to use to encrypt the token. This is the key used by the app to decrypt the token, and also for encrypting / decrypting text message content - app_data.whatsapp_account : add tenant, WABA_ID, is_active status and the encrypted access token as token_256. - app_data.customer_access: Create / review the following ensuring is_in_plan is checked: - app_route: navbar, card: WhatsApp - app_route: directory, card: OptInTab & card: ContactsGroupTab - DB_SCHEMA.app_view_config: create / reveiw entries ensuring is_enabled is checked: - app_route: navbar, card: WhatsApp - app_route: directory, card: OptInTab & card: ContactsGroupTab - DB_SCHEMA.whatsapp_e2e_phone: add entries of phone_name, phone_number, whatsapp_id for each business phone number to be used to send. Create Opt-in records and contact groups as required.

FAQs

Obtaining consent

Q: How do I obtain consent from my customers to send them messages on WhatsApp?

A: While WhatsApp does require businesses to obtain and maintain records of user consent, sending a template message specifically to request consent is generally not permitted. Here's why:

The initial message requesting consent would itself require prior consent, creating a circular dependency. This would go against Meta's policy requirements. Instead, businesses should obtain consent through other channels first, such as:

  • Website opt-ins
  • During in-person interactions
  • Through existing customer relationships
  • Via other communication channels where you already have permission to contact them
  • During the normal course of business interactions

Once you have obtained consent through appropriate channels, you can then use WhatsApp Business Platform to communicate with those contacts who have provided explicit consent.

Reference

CommunicationsAccount