Contact usRequest a demo

Triggering Aria flows with custom actions

This is a preview feature. It may be subject to change or removal with no further notice.

To enable preview features, set com.unblu.platform.enablePreview to true.

For more information on preview features, refer to the Unblu release policy.

A custom action can run an Aria agentic flow when a user invokes it. The flow receives the context of the invocation: the conversation, the person who invoked the action, and the person or message targeted.

A custom action flow carries out a task rather than taking part in a conversation. For example, it can export a conversation to your organization’s CRM application when an advisor invokes the action. Nothing appears in the conversation itself.

A custom action can only trigger an Aria flow if your account’s license includes Aria Pro.

Adding an Aria flow to a custom action

You add an Aria flow when you create or edit the custom action:

  • In the custom action editor, select Aria flow under Aria in the Triggered on section. If you’re creating a new custom action, Unblu opens the action’s Flow canvas tab so you can start building the flow right away. The Flow canvas tab is available on the page of any custom action that triggers an Aria flow. For a description of the flow canvas, refer to Flow canvas in the Aria interface guide.

  • With the web API, set triggerAgenticFlow to true in your call to /customactions/create or /customactions/update.

    You can’t link an existing flow by its ID. For more information, refer to Managing Aria flows with the web API.

In both cases, Unblu creates the flow and links it to the custom action.

The default flow

The flow Unblu creates contains a single start node and nothing else. Every start node provides information about the invocation itself, about the person who invoked the action, and about the conversation it was invoked in. For the full list, refer to The invocation context below.

The type of start node depends on the type of custom action:

  • Custom conversation actions use the Custom Conversation Action Start node.

  • Custom person actions use the Custom Person Action Start node, which also provides the state of the person the action was invoked on.

  • Custom message actions use the Custom Message Action Start node, which also provides the state of the message the action was invoked on.

The invocation context

The start node makes the context of the invocation available to the flow as variables. The variables fall into four groups:

In the last three groups, each variable name consists of a prefix identifying the group and the name of a field of a web API schema, separated by an underscore. The section for each group names the schema it draws on. The topic of the conversation, for instance, is in conversation_topic.

Every variable is a string:

  • Nested objects, lists, and maps are serialized as JSON strings. The conversation’s participants, for example, arrive as a JSON array in conversation_participants.

  • Enum values appear as their name, such as CONVERSATION or TEXT.

The action

Four variables describe the invocation itself:

  • actionType: The type of custom action. Possible values are CONVERSATION, PERSON, and MESSAGE.

  • actionKey: The key of the custom action the user invoked.

  • actionInvocationId: The ID of the individual invocation.

  • actionInvocationTimestamp: The time the user invoked the action.

These are the only variables without a prefix.

The person who invoked the action

Variables in this group use the prefix executedBy_ followed by the name of the corresponding field of PersonData. For example, the person’s display name is in executedBy_displayName.

There are two differences from the schema:

  • The invocation context includes executedBy_avatarId, which holds the ID of the person’s avatar.

  • The invocation context doesn’t include the person’s metadata.

The conversation

Variables in this group use the prefix conversation_ followed by the name of the corresponding field of ConversationData. Every field of the schema is available.

The target person or message

Custom person actions and custom message actions have a fourth group of variables describing what the user invoked the action on:

  • For custom person actions, the prefix is person_, followed by the name of the corresponding field of PersonData. The two differences described in The person who invoked the action apply here as well.

  • For custom message actions, the prefix is message_, followed by the name of the corresponding field of MessageData.

    MessageData is the base schema for all the message types, and this group only includes the fields that all message types have in common. Nothing specific to a message type reaches the flow. For example, the invocation context doesn’t give you access to a text message’s text (the message body) or a file message’s downloadLinks.

Execution

When a user invokes the custom action, Unblu starts the flow and doesn’t wait for it to finish. What the flow’s nodes produce stays in the flow. For anything to reach Unblu, add a Spark Script node that makes the desired call to the Unblu web API.

The custom action’s other triggers are unaffected. API events and webhook events fire as usual, whether the flow succeeds or fails.

The delivery log

Unblu calls Aria through an outbound endpoint registration that it creates along with the flow. Flow runs therefore appear in the custom action’s Delivery log tab, just as webhook deliveries do.

For more information on how Unblu delivers outbound requests, refer to The outbound request mechanism (ORM).

Custom actions without Aria Pro

If you have custom actions that trigger an Aria flow but your license doesn’t include Aria Pro, the following applies:

  • The custom action itself still works, and its API events and webhook events fire as usual. However, Unblu skips the Aria flow and writes a warning to the log naming the action’s key and the invocation ID.

  • The Flow canvas tab is no longer available.

  • In the custom action editor, the Aria flow option remains selected, but you can’t change it. The only way to remove the trigger is the /customactions/update endpoint, which also deletes the flow.

  • You can’t save changes to the custom action as long as it triggers an Aria flow.

Custom actions that have never triggered an Aria flow aren’t affected, and the Aria flow option is hidden for them.

Managing Aria flows with the web API

Two fields on CustomConversationActionData, CustomMessageActionData, and CustomPersonActionData deal with Aria flows:

  • triggerAgenticFlow is a boolean. When you create or update a custom action, it specifies whether the action should trigger an Aria flow. When you read a custom action, it tells you whether a flow is currently linked to it.

  • agenticFlowData holds the ID of the Aria flow. Add ?expand=agenticFlowData to your request to replace the ID with the flow’s full content.

    You can’t choose which flow a custom action uses. Unblu always creates the flow itself: a create call that sets agenticFlowData to the ID of an existing flow is rejected, and on update Unblu discards any ID you send. The one exception is import, where agenticFlowData contains the flow’s full content instead of an ID, which is how utransfer recreates a custom action’s flow.

Adding and removing flows

The effect of /customactions/update depends on the value of triggerAgenticFlow and on whether the custom action already has a flow:

  • If triggerAgenticFlow is true and the action doesn’t have a flow yet, Unblu creates one.

  • If triggerAgenticFlow is false and the action currently has a flow, Unblu unlinks the flow and deletes it.

In all other cases, Unblu leaves the action’s flow as it is.

Deleting a custom action deletes its flow as well.

Exporting and importing custom actions

A custom action’s Aria flow is included when you export and import custom actions with utransfer.

See also