- Print
- DarkLight
- PDF
WhatsApp Cloud App
- Print
- DarkLight
- PDF
The Rocket.Chat WhatsApp Cloud app provides direct communication between Rocket.Chat and WhatsApp using the WhatsApp Cloud API without needing third-party services like 360Dialog. It is a more secure option and addresses privacy concerns. Your Rocket.Chat workspace is linked through a Facebook developer app with the WhatsApp setup.
Prerequisites
Your workspace must be in a secured, publicly available domain.
Meta developer account to get the WhatsApp API credentials.
Make a Facebook Business account available to link with.
Your workspace must be registered on Rocket.Chat Cloud.
Install WhatsApp Cloud app
To install the WhatsApp Cloud app,
Go to Administration > Apps > Marketplace.
Search for the WhatsApp Cloud app.
Click Install and accept the needed permissions. You receive a message from
whatsapp-cloud.bot
in the#Omnichannel WhatsApp Cloud Setup
channel with setup instructions.
Set up Facebook developer account with WhatsApp
Meta provides developer tools through the Facebook developer's portal to easily build around the Meta ecosystem.
Login to your Facebook developer account and navigate to My Apps
You must verify your account before proceeding if it is your first time accessing Facebook for developers.
Click on Create App to create a new app
Select Business as the App type and fill in the details
App name: The name you want to call your app.
Contact address: Your email to use when contacting you.
Business Account: Select a business account if you have one. A new account can be created automatically if none is selected.
Click on Setup against WhatsApp in the list of products to add displayed. A WhatsApp section is added to the left panel of your Facebook developer dashboard.
Navigate to WhatsApp > API setup. You will find a set of credentials to be used later for setting up the WhatsApp Cloud app in Rocket.Chat. By default, you’re provided with a test phone number, which has a Phone Number ID and WhatsApp Business Account ID. The access token provided is temporary and requires you to refresh periodically, follow these steps to create a permanent token.
Optionally, add any existing WhatsApp number to receive messages while in test mode.
Now that you have obtained your Access Token, Phone Number ID, and WhatsApp Business Account ID, proceed to configure the app and connect your WhatsApp number to the workspace.
Refer to the official Meta guide for detailed steps on setting up your developer account and business app for the WhatsApp Cloud API.
Adding WhatsApp Business phone number to the Facebook app
Optionally, you can link your original WhatsApp Business number to the App.
Navigate to WhatsApp > Getting Started and click on Add phone number.
Follow the guides below to learn more about how to add a WhatsApp production number here:
Add a Phone Number - WhatsApp Business Platform Cloud API Documentation
When you connect a new number to WhatsApp cloud, you receive some free messages per month. If you exceed this quota, your card will be charged. See the official pricing guide to learn more about the billing and free tier. We recommend adding your card details as soon as you connect a new number. This ensures that your service integration won't be disrupted if you go beyond the monthly free limit.
If access to cloud services is suspended on your workspace, you may still incur charges from Whatsapp, as Rocket.Chat does not manage these services and can not cancel them on your behalf. See your WhatsApp business account panel for any pending bills and to manage your payments.
Create a permanent Whatsapp Cloud API token
Facebook uniquely provides the WhatsApp Cloud API token, Phone Number ID, and WhatsApp Business Account ID. Every business needs these credentials when using WhatsApp Cloud services.
The token provided by Facebook for testing is temporary and requires refreshing every 23 hours. Optionally, you can obtain a permanent WhatsApp Cloud API token by following these steps:
Open the app panel on your Facebook developers portal.
Click to open the business page linked to the app.
From the Facebook business setting page, navigate to System user.
A list of existing users on that app is seen, if any. Click Add to add a user, then Accept the terms and conditions.
Fill in the System username, then set sthe System User Role to Admin. Click Create System User.
Click on Add Assets across the newly created user to add assets to use.
A modal opens up, navigate to Apps, select the app, and enable Manage App. Then Save changes.
The asset gets added to the system user. Click Done.
Click on Generate New Token against the user to generate a new access token.
Select the App from the dropdown and check the
whatsapp_business_messaging
andwhatsapp_business_management
permissions. Then, click Generate Token.The permanent token is generated and presented to you. Copy this token and use it in your integrations.
Configure the WhatsApp Cloud app
After installing the app, you can update the app settings according to your requirements. To do this, follow these steps:
On the App Info page of the app, go to the Settings tab.
Enter the values for the following fields:
Field | Description |
---|---|
Notification of undeliverable message | Add a notification message to alert the agent that a message was not delivered to the WhatsApp platform. |
Agents Display Info | Select the agent information that would be added to every message sent by an agent to a visitor. The options are as follows:
|
File Uploads Enabled | Select this option to enable file upload in the conversations. By default, file upload is enabled. |
Maximum File Upload Size (in bytes) | Enter the maximum file size that can be uploaded. Set it to |
Accepted Media Types | Enter the file media types that you want to accept. This is a comma-separated list of media types. Leave it blank to accept all media types. By default, the value is |
Allow Quote Messages | If this option is enabled, agents can see the message when the visitor quotes or replies to a message on WhatsApp. |
Message Status Endpoint URL | Enter an endpoint URL where you want to receive the status of outgoing messages. |
Filter Message Status | Select the statuses you want to receive at the Message Status Endpoint URL endpoint based on the message type. The options are as follows:
By default, the value is All. |
Allow List options for Quick Replies | If this option is enabled, then messages with more than three quick reply options will be rendered as list options. Note that the maximum limit for list options is ten. By default, this option is enabled. |
Custom label for all List Option button* | Enter the custom label message you want to display on all quick reply options that are sent as a list. By default, the message is Show Options. |
Connect WhatsApp numbers
After installing and configuring the app, connect the WhatsApp number in the #Omnichannel WhatsApp Cloud Setup private channel to enable communication.
Click on Connect WhatsApp Number from the
whatsapp-cloud.bot
message in the channel or run the/whatsapp connect
slash command. Add the following details according to your requirements:
Field | Description |
---|---|
PhoneNo Id* | The WhatsApp phone number ID you want to connect. |
WhatsApp Business Id* | The WhatsApp Business Account ID of the WhatsApp number to connect |
Access Token* | The App's access token. It can be either temporary or permanent. |
Facebook App Secret* | The secret of the Facebook app. It is used to verify whether messages are sent from authorized WhatsApp servers. |
Welcome Message (optional) | Enter the first message that your customers receive automatically when they message you. |
Conversation Finished Message (optional) | Enter the message that your customers receive automatically when an agent closes the conversation. |
Default message for offline service (optional) | Enter the message that your customers receive automatically when no agent is available for the conversation. |
Click "Connect." After successfully saving the credentials, the final setup instruction for configuring the webhook URL on your Facebook developer console is displayed.
Setup Facebook app webhook URL
After connecting the WhatsApp number, the bot provides instructions for configuring a webhook URL on your Facebook app, including a callback URL and a Verify Token.
Go to the app created on your Facebook developer console.
Navigate to WhatsApp > Configuration and paste the callback URL and Verify Token provided by Rocket.Chat. Click Verify and save.
From the configuration screen, click on Manage across the Webhook field.
Subscribe to
messages
(v14.0 or higher). Now, click Done.
This is a one-time process. After subscribing to the messages, the Rocket.Chat WhatsApp Cloud app is ready for use. Visitors can now start sending messages to the WhatsApp phone number, and it gets delivered to your workspace.
Edit or disconnect WhatsApp Cloud number
To edit or disconnect a WhatsApp number in your workspace:
Run the slash command
/whatsapp numbers
to see a list of connected numbers.Click on Edit below the number you want to change. Make the necessary changes and then click Update.
Click on Disconnect below the number you want to disconnect, then confirm the prompt to disconnect. You will receive a message confirming the disconnection.
App slash commands
The WhatsApp Cloud app has a list of shortcuts to ease usage. Run the slash command /whatsapp help
to see the list of shortcuts and their functions:
/whatsapp connect: Connect a new WhatsApp number
/whatsapp numbers: View and edit all connected WhatsApp number
/whatsapp support: Get support information
/whatsapp help: See the help menu
API endpoints
The available endpoints are displayed on the Details tab of the App Info page.
Incoming message
The POST incoming
endpoint is used by the app to receive messages from WhatsApp. You generally don’t need to take action with this endpoint.
Send a template message
You must use the POST templateMessage
endpoint to send template messages. For more details, refer to the developer guide on sending template messages in Rocket.Chat.
Get the sidebar icon
You can use the GET get-sidebar-icon
endpoint to get the WhatsApp conversation room icons displayed in the Chats in Progress section on the left-hand menu.
For example, the request looks like this:
curl -X GET https://{workspace-url}/api/apps/public/87cf50f2-2db4-4e05-a8fd-135ad24f9c08/get-sidebar-icon
Uninstall Whatsapp Cloud app
To delete the Whatsapp app from your workspace,
Go to Administration > Apps > Installed.
Search for the WhatsApp Cloud app and click Uninstall.
Click Yes to confirm the uninstallation.