Adding functionality to Unblu with custom actions
Unblu gives you many different ways to integrate Unblu into your existing software environment. With custom actions, the opposite is possible: you can integrate features of other software your organization uses into Unblu. This lets you create a seamless experience for your employees and customers, helping them to achieve their goals faster and with less hassle.
A custom action has two parts:
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.
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.
|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.|
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.
/customactions/create, you include one of
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
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.
By default, new custom actions are enabled. To disable a custom action, click the Enabled toggle, or set the field
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 defines what you want the custom action to do.
For API events, you must specify which participant the event is triggered for. Three options are always available:
SELFtriggers the event for the user who invoked the custom action.
OTHERStriggers the event for all conversation participants except the user who invoked the custom action.
ALLtriggers the event for all conversation participants.
For custom person actions, there’s an additional option:
TARGET_PERSONtriggers the event for the person the custom action was invoked on.
For custom message actions, there’s also an additional option:
SENDERtriggers 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.
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
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
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 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 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.
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
If a custom action triggers a webhook event and the webhook delivery fails, the custom action’s state is automatically set to
Disabled custom actions are no longer available in new and ongoing conversations.
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 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.
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.