Contents x
    WhatsApp Cloud App
      • Print
      • Dark
        Light
      • PDF
      Contents

      WhatsApp Cloud App

        • Print
        • Dark
          Light
        • PDF
        Article summary

        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.

        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 and whatsapp_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:

        1. On the App Info page of the app, go to the Settings tab.

        2. 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:

        • None: No agent information is displayed.

        • Name: The agent’s name is displayed in the conversations.

        • Username: The agent’s username is displayed in the conversations.

        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 -1 to remove the file size limitation. By default, the value is 104857600.

        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 image/*, application/pdf, video/*, audio/*. See Supported Media Types for details.

        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:

        • All: Receive the status of all messages.

        • Regular Messages: Receive the status of regular messages.

        • Template Messages: Receive the status of template messages only.

        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.

        1. 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.

        1. 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:

        1. Run the slash command /whatsapp numbers to see a list of connected numbers.

        2. Click on Edit below the number you want to change. Make the necessary changes and then click Update.

        3. 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.

        WhatsApp Cloud API FAQs

        Was this article helpful?
        What's Next
        Rocket.Chat versions receive support for six months after release. End-of-life for any version is the last day of the month when support ends.
        ESC

        Eddy AI, facilitating knowledge discovery through conversational intelligence