Notifications

Whatsapp

How Whatsapp notifications work.

This sends whatsapp messages directly to users. Stubber has an existing business account you can message through, however, you can register your own Whatsapp number to maintain your corporate image.

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 preconfigured 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 initated 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.

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.

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}}

Commands

Commands is a special feature of Whatsapp that has to specifically be enabled for a Stubber Whatsapp Profile if 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 /.

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}}

Unsolicited incoming messages

In some scenarios, a conversation is 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 unsolicited 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 behaviours, 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

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
• location
• contact

Default: null

params

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.

Default: null

enable_lids

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

whatsapp_profile_name

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

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

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

Length in hours for the Whatsapp stubsession to remain open.

Default: null

stubsession.cancel_current_existing_stubsession

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

Default: false

stubsession.set_nextreply_with_timeout_minutes

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

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

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

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.