Flow XO Utilities

The Flow XO Utilities provides a grab bag of helper functions that can help you automate management your account and your users.

The triggers available in the Flow XO Utils package are:

New Error

This trigger will be fired any time an error occurs in one of your flows. The 'outputs' of the trigger, which can be used to filter when the trigger fires, format messages or any other purpose, contain details about the error that occurred, the bot, workflow and task that failed, and if applicable the end user engaging with your bot when the error happened.

WARNING: When an error handling flow itself encounters an error, it will not trigger more error handlers to avoid infinite loops. However, if your error handlers trigger additional workflows, and those workflows fail, they WILL fire the error handlers - you could easily get yourself into an infinite loop and use up all your interactions very quickly. Be extremely careful when triggering flows from within error handling flows to avoid this situation.

Here is a complete list of available variables:

Response Path	The response path of the user chatting with your bot when the failure occurred.
Error Message	The text of the error message. You can use this to update a back end system with details of the error, or in a CONTAINS filter for the trigger that will allow you to handle only certain errors for a given Error Handling flow.
Error Type	The category of the error. There are several current error types: policy_violation - This means the policy of the underlying platform was violated. Currently, it only applies to Facebook Messenger when you attempt to send messages outside of the 24 hour messaging window bounce - a user can no longer be reached, usually because they blocked your bot or left the conversation conflict - you are attempting to send a message or ask a question, but another question is waiting to be answered already in another flow authorization - your account is not authorized to perform the given action. This can mean that your credentials are no longer valid for an integration such as Google Sheets, or, as (unfortunately) happens from time to time, Facebook has de-authorized your session and requires you to re-authorize your page. bad_user - you are attempting to send a message to a user that does not exist limits_exceeded - you are exceeding Flow XO limits. Usually, this means you are out of interactions or your flow has reached the maximum number of times it can loop through a label error - this is the generic error type for all other errors not covered by one of the above.
Bot ID	The internal identifier of the bot that failed. Note: this will be missing for 'Webhook' triggered flows.
Bot Name	The name you have given your bot. Note: this will be missing for 'Webhook' triggered flows.
Bot Platform	The platform, such as Messenger or Telegram.
Failed Workflow ID	The internal identifier of the workflow that failed
Failed Workflow Name	The name of the workflow that failed
Failed Task ID	The internal identifier of the task that failed within the workflow
Failed Task Name	The name of the task that failed
Abandoned Request ID	The internal identifier of the interaction that failed. This is the identifier Flow XO support will need to assist in resolving the error.
User ID	The platform-specific identifier of the user. For example, if you are using Facebook Messenger, this will be the PSID.
User Handle	The platform-specific username of the user, if available.
User Name	The full name of the user, if available
User First Name	The first name of the user, if available
User Last Name	The last name of the user, if available
Attributes	The attributes associated with the user, if available

New Abandoned Conversation

This trigger will be fired any time a a conversation is abandoned because of a question timing out, validation failing too many times, or the user explicitly quitting a flow by typing "by" or "quite" (or equivalent given the bots language settting). This feature can be used to send a user to live chat after too many failed validation attempts, for example.

Here is a complete list of available variables:

Response Path	The response path of the user chatting with your bot when the failure occurred.
Abandoned Reason	Why the conversation was abandoned. You can use this property in a filter to only handle abandoned conversations of a specific type, such as failed validations. validation_failed - the user provided input, but it did not pass validation rules after the configured number of attempts timed_out - the user never provided a response to the question for the duration of the configured expiry period user_quit - the user typed "bye" or "quit" to intentionally exit the conversation
Bot ID	The internal identifier of the bot that failed. Note: this will be missing for 'Webhook' triggered flows.
Bot Name	The name you have given your bot. Note: this will be missing for 'Webhook' triggered flows.
Bot Platform	The platform, such as Messenger or Telegram.
Abandoned Workflow ID	The internal identifier of the workflow that failed
Abandoned Workflow Name	The name of the workflow that failed
Abandoned Task ID	The internal identifier of the task that failed within the workflow
Abandoned Task Name	The name of the task that failed
Failed Service Name	The name of the service that failed, such as Google Sheets
Failed Method Name	The name of the service method that failed, such as Lookup Row
Failed Request ID	The internal identifier of the interaction that failed. This is the identifier Flow XO support will need to assist in resolving the error.
User ID	The platform-specific identifier of the user. For example, if you are using Facebook Messenger, this will be the PSID.
User Handle	The platform-specific username of the user, if available.
User Name	The full name of the user, if available
User First Name	The first name of the user, if available
User Last Name	The last name of the user, if available
Attributes	The attributes associated with the user, if available

Methods

Users - Get Chat Transcript

This method will get the message history for the current user as a single block of text. You can optionally specify the start and end time of the transcript, and how you want to label the bot or agent VS the user. This step is very useful if you want to send a chat history to an agent or supervisor periodically or at the end of a specific interaction. It can also be combined with the Open AI integration to provide ChatGPT with a conversation history, or to have a conversation automatically summarized.

