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:

Triggers

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 - 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.

Still need help? Contact Us Contact Us