/
Meta for Whatsapp Channel

Meta for Whatsapp Channel

Owned by Product Knowledge
Last updated: Jun 30, 2025

On this page

 What’s about

You can use WhatsApp Channel to manage inbound and outbound interactions, by configuring Meta Connector as provider.

Requirements

  • The Motion instance must have a public address accessible via HTTPS. For security reasons, we strongly recommend using a Reverse Proxy → find out more

  • You have to register an app as Meta Developers → find more details in next paragraph

  • You need a Meta Business Suite account

  • For interactions management you need to consult the official documentation of the selected provider to check prices: find out Meta's documentation here (and pricing updates here)

Video Tutorial

How to Create an App for WhatsApp

To set up Meta Connector, you need to be logged in Meta and registered as Meta Developers on http://developers.facebook.com to create an App for WhatsApp.
By entering in your Meta account as Meta for Developers, you need to create an app.

image-20250507-123309.png
image-20250507-123334.png

 

Firstly, you can click on My Apps → Create app

image-20250507-123505.png

 

Then you can define the App name that will show on your My Apps page and associated with your app ID. You can change the name later in Settings.

And you can indicate the App contact email.
Then click on Next

 

 

image-20250507-123825.png

 

As use cases you need to select Other

  • Select Business

image-20250507-124020.png

 

  • Choose display name for your app and app contact email

  • Connect the app with your Account Business Manager (optional)

  • Create the app

  • Then, you need to add products to your app.
    You have to choose WhatsApp to configure integration and click on Set up
    (Find our Meta documentation here)

  • Click on “Start using the API” to proceed with API Configuration

image-20250507-124542.png

 

You will view this visualisation:

  • You can generate an Access Token (you will use this token in your API requests to authenticate yourself) but consider that this token expires after 24h so you can create a permanent token, by following these guidelines

  • You can run a Test API Request, by using WhatsApp console to send the test message and verify if the integration works correctly:

    1. Select in From the created WhatsApp Business number

    2. Fill in the field To with recipient number to which to send the template “hello_world”

    3. Click the button Send message

Consider that if you use a test number, you can define a maximum of 5 recipients phone numbers

  • So verify that the recipient has received it correctly

image-20241111-144943.png

  • Otherwise you can make a request curl with WhatsApp API, by using the token generated in an API call to verify that the setup is complete

 

  • Then on step 5 you will be able to click on section Add a phone number

 

 

 

You can insert:

  • WhatsApp Business display name

  • Choose a time zone

  • Business category

 

  • You add WhatsApp phone number, by choosing prefix and, according to the selected option, you will receive a text message with a pin code or a phone call to verify your number
    You can explore Meta documentation about how to register business phone numbers

  • Moreover, it is mandatory to configure a payment method

After creating the number and associating a payment method, Meta console will display a message like this:
Congratulations! Your display name XcallyTest was approved. Download and connect your phone number certificate to send messages to your customers.

For certificate management of WhatsApp Cloud API solution (which does not require an on-premise installation), it is NOT necessary to upload a certificate manually. In fact, Meta takes care of authentication and security management directly in the cloud platform.
So to link the phone number, just send a test message (using the default generated “hello_world” template).

Once you send the first test message, you will receive an email like this:

image-20241111-145200.png

Creation of WhatsApp Account on XCALLY

By entering in your XCALLY environment, you can go on WhatsApp Channel → WhatsApp Accounts to create a new account for outbound campaign

 

Click on button and enter:

  • Account Name

  • Key: identification code of maximum 5 characters

  • List: Contact Manager list used to associate contacts. When you run campaigns, contacts are added to this Master List, so it’s possible to have a unique customer journey with all customer touchpoints with outbound campaigns.

For all contacts in the Master List to be usable, it is necessary that they contain in the Phone Field the WhatsApp number

  • Proxy or Motion Domain: server address

  • Type Meta

     

image-20240502-152300.png

 

You can copy these data from your Business Meta account

  • Account SID = ID Account WhatsApp Business

  • Auth Token = Access Token ( you need to create a Permanent Access Token to use WhatsApp correctly because access token expires after 24 hours. Follow these guidelines)

  • AppId = ID app

  • Phone number Id = ID phone number

  • Phone number with prefix (with +)

  • Click on Add

 

How to create a permanent token

With your Developer Account, to create a Permanent Access Token, you can follow Meta guidelines to create a System User with specific permissions.

