WhatsApp Sandbox

The WhatsApp Sandbox App provides a secure environment for testing Rocket.Chat's integration with WhatsApp, using the 360dialog sandbox. This allows you to send both regular and template messages from your workspace to your customers on WhatsApp. Similar to the WhatsApp Cloud app, the sandbox app lets you experiment freely without risking your business data or disrupting ongoing operations.

This app is for testing only and not intended for production use. For production, use the official WhatsApp Cloud App.

Prerequisites

A Rocket.Chat workspace with Omnichannel enabled. Omnichannel agents and managers must also be assigned.
From 7.0, the WhatsApp Sandbox App requires a subscription add-on. Contact the sales team to get the required add-on.

Install WhatsApp Sandbox App

To install the WhatsApp Sandbox app,

Go to Administration > Apps > Marketplace.
Search for the Whatsapp Sandbox app.
Click Install and accept the needed permissions. You receive a message from whatsapp-sandbox.bot with setup instructions.

If you don’t have the required add-on, a warning is displayed for you to contact sales to get the add-on.
To get support, please run the /whatsapp-sandbox support command.

Get the Test API key from 360Dialog

To use the WhatsApp Sandbox App, you'll need a test API-KEY from 360dialog.

To obtain the API-KEY:

Send a WhatsApp message with the content "START" to 4930609859535, or use this link.
Alternatively, scan this QR Code.

You’ll receive your Test API-KEY, linked to the WhatsApp number you used. With this key, you can start using the 360dialog WhatsApp Sandbox.

For more details, refer to the official documentation on 360dialog Sandbox and its limitations.

Configure WhatsApp Sandbox 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
WhatsApp Sandbox API KEY*	The API KEY provided by 360Dialog for the sandbox environment.
Default department	The default department to handle all conversations from WhatsApp Sandbox.
Welcome Message	Enter the first message that your customers receive automatically when they message you.
Conversation Finished Message	Enter the message that your customers receive automatically when an agent closes the conversation.
Service Unavailable Message	Enter the message that your customers receive automatically when no agent is available for the conversation.
Agents Display Info	Select the agent information that would be added to every agent's message. 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.
Allow Quote Messages	If this option is enabled, agents can see the message when the contact 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.

Click Save Changes.

After saving the API key, you can begin sending WhatsApp messages to the sandbox number from your linked phone number. The messages are delivered to your workspace and are ready for agents to respond.

App slash commands

The WhatsApp Sandbox 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-sandbox view-templates: List the available template messages in the sandbox environment.
/whatsapp-sandbox send-template: Send a template message to a contact.
/whatsapp-sandbox support: Get support information
/whatsapp-sandbox 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 to contacts. For more details, refer to the developer guide on sending template messages in Rocket.Chat.

There are only three pre-defined template messages available on WhatsApp Sandbox. Templates cannot be created or modified. Consult the 360dialog documentation to learn more.

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 Sandbox app

To delete the WhatsApp Sandbox app from your workspace,

Go to Administration > Apps > Installed.
Click the kebab menu against the Whatsapp Sandbox app.
Select Uninstall.
Click Yes to confirm the uninstallation.