WhatsApp

Serve and engage your customers on the most popular social messaging channel available in the market today.

With more than 2 billion monthly users and counting, WhatsApp is arguably the most popular consumer messaging and communication app in the market today. This tutorial walks you through the process of configuring your WhatsApp Business Account on Webex Connect.

Register for an Official Account on WhatsApp

📘

Embedded Sign-Up for WhatsApp Asset Creation

Please note that we now support and recommend WhatsApp Embedded Sign-Up for adding new WhatsApp assets on Webex Connect. Manual onboarding option that we supported previously is being phased out and may no longer be available in your tenant. If you need assistance in setting up a WABA, get in touch with us using Contact Support information mentioned in your Webex Connect account.

In the Embedded Sign-up process, you just need a phone number; phone number certificate is not needed.

You can use a phone number that is already registered in the Android, iPhone, or Business application versions of WhatsApp. However, in order to register this phone number with us, you need to follow the steps below to delete the WhatsApp account associated with that phone number mentioned here

Configure WhatsApp App Asset on Webex Connect

  1. To configure the WhatsApp app, sign in to the Webex Connect platform, go to Assets > Apps .
  1. On the Apps page, click the Configure New App button and choose WhatsApp from the drop-down list of apps.
  1. Enter the name of the WhatsApp account in the Name field on the Configure New App page.
  2. Select the Sign-up Method: Sign-up with Facebook (Embedded Sign-up Onboarding) or Manual.

If you selected Sign-up with Facebook in the step 4 above, follow the below embedded signup process.

Embedded Sign-up

Using the embedded signup feature, the Business can onboard to the WhatsApp Business Platform directly from the Webex Connect WhatsApp App Creation page.

Prerequisites

The following are the prerequisites for the embedded signup:

  • A valid Facebook account.
  • Facebook business account with administrator access. If you do not have a business account already, you can create one during the signup process.
  • A valid phone number, which you can register as a sender. Note that you should not have any private or business WhatsApp account configured with this number. You also must have this number handy, because you’ll receive an SMS or a voice call during the verification process.
  • In addition, you’ll need the following details:
    • Business Phone Number
    • Company Name
    • Representative’s Email Address
    • Address
    • City
    • State / Province / Region
    • Country
    • Website
    • Business number Display Name
    • Business Category
    • Business Description

Before You Begin

This section briefs the guidelines you must follow during the signup and verification.

Phone Number

Make sure your phone number meets all the following requirements that are necessary for WhatsApp:

  • Must be active throughout the verification process, because you will receive an SMS or a voice call with OTP to confirm the number.
  • Must not be a short code or a toll-free number.
  • Must not be associated with any other WhatsApp Business Account.

What is Phone Number Display Name?

This is the display name which your customers see on your WhatsApp Business profile. Whenever you add a phone number to your WABA, you are prompted to add a display name for it as part of Embedded signup pop-up.

Display names should be related to your business and must not violate WhatsApp Commerce and Business policies. In addition, the display name must comply with formatting guidelines. Refers to this page for comprehensive guidelines.

Business verification and Display Name review

Business verification and WhatsApp Business Display name review aren’t required now as a mandatory step to start messaging on WhatsApp. After signup an automated compliance check with the WhatsApp Business Platform Policy is conducted. Following which you can immediately start sending messages to customers.

📘

When to initiate Business verification?

You are only required to initiate the business verification process when you’re ready to scale your business-initiated conversations or request to become a WhatsApp Official Business Account.

After the business verification is complete, the display name review for all phone numbers associated with your account will be initiated. Once the display name review is initiated, any new display name change will have to be reviewed and approved before it can be used.

Once the business verification is completed and the display names for all phone numbers are approved, your business can have increased messaging and phone number limits.