image-20250507-132211.png

So by opening your Business Settings, you can select the desired business manager

 

image-20250507-132409.png

 

Go to Users → System users to create a new one, clicking on Add.

 

image-20240228-142250.png

 

Then you give a System Username and you choose “Admin” as User Role

Screenshot 2025-03-05 093531-20250305-083531.png

  • You can click on Assign Assets and on Select asset type you choose Apps

image-20250305-085342.png

  • You select WhatsApp created app, by enabling full control Manage app

Remember that you can create only 1 system user for Business account. However, if you generate more WhatsApp apps, and you click on Generate new token, the system allows you to select the app for which you want to create a permanent token

Screenshot 2025-03-05 093727-20250305-083727.png

  • So you can click on Generate Token, by selecting your App

Screenshot 2025-03-05 093736-20250305-083736.png

  • Set “Never” as token expiration

image-20250513-074148.png

 

 

  • You need to add these permits:

    • WhatsApp_business_messaging

    • business_management

    • pages_show_list

    • pages_messaging

    • WhatsApp_business_management

    • pages_manage_metadata

And click on "Generate Token" to obtain a permanent token to paste on auth token section

Configuration of created account

After account creation, you can edit it:

  • on Settings tab you will see all information inserted before

Moreover, you will view Receive URL, an auto-generated API string you need to use to receive the messages inside your account from your WhatsApp Channel provider: click the clipboard button to copy it and then on your Meta Account you need to Configure webhook

By clicking on Configure webhook, you need to insert callback URL (paste here code copied before) + verify token that you can copy from advanced tab of your XCALLY account

To configure correctly your callback URL, your server must have HTTPS certificate.
Sometimes can happen that Meta marks some domain as blacklist. In that case we suggest you to contact Meta support.

 

image-20250513-090142.png
image-20250513-090333.png
image-20250513-090400.png

 

In addition to Callback URL, it is necessary to subscribe some webhook fields, by clicking on Manage to insert these fields:

  • account_alerts

  • account_update

  • message_template_status_update

  • messages

  • template_category_update

  • on Advanced tab

You can see info about proxy and token number

You can enable mandatory disposition and you can select Recontact Template

  • on Dispositions and Canned Answers you can create specific dispositions/canned answers for this account

 

  • on Actions you have to create dialplan to pass interactions to relative queue

Obviously, you have to associate agents to queue and WhatsApp account that you want, otherwise they can’t manage interactions

  • on Interactions tab, you can see campaign interactions and relative status (explore more here)

 

Upgrade API version

Starting from version 3.53.0, API version v23 is supported.
To upgrade your WhatsApp Meta API to the latest version (v23), follow the steps below:

  • Open your app in the Meta Developer Dashboard.

  • In the sidebar, navigate to App settings → Advanced → View Upgrade API version.

  • From the dropdown menu, select v23 as the API version for your app.

image-20250625-082526.png

  • click Save Changes to apply the upgrade. This change will apply to all users of the app.

Use WhatsApp Channel with Meta for Agents

For Agents, the feature is available on WhatsApp Channel section, from which they have to select accounts.
In fact, agents need to be associated to the created Meta account to receive new interactions

When a new inbound interaction arrives, the agent will see a popup with information about the account, queue and sender phone number.

Agent can manage the conversation directly on Omnidesktop interface

For outbound campaigns, explore the relative section, at this link

Phone and mobile contact fields management

We highly recommend to insert the same number in phone and mobile fields to use WhatsApp channel

 

Remember that:

  • outbound Meta campaigns send message to phone field

  • single messages sent by agent consider mobile field

Starting from version 3.50.0, if contact is missing phone or mobile field, now agent can send message.

In the contact finder modal, the search both by phone number and by mobile has been implemented.

image-20250424-150251.png

In fact from version 3.50.0 if contacts have only mobile or phone field filled in, automatically the system sets the other field consequently with the same number.

Scenarios:

  • Message to a contact with only phone field → chat created/message sent (phone number set on mobile)

  • Message to a contact with only mobile field → chat created/message sent (mobile number set on phone)

  • Message to a contact with the same mobile and phone → chat created/message sent

  • Message to a contact with different mobile and phone → a toasty warning is shown. If it is a single message sent by agent, the number considered is the mobile one.

  • Message to a new phone number by writing it in the bar → chat created/message sent (phone number and mobile set equal)

 

Related topics