On Demand

On Demand broadcasts are never sent automatically by Xenioo but can only be triggered by calling a very specific Launch Web Hook that will be dynamically generated for you. Invoked On Demand broadcasts are sent by Xenioo with a maximum delay of 10 seconds to all targeted users. Invoking again the hook URL before the broadcast has been sent will force a reschedule and actually delay distribution as the timer will be reset and the broadcast queued again.

Launch Web Hook

This field contains the hook URL that Xenioo will generate for you. Use this hook in your integration systems to invoke this broadcast.

Filter Calling Hosts

Use this field to ensure that your broadcast hook cannot be called by any source host but those specified. By default your broadcast hook URL can be invoked by any host.

Calling the Web Hook

The web hook supplied by Xenioo can be called using either GET or POST standard http methods. While the most immediate way is GET, as it can be done by simply copying and pasting the hook in any browser window, the POST method gives you more control over execution.

When using POST, you have two ways of invoking the web hook using two different payloads: the audience and values approach lets you specify a dynamic audience and a set of value that will target one or more contacts using multiple filters while the mass users payload will let you target multiple users at once by specifying their unique id.

Audience and Values

Invoking the web hook using POST you can supply a number of parameters that can override the configured Audience or automatically set one or more variables for all targeted users. You can find an example of the full JSON payload below:

{
    "audience_filters":"favorite_color",
    "audience_criteria":"Equals",
    "audience_values":"red",
    "set_variables":"new_favorite_color",
    "set_variables_values":"magenta"
}

The above JSON, when posted to the Launch Web Hook will filter users to target only those with favorite_color equal to red and will create on all those users the variable new_favorite_color equal to magenta.

Using multiple values and variables is possible by just concatenating each entry with a semicolon (;). In the following example, we are using two filters and setting multiple variables:

{
    "audience_filters":"favorite_color;user_id",
    "audience_criteria":"Equals;Equals",
    "audience_values":"red;3030391",
    "set_variables":"new_favorite_color;someother_var",
    "set_variables_values":"magenta;the_other_var_value"
}

In the example above, the target broadcast audience will be overridden by the dynamic parameters supplied: only the user with id equal to 3030391 and favorite_color equal to red will be targeted by the broadcast.

The JSON fields you may configure are:

Field	Description
audience_filters	A list of filter fields as a single, comma separated string that will be dynamically used ad audience filter.
audience_criteria	The criteria to be used in the filters. Check table below for full reference.
audience_values	The list of values for each of the field reference.
audience_join	The list of logical operators that join the different filters. Can be either AND or OR. By default, or operators are AND.
set_variables	The list of variables to be set automatically for each targeted user.
set_variables_values	The values supplied for each variable.

When specifying the criteria field, you can use the following values:

Operator

Equals

Different

GreaterThan

LesserThan

Cointains

DoesNotContain

StartsWith

DoesNotStartWith

HasValue

EmptyOrUnset

IsLongerThan

IsShorterThan

The hook will return different http error codes depending on the call result:

Value
200 OK	The call has been successful and the broadcast has been scheduled.
400 Bad Request	The call contains invalid data that cannot be correctly parsed. This may happen if the payload is invalid or some of the mandatory fields are incomplete.
404 Not Found	The specified broadcast has not been found or the broadcast is not enabled.

The set_conversation parameter

When invoking the OnDemand webhook using POST an additional boolean parameter named set_conversation can be specified. This parameter will ignore the audience filters and attempt to create a brand new conversation using the values supplied inside the set_variables and set_variables_values parameters.

Le't look at the following example:

{
    "set_variables":"bot_channel;user_phone_number",
    "set_variables_values":"WhatsAppChannel;34655555555",
    "set_conversation":true
}

Using the data above, Xenioo will execute the OnDemand broadcast trying to:

• Search for an existing conversation for the targeted chatbot that has the specified user_id. If user_id is not supplied, it will try to use the user_phone_number;

• If the conversation is found, it will target the found conversation for the broadcast and leave execution;

• If the conversation is not found, it will create new conversation using the supplied variables and target it with the current broadcast.

Keep in mind that not all channels allow unattended or unsolicited messaging from unknown contacts and while the conversation can be created, the message delivery may still fail.

To create a brand new conversation at least bot_channel and user_phone_number (or user_id) must be supplied. If these parameters are missing the conversation won't be created.

If the targeted broadcast is called without the specified parameter, the specified Audience will be used instead for distribution.

Multiple Users Creation and Targeting

If you need to target multiple potentially new users with the very same broadcast you can use the targets payload mode when invoking the broadcast using POST.

The expected targets payload could look similar to the following example:

{
    "targets":[
        {
            "user_id":"221123030303",
            "bot_channel":"WhatsApp",
            "some_variable":"test"
        },
        {
            "user_id":"342342342311",
            "bot_channel":"WhatsApp",
            "other_variable":"some other test value"
        }
    ]
}

In the above example, the on demand broadcast will be sent to two different users. If the users do not exist, they will be created. Variables set in the payload do not need to be homogeneous: different contacts can have different variables. To create a new contact at least the user id and bot channel variables must be specified.

On WhatsApp, SMS and RCS, the user id of the contact is equal the user phone number variable. To create a new contact on these channels either user id or user phone number can be specified.