Max Message Count	How many messages to retrieve. Make this number as small as you can to meet your objective, especially if you will be using this step multiple times in a flow, as the entire transcript is stored in the conversation and can eventually slow your flows down if overused.
Agent Label	How messages from Flow XO should be labeled. For example, if your label is "Bot: " then the transcript will identify messages from Flow XO like this: "Bot: How can I help you today?".
User Label	How messages from the user should be labeled.
Start Time	(Optional) The earliest time that messages should be retrieved for the transcript. This is especially useful if you want to collect a transcript for a particular interaction - you can set the Start Time to the "Message Received" timestamp of the trigger of your flow.
End Time	(Optional) The latest time that messages should be retrieved for the transcript.
Remove Newlines	(Optional) Strips any new lines (line breaks) from individual messages. This is helpful when sending a transcript to ChatGPT, since the ChatGPT integration splits messages by lines, and this setting will prevent the ChatGPT integration from mistakenly attributing a multi-line message to the wrong author.

Users - Clear Open Questions

This method will mark any flows for a given user that are blocked because they are waiting on a response from the user as 'Abandoned'. This method can be useful in Broadcast flows if you may have users who have not completed a previous conversation, but you want the current broadcast flow to take priority.

Users - Clear Attributes

This method will clear all custom attributes from the user's profile. This can be useful if you want to 'reset' a user, and put them back in a 'new' state as if they are interacting with your bot for the first time. This can be used in conjunction with 'Users - Clear Open Questions' to truly give a user a fresh start.

Users - Change Status

This method can can be used to mark a user as 'Banned' or 'Available' (unbanned). You can use this to automatically ban a user, or unban them later, perhaps after a timout.

Users - Create User

This action can create a user with a given channel ID in the audience of the bot you specify. You can use this API to import users from another platform, to pro-actively add users to your bot for channels that support automated first-contact messaging, such as Twilio SMS or WhatsApp, or to add users to your audience that subscribe to or join a Telegram Group or Channel your bot is an administrator of.

Parameters:

Connection ID	The Connection ID of the bot you want to add the user to. Please see here for more information.
Channel ID	The channel-specific unique identifier of the user you want to add. Please see here for more information on selecting the correct Channel ID.
User Name	The User Name of the user you wish to add. This is optional, and if specified will permanently override any User ID that might be provided by the channel itself.
User First Name	The First Name of the user you wish to add. This is optional, and if specified will permanently override any First Name that might be provided by the channel itself.
User Last Name	The Last Name of the user you wish to add. This is optional, and if specified will permanently override any Last Name that might be provided by the channel itself.
Email	The email address of the user
Phone	The phone number of the user
Language	The two digit ISO language code of the user. This field, when set, will alter which language system messages are displayed in.

Users - Update User

In addition to being able to create a new user, you can update the username, first name and last name of any user as long as you have their response path. This can be very useful for channels that don't provide any kind of user information, such as SMS and the Web Bot.

Parameters:

Response Path	The Response Path of the user you wish to update.
User Name	The User Name of the user you wish to add. This is optional, and if specified will permanently override any User ID that might be provided by the channel itself.
User First Name	The First Name of the user you wish to add. This is optional, and if specified will permanently override any First Name that might be provided by the channel itself.
User Last Name	The Last Name of the user you wish to add. This is optional, and if specified will permanently override any Last Name that might be provided by the channel itself.
Email	The email address of the user
Phone	The phone number of the user
Language	The two digit ISO language code of the user. This field, when set, will alter which language system messages are displayed in.

Users - Find User

This action can look up a user based on their, response path, email address, phone number, or external user identifier. This can be useful if you want to trigger webhooks from external systems that interact with your users, but your external systems do not have access to the user's response path.

Parameters:

Search Field	The user field you want to use to find the user. Options are Response Path, Email, Phone Number and External ID
Search Value	The value to search for. This will depend on the search field. For example, if your search field is Email, you should supply the user's email, and if it's Response Path, provide the user's response path, etc.
Multiple Result Handling	By default, if you have multiple users with the same 'value' in the search field you are searching, the most recently updated will be returned. If you prefer your flow to fail if this happens instead, you can set this to 'Fail if Multiple Found'
Connection ID	Advanced. By default, this search will look for any user associated with any of your bots. If you only want to search for users tied to a specific bot, you can put the Bot Connection ID here.

Generate a Unique Identifier

Sometimes it may be useful to generate a random ID. This can be particularly useful when working with Google Sheets to create a unique ID for each row that you can refer to in future queries. Google Sheets rows do not have their own unique identifiers, and so they are referenced by row number, which can be hard to manage when the row number changes because of inserts and

Parameters:

Number of Characters

The length of the ID you want to generate. The default is 21, which can be rather long if you want your users to be able to enter the ID you generate into another system. So choose a length that works well for your application, but keep in mind that the longer the ID, the more unique it will be. If you choose a very short ID, like 3 or 4 characters, and you generate a LOT of IDs, you may end up with duplicates!

Cancel a Flow

Sometimes you need to cancel a flow manually. Usually this is because you are working with subflows, and you want to cancel a flow that you have previously triggered, or cancel a flow that triggered the current flow.

Parameters:

Reason	The reason you are cancelling the flow. This is optional, and will show up in the logs.
Request ID	The Request ID, which is the unique identifier of a running flow, for the flow you want to cancel. You can cancel the CURRENT flow by leaving this blank.

Parameters:

Reason	The reason you are cancelling the flow. This is optional, and will show up in the logs.
Request ID	The Request ID, which is the unique identifier of a running flow, for the flow you want to cancel. You can cancel the CURRENT flow by leaving this blank.

Start typing indicator

Currently works for Web bots and Telegram bots. Starts the typing indicator, to let the user know that the bot is working. The typing indicator will automatically be turned off after the next message is sent to the user.