Accessing End User Conversations via API
Flow XO allows you to list and retrieve conversation transcripts through our API.
The following actions are available:
1. Listing all conversations associated with your account (paginated)
2. Access details of a single conversation
3. Retrieve all of the messages in a single conversation
Authorization
You must authorize all calls to the Flow XO API using your API key and an authorization header. Details can be found here: https://support.flowxo.com/article/289-api-authorization
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/conversations
Listing Conversations
You can list conversations associated with your account issuing a GET request:
GET https://flowxo.com/api/conversations?skip={skip}&limit={limit}&start={start_time_iso_8601}&end={end_time_iso_8601}
The result will look like this:
{
total: 415,
skip: 0,
limit: 25,
conversations:
[
{
"agent_mode": false,
"last_message": {
"id": "618dafd33546c5802fd7991c",
"role": "bot",
"conversation": "60105b74d2b084f0b80bd45a/c/876631178",
"from": "60105b74d2b084f0b80bd45a",
"agent_mode": false,
"type": "custom",
"custom": "{\"text\":\"Well you know my name is __simon__\",\"parse_mode\":\"MarkdownV2\",\"disable_web_page_preview\":false,\"disable_notification\":false,\"allow_sending_without_reply\":false}",
"timestamp": "2021-11-12T00:05:39.329Z"
},
"created_at": "2021-11-04T05:20:29.174Z",
"id": "60105b74d2b084f0b80bd45a/c/876631178",
"id_url_encoded": "60105b74d2b084f0b80bd45a%2Fc%2F876631178",
"bot_id": "60105b74d2b084f0b80bd45a",
"bot_name": "nathanbot local",
"platform": "telegram",
"user_id": "876631178",
"user_name": "Secret Dude"
},
{
"agent_mode": false,
"last_message": {
"id": "618b2ba4ed4f3d25c300bd56",
"role": "bot",
"conversation": "603be93db1331d55a2e1b291/c/17074777548",
"from": "603be93db1331d55a2e1b291",
"agent_mode": false,
"type": "text",
"message": "Here: 7074777548: valid",
"options": null,
"timestamp": "2021-11-10T02:17:08.166Z"
},
"created_at": "2021-03-01T01:14:40.902Z",
"unreachable": false,
"id": "603be93db1331d55a2e1b291/c/17074777548",
"id_url_encoded": "603be93db1331d55a2e1b291%2Fc%2F17074777548",
"bot_id": "603be93db1331d55a2e1b291",
"bot_name": "whatsapp",
"platform": "whatsapp",
"user_id": "17074777548",
"user_name": "Nathan"
}
]
}
Parameters
start - (optional) - the starting date or date/time in ISO8601 format for which you want to return conversations.
end - (optional) the ending date or dat/time in ISO8601 format for which you want to return conversations
skip - the number of records to skip. This is used in pagination (see blow)
limit - the maximum number of records to return. This is used in pagination (see below)
Pagination
You should use the "skip" and "limit" parameters to paginate your conversation results, as there may be a very large number of them, too many to process in one API call.
skip determines how many records to skip from the beginning of the data set
limit determines how many records to return
The data that is returned will contain a total field, which represents the total number of conversations matching the filter criteria, and can be used to calculate the total number of pages based on your page size.
To retrieve a specific page of records, you will determine skip and limit values based on the number of items in your "page" of results, and the current page you are on. For example, if you are returning 25 items per page and the user wants to see page 3, you would provide a limit value of 25 (25 records per page) and a skip value of 50. The skip value is calculated as (page number - 1) x page size, or (3-1) x 25 = 50, in this example.
If you need additional filters on this API to accommodate filtering in your data set, please let us know.
IMPORTANT NOTE:
The identifier for conversations is a "Response path" - which is a string that looks like this: {bot_id}/c/{user_id}
Since we need to use this identifier in future API calls, and since the natural format of the response path has the / character and can be difficult for REST apis, each conversation record returned includes the attribute "id_url_encoded". Please use THIS identifier in other conversations API calls when fetching additional data.
Listing a single conversation
You can retrieve the data of a single conversation by issuing a GET request:
GET https://flowxo.com/api/conversations/{url_encoded_converstaion_id}
The result will look like this:
{
"agent_mode": false,
"last_message": {
"id": "618dafd33546c5802fd7991c",
"role": "bot",
"conversation": "60105b74d2b084f0b80bd45a/c/876631178",
"from": "60105b74d2b084f0b80bd45a",
"agent_mode": false,
"type": "custom",
"custom": "{\"text\":\"Well you know my name is __simon__\",\"parse_mode\":\"MarkdownV2\",\"disable_web_page_preview\":false,\"disable_notification\":false,\"allow_sending_without_reply\":false}",
"timestamp": "2021-11-12T00:05:39.329Z"
},
"created_at": "2021-11-04T05:20:29.174Z",
"id": "60105b74d2b084f0b80bd45a/c/876631178",
"id_url_encoded": "60105b74d2b084f0b80bd45a%2Fc%2F876631178",
"bot_id": "60105b74d2b084f0b80bd45a",
"bot_name": "nathanbot local",
"platform": "telegram",
"user_id": "876631178",
"user_name": "Secret Dude"
}
<br>
Listing messages of a conversation
You can retrieve all the messages in a conversation by issuing a GET request:
GET https://flowxo.com/api/conversations/{url_encoded_converstaion_id}/messages?skip={skip}&limit={limit}
The result will look like this:
[
{
"id": "618dafd33546c5802fd7991c",
"role": "bot",
"conversation": "60105b74d2b084f0b80bd45a/c/876631178",
"from": "60105b74d2b084f0b80bd45a",
"agent_mode": false,
"type": "custom",
"custom": "{\"text\":\"Well you know my name is __simon__\",\"parse_mode\":\"MarkdownV2\",\"disable_web_page_preview\":false,\"disable_notification\":false,\"allow_sending_without_reply\":false}",
"timestamp": "2021-11-12T00:05:39.329Z"
},
{
"id": "618dafd13546c5802fd79913",
"role": "bot",
"conversation": "60105b74d2b084f0b80bd45a/c/876631178",
"from": "60105b74d2b084f0b80bd45a",
"agent_mode": false,
"type": "custom",
"custom": "{\"text\":\"Hi!\",\"disable_web_page_preview\":false,\"disable_notification\":false,\"allow_sending_without_reply\":false}",
"timestamp": "2021-11-12T00:05:37.782Z"
},
{
"id": "618b1796ed4f3d25c300b4a7",
"role": "bot",
"conversation": "60105b74d2b084f0b80bd45a/c/876631178",
"from": "60105b74d2b084f0b80bd45a",
"agent_mode": false,
"type": "text",
"message": "Command: \nMessage: Text me",
"options": null,
"timestamp": "2021-11-10T00:51:34.014Z"
},
]<br>
You can use the same pagination technique described when listing conversations.
Fields:
role - the role will be either "bot", meaning the messages was sent by the bot, or "channel", which is an incoming message from the user
agent_mode - agent mode will be "true" when the messages was sent during live chat, and false when sent as part of an automated conversation
type - type references the type of message. It can be text, card, card_set, and custom, among others
custom - for custom requests, the custom payload sent to the messaging channel
message - the text of the message sent or received
options - any options sent as part of a question
timestamp - the time of the message
Thats it for now! We will be documenting more about payload schema of messages in the future, but this should get you started.