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 currently only be used to mark a user as 'Unreachable'. This is a rarely needed function, but if your flow logic determines that you should not send broadcasts to a user from that point forward it can be useful. It is critical to understand that if you send a message after using this function, or the user sends a message to your bot, it will put the user back into an 'Active' status, so this method should usually be the last method of a flow. Any notification you want to send the user should be sent before using this method.

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.

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.

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.