Embedded Sign-up Onboarding

  1. Select Sign-in with Facebook on Select Sign-up Method within the WhatsApp apps page.
  1. Click Add WhatsApp Business. You can use the existing account or create a new account.
  1. Click Get Started.
  1. Click Continue.
  2. Select the existing Meta Business Account or Create a new Meta business account.
  1. Click Continue.
  2. Select the existing WhatsApp Business account (WABA) or Create new WhatsApp Business account.
    Click Continue. A confirmation page appears.
  1. Click Continue to Step2.
  1. Select the existing WhatsApp Business Profile or create a profile.
  2. Click Continue.
  1. Select the existing WhatsApp number or create a number to integrate to your WhatsApp Business Account and click Next.
  1. When prompted, enter the OTP to confirm the number.
  2. The screen shows that the information is being processed.
  1. Once the process is done, Steps to verify your business screen appears.
  1. Click one of the following:
  • Verify in Facebook: a new tab opens with the verification screen. Complete the verification.
  • Done with Verification? Proceed: takes you to Step 20.
  • Skip Verification: displays the following screen. Click Proceed.

    📘

    Note

    If you skip the verification, you can only send notifications to two numbers and have 10 customer -initiated conversations. Once you submit the documents for verification, you will be allowed for 1500 customer - initiated conversations.

  1. The Setup process for your WhatsApp Business Account starts.
  1. On the Fetched WABA ID’s screen, click Integrate with Webex Connect associated with the account you would like to integrate.
  1. Once the permission to manage account is received, the phone numbers associated with the WABA are fetched. Select the number you want to integrate and click Integrate with imi.
  1. Once the pre-approved templates are added and the shared IMI’s credit line with WABA is set up, the screen shows a Ready for Setup message.

    📘

    Note

    Credit line cannot be changed after being attached to a WABA. If you have integrated with a different credit line in the past, you must create a new WABA to use Webex Connect's credit line and then migrate the phone numbers to the new WABA if needed.

  2. Go to your tenant and navigate to AssetsApps. Select WhatsApp from App Type.
  3. Select the WhatsApp number that is integrated using the above steps.
  4. On the Mange WhatsApp page:
    • The credentials that are approved show the Approved icon.
    • The credentials that are pending approval show the Pending-approval icon.
    • The credentials that are rejected show the Rejected icon.

📘

Note:

WhatsApp allows you to use two numbers without having to verify, with limited conversations and limited number of transactions.

Manual Sign-up

For the manual configuration, answer a few short questions here and we'll get in touch with you! In order to configure WhatsApp account for business, you need a new mobile number and obtain a WABA certificate to verify the business contact WhatsApp number.

If you selected Manual in the step 4 of the procedure above, follow the below procedure:
a. Enter the name of the WhatsApp account in the Name field on the Configure New App page.
b. Choose the relevant country code from the drop-down list box in the Credentials section and enter the purchased phone number in the Number field.

1609

Configure New WhatsApp App

c. Enter the WhatsApp Business Account ID (WABA ID) obtained from the support team/your account manager. The WABA ID identifies the templates available for a specific mobile number.

📘

Note

You can create your own template via tools -> templates section in the platform, which needs to be approved by the WhatsApp. Once approved it will be available in the send node. In other words, every template message should be registered in business manager to be send to the customers.
You don't need to manually refresh WhatsApp template registration status.
The status will be refreshed automatically on the UI as soon as WhatsApp provides an update.
You can also view the reason for rejection in case a WhatsApp template is rejected.

d. Register your purchased mobile number to get a unique certificate that you provide in the Certificate field. If you require any assistance with the certificate, write to the support team / your account manager.

e. Click Create. A notification will be displayed on the top of the screen.

Once the verification is complete, you can see your WhatsApp app on the Apps page.

After the app is created the following notification is displayed.

If your app is not created, one of the following messages is displayed.

f. Choose Text or Voice as the Verification Type and click the Verify Number button on the bottom-left of the screen to verify your account and complete the configuration.
The OTP initiates few minutes after clicking Verify Number and is valid within 24 hours after it was initiated.

Once the verification is complete, you can see your WhatsApp app on the Apps page.

🚧

Verification OTP on Virtual numbers - WhatsApp

If you are using a virtual number you can face issues receiving verification SMS/Voice OTP. Please contact your regional support contact/account manager for assistance on setting up your WhatsApp app.

Request to become WhatsApp Official Business Account

If your business desires to have an WhatsApp Official Business Account, it must be considered a notable business that has a substantial presence in news articles from publications with sizable audiences. WhatsApp Official Business Accounts are issued for phone numbers. With the same phone number, you can use the current or a new business name to apply for the WhatsApp Official Business Account.

Once you have initiated business verification, please reach out to your support contact it you intend to become a WhatsApp Official Business Account.

Learn more

