Creating a User 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:

{
  "connection":"YOUR_CONNECTION_ID",
  "channel":"NEW_USER_CHANNEL_ID",
  "profile":{
      "user_name":"Some Username",
      "user_first_name":"Joe",
      "user_last_name":"Joeson"
  }
}

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",
   }
}'

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

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.

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",
   }
}'