Notifications

Whatsapp

Sending Whatsapp messages on the Stubber platform.

Stubber is a Meta Business Partner and has the ability to send Whatsapp messages directly to users.
Stubber is a Badged Partner and has integrated Whatsapp and other messaging platforms into the Stubber platform.

Stubber provides a default Whatsapp business number (+1 415 312 1456) that you can use immediately for testing and getting started with Whatsapp on the Stubber platform.

For production use, we highly recommend registering your own Whatsapp business number with Stubber. This allows you to:

• Display your own company branding
• Maintain consistent customer experience
• Have full control over your messaging
• Keep your business communications separate

To set up your own Whatsapp number with Stubber, please contact us.

# Inner workings

The Whatsapp communication channel works between 2 numbers, the business and the client. Messages can not be sent to group chats.

Stubber has a default Whatsapp business profile that will be used if you have not set up your own Whatsapp business profile in Stubber Manage yet. To set up your own Whatsapp business profile with your own branding, please contact us here.

To initiate a conversation with a client, a business has to start with a template message. Template messages are pre-configured messages that has been set up on Facebook business. ( List of available languages)

Stubber has default template messages that can be used to start a conversation. A default interaction request is sent automatically when you try to send a normal message without having initiated the conversation with a template message.

If a client replies to a message, that message will only be returned to the stub the message originated from if a stubsession was created in the first outgoing message from the business.

The stubsession is how Stubber knows what to do with incoming messages from clients. The Basic Usage section has an example of how to set a stubsession on an outgoing message.

# Routing Incoming Whatsapp Messages

When messages are sent to a Stubber Whatsapp Profile number, they need to be routed in some way. Stubber offers different mechanisms to route these incoming messages, such that a wide range of functionality is available.

Incoming messages are integrated into Stubber using a feedback action called _update_from_whatsapp. This feedback action is triggered when a message is sent to a Stubber Whatsapp Profile number.

# Stubsession

The most basic mechanism is the stubsession. When you send a message to a Whatsapp number, you can create a stubsession for that number. The stubsession contains the user's number, and the Stub that the original message was sent from. When that number replies with a message (incoming message), Stubber routes that message back the Stub of the stubsession via the feedback action, _update_from_whatsapp.

See the stubsession concept for more information

Incoming stubsession messages will emit the following Heimdall event:

• mechanism: evt
• path:stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.stubsession.{{stubsession_stubref}}

See Basic Usage

# Next reply

In some scenarios, you want to obtain/steal a single reply from a user, without potentially overwriting their active stubsession. The nextreply mechanism can be used for this.

Incoming nextreply messages will emit the following Heimdall event:

• mechanism: evt
• path: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.nextreply.{{nextreply_stubref}}

See the parameters and Examples.

# Specific reply

The specificreplyuuid is another useful mechanism that can be used to route incoming messages. When the user specifically replies to a message (the Whatsapp reply functionality of replying to a specific message), Stubber will check if a specificreplyuuid was set on the outgoing message, and then emit on Heimdall accordingly. This is useful for outgoing messages where the user is likely to specifically reply, eg. Button or Template messages.

Incoming specificreplyuuid messages will emit the following Heimdall events: General:

• mechanism: cbh
• path: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.specificreplyuuid.{{specificreplyuuid}}

Specific:

• mechanism: cbh
• path: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.from.{{from_number}}.specificreplyuuid.{{specificreplyuuid}}

# WhatsApp Commands

Commands is a special feature of Whatsapp that has to specifically be enabled for a Whatsapp Profile on the
Facebook Number Settings of that profile.

The picture below shows how you can edit the commands in the Automations section of your number's settings.

If commands are enabled on a Whatsapp number, then a list of the available commands will pop up when a user types a /.

For command messages that include additional content after the command and target (like /chat stubref message), only the message portion will be posted to the stub when using the chat routing functionality.

Incoming command messages will emit the following Heimdall event:

• mechanism: evt
• path: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.command.{{command}}.target.{{target}}.from.{{from_number}}

Consider the command invocation /run hello_world, in the path above, the {{command}} is the command that the user selected, run, and the {{target}} is the argument that the user provided for the command, hello_world. If no argument is provided, eg. /demo, the path would be: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.command.{{command}}.target..from.{{from_number}}

# Chat Command for Private Numbers

If you have your own WhatsApp business number set up with Stubber (not the public number), you can use a simplified chat command to route messages directly to stubs in your organization. This feature must be enabled by setting "enable_chat_routing_stubber_public": true in the Action Meta of the _update_from_whatsapp Feedback Action.

Once enabled, users or Solution Architects can send messages to your private number using this format:

        /chat {{stubref}}

      

Or with a message that will be posted to the stub:

        /chat {{stubref}} {{message}}

      

Since your private number is already tied to your organization, there's no need to specify the organization domain.

# Example Usage

To route a message to stub 2025-05-03-STUB-ABCD on your private number:

        /chat 2025-05-03-STUB-ABCD

      

Or with a custom message:

        /chat 2025-05-03-STUB-ABCD Need assistance with order status

      

In the first case, the command data would be delivered to the stub in the _update_from_whatsapp action. In the second case, the same action would be executed, but additionally with the message "Need assistance with order status".

# User Initiated Messages

A conversation can be initiated by the user instead of by Stubber (an org). For these cases, no stubsession can exist yet, so these messages cannot be posted on stubs via the _update_from_whatsapp feedback action.