Start messaging immediately

You can start messaging customers immediately and only need to complete Business Verification when you are ready to scale business-initiated conversations or request to become an Official Business Account (OBA).

After completing Embedded Signup or the Manual onboarding (OBO model) processes, businesses can immediately:

  • Respond to unlimited customer-initiated conversations (24-hour messaging windows).
  • Send business-initiated conversations to 250 unique customers in a rolling 24-hour period.
  • Register up to two (2) phone numbers.

Edit/Manage the WhatsApp App Asset

  1. Go to Assets > Apps.
  2. Search for the WhatsApp that you want to edit and click Manage in the drop-down list box at the right to manage the settings of this app.

You see the Manage – WhatsApp page, where you can manage the settings of the app.

🚧

Managing WhatsApp account settings

Please use the Manage - WhatsApp page of the Webex Connect platform for updating the Business Account Settings. Although you can access your WABA from within the WhatsApp Manager portal if you have onboarded using the Embedded signup model, the following updates made from the WhatsApp Manager portal can impact your existing services - Business Account Settings, Template content, or the two-factor authentication settings.

📘

Embedded Sign-Up for WhatsApp Asset Creation

Please note that we now support and recommend WhatsApp Embedded Sign-Up for adding new WhatsApp assets on Webex Connect. Manual onboarding option that we supported previously is being phased out and may no longer be available in your tenant. If you need assistance in setting up a WABA, get in touch with us using Contact Support information mentioned in your Webex Connect account.

Business Account Settings

You can register the details of the business account like the About, Address, Business Category, Contact Email, Business Description, Website URL 1 (the primary website), and Website URL 2 (the secondary website). Click the Upload button to browse and select an image that will be displayed as the logo.

As per the WhatsApp guidelines, when you upload the image, the WhatsApp Business Platform Client will scale and crop the uploaded the profile pic and render it as a square image. Therefore, the image that you use for your business logo must comply with the following:

  • Maximum size of 5 MB
  • Image height or width not less than 192 px
  • Image resolution of 640x640.

These business account settings appear to the users when they view your business profile on WhatsApp.

Refer to the screenshot below:

🚧

Managing Business Account Settings

Please use the Manage - WhatsApp page - Business Account Settings section of the Webex Connect platform to update any Business profile information. Although you can access your WABA from within the WhatsApp Manager portal if you have onboarded using the Embedded signup model, it may impact your existing services.

Message Us Plugin

The Message Us plugin renders a Message Us button on your WhatsApp business profile page. This button, when clicked by the users, enables the users to open a conversation with the business on the configured WhatsApp Business Account. Use the following code sample on your website to allow users to contact you on your configured WhatsApp Business Account through the Message Us button.

<div class="wa-message-us" number="<YOUR_WHATSAPP_NUMBER>"
    label="<CUSTOM_BUTTON_LABEL>"
    pre_filled_message="<CUSTOM_PREFILLED_MESSAGE>"
    color="<teal | green | white>"
    size="<standard | compact>"
    border_radius="<VALUE_IN_PX_OR_%>"
    <script src="https://imiconnect.io/whatsapp/message-us-btn.min.js" type="text/javascript">
    </script>
    </div>
1192

Message Us Plugin

For e.g. use the following code to generate a standard size WhatsApp Message Us button in green color:

<div class="wa-message-us" number="9180xxxxxxxx"
    label="Message Us"
    pre_filled_message="Hi there"
    color="green"
    size="standard"
    border_radius="5px">
</div>
    <script src="https://apptray-uk.imiconnect.io/WhatsApp/WhatsAppPlugin.js" type="text/javascript">
    </script>

Click the Save button to complete the configuration.

Using the Channel

User Identity

To message users on WhatsApp you will need the users WA ID. This is the MSISDN that the customer uses on WhatsApp.

Getting Opt-Ins

You are required to obtain opt-in before opening marketing, utility, and authentication conversations with customers outside the 24-hour window. You can obtain opt-in in a multitude of ways, both on and off WhatsApp.

The following are examples of supported opt-in methods:

  • SMS
  • Website
  • In a WhatsApp thread
  • By phone (using an interactive voice response (IVR) flow)
  • In person or on paper (customers can sign a physical document to opt in)

We strongly recommend that businesses continue to optimize for the user experience when designing opt-in flows.

