Managing Users via API

Flow XO provides an HTTP API you can use to programmatically create users for any of your bots, or update the name of an existing user. 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. Please note, you can also create a user or update a user directly in Flow XO without using an API key by using the Flow XO Utilities integration, documented here.

Authorization

You must authorize all calls to the Flow XO API using an Authorization header in your HTTP request. The Flow XO API uses 'bearer token' authorization, so you will need to precede your API key with the word 'Bearer', like so:

Authorization: Bearer yOuRApIKeyGoEsHeRe

Note that if you are using Postman, and you use the Bearer Token feature, you will not need to manually add the word 'Bearer' as postman will do that for you: https://learning.postman.com/docs/sending-requests/authorization/#bearer-token

You can find your API key in the User Profile section of the Flow XO account owner. The API key is only visible to users with an Owner role.

API Url

To use the Flow XO API, you will need to send HTTP requests to the following endpoint. The last part of the URL will depend on the method you are calling, but the base address is:

https://flowxo.com/api/

Finding the Connection ID of your Bot

Before you can use the API to create a new user, you will need to locate the Connection ID of the bot you want to add the user to. Please see this article for locating the correct Connection ID.

Determining the Channel ID of the new user

In addition to the Connection ID of the bot you want to add the user to, you will need to decide on a Channel ID for your user. The correct Channel ID for a user will depend on the type of bot, such as Telegram or WhatsApp, and you can read about how to find the right channel ID here.

Create User API

POST https://flowxo.com/api/end_users

The payload should be of type application/json, and look like this (all profile fields are optional)

{
  "connection":"YOUR_CONNECTION_ID",
  "channel":"NEW_USER_CHANNEL_ID",
  "profile":{
      "user_name":"Some Username",
      "user_first_name":"Joe",
      "user_last_name":"Joeson",
      "user_timezone": "America/Los_Angeles",
      "user_locale": "en",
      "user_email":"someone@somwhere.com",
      "user_phone":"+17072554923"
  },
  "attributes": {
      "my":"attribute"
  },
  "segments":[]
}

Here's what the request would be using cURL:

curl --location --request POST 'https://flowxo.com/api/end_users' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "connection":"YOUR_CONNECTION_ID",
  "channel":"NEW_USER_CHANNEL_ID",
  "profile": {
	"user_name":"Some Username",
	"user_first_name":"Joe",
        "user_last_name":"Joeson",
        "user_timezone": "America/Los_Angeles",
        "user_locale": "en",
        "user_email":"someone@somwhere.com",
        "user_phone":"+17072554923"
   },
   "attributes": {
      "my":"attribute"
   },
   "segments":[]
}'

Payload:

connection : String, required This is the Connection ID of your bot. Please see the section above on finding the Connection ID for the bot you want to add your user to.
channel : String, required This is the Channel ID of your user. This will be specific to the type of bot (WhatsApp, SMS). Please see the section above of Channel ID.
profile : Object, optional
user_name : String, optional This is the user name of the new user
user_first_name: String, optional This is the first name of the new user
user_last_name: String, optional This is the last name of the new user
user_timezone: String, optional The IANA timezone of the new user
user_locale: String, optional The two character country code of the new user
user_email: String, optional The email address of the user
user_phone: String, optional The phone number of the user.
attributes: Object, optional A JSON object containing the attributs you wish to set on the user. All values will be converted to strings.
segments: See "Working with segments" at the end of this document

A note on the user profile: Some channels will send Flow XO the username, first name and last name data, or some combination. If you provide them when creating a new user, it will permanently override whatever the channel may send. Only send a user profile if you know for sure what you want to call your user. Leave it blank and when they send a message to Flow XO, if the channel sends profile data, the blanks will be filled in automatically.

Update User API

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.

NOTE: Attributes provided in the update will be merged with existing attributes, not replace them. To remove attributes, provide the attribute names you want to remove with an empty string as the value.

API Url:

PUT https://api.flowxo.com/api/end_users

Updating a user using CURL

curl --location --request PUT 'https://flowxo.com/api/end_users' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "response_path":"USERS_RESPONSE_PATH",
  "profile": {
	"user_name":"Some Username",
	"user_first_name":"Joe",
        "user_last_name":"Joeson",
        "user_timezone": "America/Los_Angeles",
        "user_locale": "en",
        "user_email":"someone@somwhere.com",
        "user_phone":"+17072554923"
   },
   "attributes": {
      "my":"attribute"
   }, 
   "segments": {}
}'

Working with Segments

In addition to updating the basic profile data and attributes of your users, you can also use this same API to add, remove, or completely replace a users segment membership by adding a "segments" key to your update or create payload. The segments object can take one of two forms: an array of segment IDs ( "segments": ["segmentid1", "segmentid2"] ) which adds the provided segments to a user, or as an object:

{
  ...
 "segments": {
     "replace": ["segmentid1", "segmentid2"],
     "add": ["segmentid1", "segmentid2"],
     "remove": ["segmentid1", "segmentid2"]
}

When using the object form of the API, segment IDs in the "replace" array will completely replace any existing segments the user has, while segments in the "add" array will add the provided segments and segments in the "remove" array will remove the provided segments from a user.

The entire call will look like this:

PUT https://api.flowxo.com/api/end_users

Updating a user using CURL

curl --location --request PUT 'https://flowxo.com/api/end_users' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "response_path":"USERS_RESPONSE_PATH", 
   "segments": {
       "add":["segmentid1", "segmentid2"]
    }
}'

When you update a users segments via API, any triggers that are configured to start flows based on changes in segment membership will be fired. This may not always be what you want, especially if you are changing many users in bulk, as it can slow the process down, or you may simply want to put a user in a segment for historical purposes and avoid any actions that would normally take place when a user is added to a segment as part of a normal flow. You can disable these triggers by including the "disableTriggers" key

{
  ...
 "segments": {
     "replace": ["segmentid1", "segmentid2"],
     "add": ["segmentid1", "segmentid2"],
     "remove": ["segmentid1", "segmentid2"]
}

The entire call will look like this:

PUT https://api.flowxo.com/api/end_users

Updating a user using CURL

curl --location --request PUT 'https://flowxo.com/api/end_users' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "response_path":"USERS_RESPONSE_PATH", 
  "disableTriggers": true,
   "segments": {
       "add":["segmentid1", "segmentid2"]
    }
}'

Listing existing segments or creating new ones

You can also get a list of existing segments, or create a new segment via the API by using the "/segments" endpoint. Here's an example that lists existing segments:

curl --location --request GET 'https://flowxo.com/api//segments' \
--header 'Authorization: Bearer YOURAPIKEY' \

And here is an example of adding a new segment:

curl --location --request POST 'https://flowxo.com/api/segments' \
--header 'Authorization: Bearer YOURAPIKEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name":"my new segment",
    "description": "a new segment for fun times"
 }
}'

And that's it! Let us know if you have any questions or feedback at support@flowxo.com