Adding functionality to Unblu with custom actions

What’s a custom action?

A custom action has two parts:

An action of some kind that you want users to be able to trigger. This action can be a realtime webhook, an event in the Unblu Visitor or Embedded JavaScript API, or a mobile SDK event. It can be related to a conversation as a whole, a person taking part in the conversation, or a message in the conversation.
A UI element for users to trigger the custom action. The UI element is a button with an icon that you provide when you create the custom action.

Types of custom action

There are three types of custom action:

Custom conversation actions triggered on a conversation. A support desk agent might use a custom conversation action to forward a transcript of a conversation to the customer’s relationship manager.
Custom person actions triggered on a participant in a conversation. For example, you could create a custom person action that lets agents open a participant’s portfolio in their CRM application.
Custom message actions triggered on an individual message in a conversation. A relationship manager can use a custom message action on a file message to trigger an electronic signature process.

The examples given above are all rather simple, but you can create more complex workflows. The endpoints of the Bots web API, for example, let you guide participants through a process once it’s been triggered by a custom action.

Creating custom actions

You can create custom actions in the Account Configuration interface or with the /customactions/create endpoint of the Custom actions web API.

To use a custom action you’ve created, you have to enable it the conversation templates you want it to be available in. For more information, refer to Enabling and disabling custom actions below.

Selecting the custom action type

In the Account Configuration interface, the type of custom action to create is determined by the option you select after clicking the New custom action button.

When calling /customactions/create, you include one of CustomConversationActionData, CustomMessageActionData, or CustomPersonActionData in the body of the request. Each of the schemas includes the type field which determines the type of custom action Unblu creates. If, for example, you pass a CustomPersonActionData with field set to CONVERSATION in the body of your call, Unblu creates a custom conversation action. Any fields that aren’t relevant for custom conversation actions are ignored.

Basic options

By default, new custom actions are enabled. To disable a custom action, click the Enabled toggle, or set the field state to INACTIVE.
The Key is the custom action’s unique identifier. It’s used to identify the custom action in events sent to the APIs or webhooks.
The Icon and Name are displayed in the agent and visitor UIs. Both are mandatory.
The Description is optional.
You can provide translations of the name and description by clicking the Add translations button.

The What section

The What section defines what you want the custom action to do.

Custom actions can trigger events in the Unblu mobile and JavaScript APIs as well as webhook events.

For API events, you must specify which participant the event is triggered for. Three options are always available:

SELF triggers the event for the user who invoked the custom action.
OTHERS triggers the event for all conversation participants except the user who invoked the custom action.
ALL triggers the event for all conversation participants.

For custom person actions, there’s an additional option:

TARGET_PERSON triggers the event for the person the custom action was invoked on.

For custom message actions, there’s also an additional option:

SENDER triggers the event for the person who sent the message that the custom action was invoked on.

For Webhook events, you must specify the endpoint URL the event should be delivered to when the action is triggered. You can add a secret key that can be used to verify the origin of the event.

System messages for custom actions

By default, Unblu sends a system message when a user triggers the custom action.

To disable system messages for custom actions, uncheck the option in the Account Configuration interface. In calls to /customactions/create, set the field triggerSystemMessage to false.

Who can see these system messages is determined by com.unblu.conversation.message.allowSeeGeneralSystemMessagesForCustomActions and com.unblu.conversation.message.allowSeePersonalSystemMessagesForCustomActions, both of which are in the CONVERSATION_TEMPLATE scope.

The Who section

The Who section specifies who’s allowed to invoke the custom action. You can restrict the use of a custom action to one or more types of participant.

The When section

The When section defines when a custom action can be invoked. You can restrict the possibility to invoke a custom action based on the conversation state and the participation state of the user who wants to invoke the custom action.

The Where section

The Where section specifies the user interfaces that the custom action should be available in. If you have a custom action that launches a mobile app, for example, there’s little point in displaying it in the Agent Desk.

The custom action is only available in the user interface provided the participant using it has access to the custom action.

The Sort order defines where the custom action should appear in the list of available (predefined and custom) actions. The order of actions with the same sort order is undefined.

Some aspects of the Where section are only available for certain types of custom actions:

For conversation custom actions, the Action bar display mode specifies how the action should appear in the action bar. Choose between Always in overflow, Always show, and Show if possible.
For message custom actions, Message types lets you specify which message types the action should be available on. Messages sent by allows you to limit the action to messages sent by certain participants.

The Target section

The Target section is only available for custom person actions. It lets you specify which types of participant the custom action should available for. You can further restrict custom person actions to be available only when the target person is using a certain entry point.

If you select a target entry point for the custom person action, agents can only invoke the action on participants who are online with the entry point specified.

If you don’t select a target entry point, agents can also invoke the action on participants who are offline.

Enabling and disabling custom actions

To make a custom action available to users, add it to the configuration property com.unblu.conversation.availableCustomActionIds.

If you want to enable all custom actions, use com.unblu.conversation.enableAllCustomActions instead. This overrides any selection made in the previous configuration property.

You can temporarily disable a custom action by clicking the Enabled toggle in the account configuration interface or by calling the /customactions/update endpoint with the state field set to INACTIVE.

If a custom action triggers a webhook event and the webhook delivery fails, the custom action’s state is automatically set to INACTIVE_UNAVAILABLE.

Disabled custom actions are no longer available in new and ongoing conversations.

Invoking custom actions

Custom actions of a given type are displayed in the same place as predefined actions of the same type. The location depends on the user interface they’re displayed in, but the Agent Desk can serve as an example:

Custom conversation actions appear in the action bar or in the action bar overflow menu , depending on the action’s display mode.
Custom message actions appear wherever you can trigger an action on a message:
- When you hover over a message they can be invoked on.
- When you enlarge an image uploaded to a conversation.
- In the overview of All shared files in a conversation.
Custom person actions are listed in the participant information popup of participants they can be invoked on.

Reacting to custom actions

How you react to a custom action is entirely up to you. The reaction can consist of single operation, such as opening a particular page on your organization’s website. It could also be initiate a process involving a dialog bot that helps participants complete a more complex series of steps.