API

Here is a Postman collection to test our APIs. Make sure you change the key in the header to your service key.

Latest Collection: Run in Postman

Archived Collection: Refer Postman Collection

Download Postman from here

Webhooks

Once a WhatsApp app is configured, you can configure Outbound Webhooks by choosing the WhatsApp app from the entity dropdown to receive incoming messages and events from your customers.

{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_155054536910425280",
    "event": "MO",
    "waid": "919949452xxx",
    "message": "Hello",
    "attachments": "[]",
    "system": "",
    "location": "",
    "contact":"",
    "ts": "2019-03-03T07:40:51.297Z",
    "tid": "0cab6280-9d98-0041-4877-0bde6515b15a_0"
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_154623235593581600",
    "event": "MO",
    "waid": "918790725685",
    "message": "",
    "attachments": "[{\"mime_type\":\"image/jpeg\",\"url\":\"https://stgrtmedia.s3.amazonaws.com/a_154623235593581600/d3aa15e8-93ee-4e79-bb31-0ad3f0fe7430.jpg\"}]",
    "system": "",
    "location": "",
    "ts": "2019-01-03T09:04:42.726Z",
    "tid": "5b11ed3b-36fb-9336-bb58-11429b0b78aa_0"
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_154623235593581600",
    "event": "MO",
    "waid": "918790725685",
    "message": "",
    "attachments": "[{\"mime_type\":\"audio/ogg; codecs=opus\",\"url\":\"https://stgrtmedia.s3.amazonaws.com/a_154623235593581600/0f35e14a-0c1f-4544-ba02-5d06382de7de\"}]",
    "system": "",
    "location": "",
    "ts": "2019-01-03T09:16:22.638Z",
    "tid": "8beb0302-ccbf-4e5f-ecc9-049db9212029_0"
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_154623235593581600",
    "event": "MO",
    "waid": "918790725685",
    "message": "",
    "attachments": "[{\"mime_type\":\"video/mp4\",\"url\":\"https://stgrtmedia.s3.amazonaws.com/a_154623235593581600/aa9b851f-94b6-49f6-878c-ea8a8d7b3098.mp4\"}]",
    "system": "",
    "location": "",
    "ts": "2019-01-03T09:23:26.386Z",
    "tid": "ff0f3e02-e812-22f7-dc15-dba71dabde53_0"
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_154529859479452060",
    "event": "MO",
    "waid": "918790725685",
    "message": "",
    "attachments": "[]",
    "system": "",
    "location": "{\"address\":\"Plot No. 770, Road No. 44, Jubilee Hills, Hyderabad\",\"latitude\":\"17.434901060022\",\"name\":\"Imimobile\",\"url\":\"https://www.facebook.com/pages/Imimobile/204627936239899\",\"longitude\":\"78.398435572505\"}",
    "ts": "2019-01-08T08:59:02.717Z",
    "tid": "3beecbfb-73fd-803e-a27f-4e797fb22ffd_
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_154623235593581600",
    "event": "MO",
    "waid": "918790725685",
    "message": "",
    "attachments": "[{\"mime_type\":\"application/msword\",\"caption\":\"This is PPT-1\",\"url\":\"https://stgrtmedia.s3.amazonaws.com/a_154623235593581600/21bb5a4a-fd0e-47d3-a02d-b1af0eddbe88.ppt\"}]",
    "system": "",
    "location": "",
    "ts": "2019-01-03T08:59:16.192Z",
    "tid": "5a7898e0-d80b-7316-dd80-7849f84fa304_0"
    
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_160981352754574140",
    "event": "MO",
    "waid": "919963585090",
    "message": "",
    "attachments": "[]",
    "system": "",
    "location": "",
    "ts": "2021-02-11T10:06:30.824Z",
    "tid": "9052b6d0-7b98-0902-b24c-195cde666ca6_0",
    "contacts": "[{\"birthday\":\"1998-12-03\",\"emails\":[{\"type\":\"INTERNET\",\"email\":\"[email protected]\"}],\"addresses\":[{\"zip\":\"502032\",\"country\":\"India\",\"country_code\":\"in\",\"city\":\"Hyderabad\",\"street\":\"Temple\\\\r\\\\nMain Road\",\"state\":\"Ta\",\"type\":\"HOME\"}],\"urls\":[],\"org\":{\"department\":\"imi\"},\"name\":{\"last_name\":\"Smith\",\"first_name\":\"John\",\"formatted_name\":\"John Smith\"},\"phones\":[{\"phone\":\"+9199634589123\",\"type\":\"HOME\"},{\"phone\":\"+9188635894612\",\"type\":\"WORK\"}]}]",
  
}
{
    "userId": "",
    "channel": "WhatsApp",
    "appId": "a_160981352754574140",
    "event": "postback",
    "waid": "919963585090",
    "ts": "2021-02-10T07:16:36.080Z",
    "tid": "5bbc6f8c-5565-7278-70a0-054ee1fe38f5_0",
    "buttonPayload": "Yes",
    "buttonText": "Yes",
    "errors": "",  
}