These incoming messages will emit the following Heimdall event:

• mechanism: cbh
• path: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.from.{{from_number}}

# Basic Usage

• Setup a notification in an action as seen below

# Parameters

Everything inside platforms.meta_whatsapp should be considered parameters for this notification. There are top level parameters that describe the message type and other general message behaviors, and then there are nested parameters dependent on the message type.

This page focuses on the top level parameters, the nested parameters can be found in the message type specific pages below.

# message_type

required

string

Indicates the type of message that is going to be sent. This also will determine what the contents of the params object should be.

Available message types are:

• text
• media
• template
• buttons
• list
• location
• location_request
• contact

Default: null

# params

required

object

Contains the parameters for the message and will depend on the message_type setting. See the message_type specific documentation above for the message type specific parameters.

Some params that are common to some message types but not all are also placed in here.

Example:

Default: null

# enable_lids

optional

boolean

This parameter can be set to true to enable the lids feature for the outgoing Whatsapp message.

# whatsapp_profile_name

optional

string

If you have multiple WhatsApp profiles (multiple numbers) setup on your org, you can use this parameter to specify the profile to use for the outgoing message.

# enable_additional_status_messages

optional

boolean

Stubber receives status updates from Facebook for the following message events relating to an outgoing Whatsapp:

• sent: This is received if the message was delivered to Whatsapp (one tick).
• delivered: This is received if the message is delivered to the client's device (two ticks).
• read: This is received if the client reads the message (if the client has read receipts enabled).
• failed: This is received if something went wrong. It can happen before the sent and after the sent status events.

By default, only the sent and failed status messages are shown on outgoing Whatsapp stubposts as they are the only required status messages.

All status messages can be received if this parameter is set to true.

Default: false

# stubsession

optional

object

Contains the properties that relate to the handling of client's stubsession. The stubsession is what is used to determine where a client's incoming Whatsapp message should go. If you set the stubsession on an outgoing Whatsapp, all incoming replies for the duration of the stubsession will be returned to the stub the outgoing message was sent from.

Default: null

# stubsession.set_new_with_timeout_hours

optional

integer

Length in hours for the Whatsapp stubsession to remain open.

Default: null

# stubsession.set_feedback_action

optional

integer

Sets the feedback action that will be used to post incoming messages for this stubsession. If not set, the default _update_from_whatsapp feedback action will be used.

Default: null

# stubsession.cancel_current_existing_stubsession

optional

boolean

This can be set to true to cancel the current stubsession for a specific number (client).

Default: false

# stubsession.set_nextreply_with_timeout_minutes

optional

integer

This can be used to "steal" the stubsession for a specific number (client), but only for their next reply. After their next reply, their stubsession will return to what it was.

Default: false

# stubsession.specificreply_uuid

optional

string

If this parameter is supplied, incoming replies from the client will not be posted to the stub in their stubsession. This parameter makes it easy to run actions on any stub in your org for incoming messages, as opposed to specifically on the stub the message was sent from.

Incoming replies will emit on heimdall on a specific path, determined by the specificreply_uuid. You can then register on this path to run a specific action on any stub in your org.

Default: null

# stubsession.set_stubsession_stubref

optional

string

This parameter can be used to set the stubsession to a specific stub in your org. This is useful when you want to route the next incoming messages to a specific stub in your org. Setting this parameter will override the default behavior of the stubsession being set to the stub the message was sent from.

Default: null

# Result

• In order to communicate the user needs to approve a interaction request

• If you send multiple messages before a user approves the request. The system will stash those messages

• Stashed messages will be all sent at once after the user has accepted the interaction request

# Additional Parameters

# Enable Additional Status Messages

By default, the stub will only receive failed, sent and success whatsapp status messages.

You can enable the specific notification to receive all the whatsapp status messages by adding in this param: "enable_additional_status_messages": true,

# Examples

# Send the stubpost.message

This example will send the contents of the stubpost's message to a cellphone number contact point attached to the contact that is running the action, you. This can be seen in the send_to section, where the type is contactuuid and the value is actioningContact.contactuuid.

# Using the nextreply mechanism

By adding set_nextreply_with_timeout_minutes in the stubsession options, the next message (and only one) will be routed to the Stub that the nextreply was set from. After that, additional incoming messages will be routed to the stubsession, if it exists.

Nextreplys will also emit on the Heimdall path below: stubber.systems.notifications.whatsapp.incoming.{{whatsapp_profile_name}}.nextreply.{{nextreply_stubref}}

# Send a file via Whatsapp

In this example, we send a file that is uploaded with the Stubber files field, named files. The files field returns an array of files uploaded, so we have to specify the first file object in the array with the [0]. The send_to in this example is a contact_list on the stub, in this case _created_by. It will thus be send to a cell number contact point on whoever created the stub that this notification will be sent from.

media.files is expected as an array with and object. This object can be built out manually if required as below.

You can use standard substitution techniques to pull in values from stub or stubpost data.

# Request user's location

This example sends a location request message to the user, asking them to share their location.

# Sending a Whatsapp using a Template

When send a WhatsApp to someone, the rules are, They should be expecting the message and if not, have to option to reject it.

So when send a standard WhatsApp messages, the end user would first receive an interaction request message informing them there is a message for them and gives them the option to Allow or Reject the message. The end user has the choice.

Meta, however, have a way to allow you to create messages templates that you can use to send predefined messages without this interaction request being sent to the end user. Meta needs to review and approve these templates before they can be used.