REST API Reference for Conversations History

Description of all REST API endpoints for getting users’ conversation data

Conversations History

You can download your users’ conversations with the bot. The API requires the bot id and authentication with the bot server access token. You can find them in the bot Settings.

Replace the [bot id] and [bot server access token] in the examples below.


Returns a list of all conversations.

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bot-Server-Access-Token [bot server access token]" \
-X GET[bot id]/conversations

Conversation messages

Returns a list of all messages in a conversation.

curl \
-H "Content-Type: application/json" \
-H "Authorization: Bot-Server-Access-Token [bot server access token]" \
-X GET[bot id]/messages?query=%7B%22Conversation%22%3A%[conversation id]%22%7D



Limits the number of elements in the result.

/v1/bots/[bot id]/conversations?limit=100


Skips the first N elements in the result that match the query.

/v1/bots/[bot id]/conversations?skip=100


Sorts the elements in the result by one ot more properties.

/v1/bots/[bot id]/conversations?sort=StartedAt
/v1/bots/[bot id]/conversations?sort={"Data.user.FirstName":-1, "Data.user.LastName": 1}


Filters the elements with MongoDB query predicates.

The queries support filtering by a single or multiple properties, nested properties, logical and comparison operators.

/v1/bots/[bot id]/messages?query={"User":"[user-id]"}
/v1/bots/[bot id]/conversations?query={"":"facebook","Status":"success"}
/v1/bots/[bot id]/conversations?query={"$or":[{"":"facebook"},{"":"viber"}]}
/v1/bots/[bot id]/conversations?query={"Errors":{"$gt":0}}
/v1/bots/[bot id]/conversations?query={"Messages.user":{"$gt":3}}


Returns the count of the elements that match a query.

/v1/bots/[bot id]/conversations/_count?query={"":"facebook"}
/v1/bots/[bot id]/messages/_count?query={"Conversation":"[conversation-id]"}