To receive delivery receipts of the messages you sent out, configure Outbound Webhooks on the service you sent the message from.

{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "timeStamp": "2019-01-23T14:05:30.068Z",
            "Description": "Sent",
            "code": "7500",
            "deliveryChannel": "whatsapp",
            "additionalInfo": "",
            "destination": "918790725685",
            "destinationType": "waid",
            "deliveryStatus": "Sent"
        },
        "subtid": "",
        "transid": "4d9b61a5-7972-4518-9afe-0c215c8d40a1",
        "callbackData": "",
        "correlationid": ""
    }
}
{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "timeStamp": "2019-01-23T14:05:30.068Z",
            "Description": "Delivered",
            "code": "7500",
            "deliveryChannel": "whatsapp",
            "additionalInfo": "",
            "destination": "918790725685",
            "destinationType": "waid",
            "deliveryStatus": "Delivered"
        },
        "subtid": "",
        "transid": "4d9b61a5-7972-4518-9afe-0c215c8d40a1",
        "callbackData": "",
        "correlationid": ""
    }
}
{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "timeStamp": "2019-01-23T14:05:30.068Z",
            "Description": "Read",
            "code": "7502",
            "deliveryChannel": "whatsapp",
            "additionalInfo": "",
            "destination": "918790725685",
            "destinationType": "waid",
            "deliveryStatus": "Read"
        },
        "subtid": "",
        "transid": "4d9b61a5-7972-4518-9afe-0c215c8d40a1",
        "callbackData": "",
        "correlationid": ""
    }
}
{
    "deliveryInfoNotification": {
        "deliveryInfo": {
            "timeStamp": "2019-01-23T14:03:37.454Z",
            "Description": "Unknown Status",
            "code": "7200",
            "additional_info": [
                {
                    "code": 470,
                    "title": "Failed to send message because you are outside the support window for freeform messages to this user. Please use a valid HSM notification or reconsider."
                }
            ],
            "deliveryChannel": "whatsapp",
            "additionalInfo": "",
            "destination": "918790725685",
            "destinationType": "waid",
            "deliveryStatus": "Failed"
        },
        "subtid": "",
        "transid": "86ffec56-35f1-49e2-adad-68360dc009ef",
        "callbackData": "",
        "correlationid": ""
    }
}

Message Types

WhatsApp supports the following message types:

  1. Text
  2. Media (Image, Video, Document and Sticker)
  3. Location
  4. Contact
  5. Templates

Rules

You can configure based on Trigger events to activate the WhatsApp node.

Trigger eventAction
Incoming MessageSend WhatsApp Message
Forward to BOT

Flow

In a flow, you can configure the Receive node to receive messages from WhatsApp users and the WhatsApp node enables you to deliver messages to the WhatsApp user.

Configuring Outbound Webhook for WhatsApp

To configure a Outbound Webhook for WhatsApp:

  1. Go to Assets → Apps.
  2. Select WhatsApp from the App Type drop-down.
  3. Click the number for which you want to enable the Outbound Webhook.
  1. Click Configure Outbound Webhooks.
    Configure New Integration - Outbound Webhook is displayed.
  1. Enter the Name for the webhook.
  2. Entity is automatically populated.
  3. Select the notifications you want to receive – Incoming Message, Postback, List Message, and/or Reply Buttons Message.
  4. Enter the webhook URL for the Endpoint Configuration.
  5. Select Enable Hub Signature if you want to enable the hub signature and enter all the relevant details.
  6. Click Save.