Notifications
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.
The previous WhatsApp Notifications that use platform.whatsapp
are being phased out.
Please make sure you are using these notification syntax's
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:
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 thesent
and after thesent
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.
Nextreply
s 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.
See Attachments for related info
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.