Version: Latest
Conversation API
Introduction
The Conversation API allows external access to delete and tag conversations within Rasa Studio.
Requirements
- Required API Role
Manage Conversations. See Authorization page to learn how to access configuration. - Assistant API ID. See guide for user configuration for more details.
- Tag IDs. To see how to access page from screenshot see guide for conversation review.
Available APIs
Query: rawConversations
Schema:
type Query {
rawConversations(input: RawConversationsInput!): RawConversationsOutput!
}
input RawConversationsInput {
assistantId: ID!
fromTime: String
toTime: String
limit: Int
offset: Int
}
type RawConversation {
id: ID!
conversationEvents: [JSON!]!
}
type RawConversationsOutput {
conversations: [RawConversation!]!
count: Int!
}
Input: RawConversationsInput
| Field | Description |
|---|---|
assistantId | The unique identifier of the assistant. |
fromTime | Optional start time filter for the conversation retrieval in ISO 8601 UTC format (YYYY-MM-DDTHH:MM:SS.sssZ). |
toTime | Optional end time filter for the conversation retrieval in ISO 8601 UTC format (YYYY-MM-DDTHH:MM:SS.sssZ). |
limit | Limits the number of conversations returned. Default is 10. |
offset | Skips a specified number of conversations for pagination. Default is 0. |
Output: RawConversationsOutput
| Field | Description |
|---|---|
conversations | A list of raw conversation objects. Each conversation contains an id and a list of conversationEvents in JSON format. |
count | Total count of conversations matching the query criteria. Count is not affected by paging arguments limit and offset. |
JSON Structure for conversationEvents
The conversationEvents field contains a list of events that occur within a conversation. These events follow a specific structure that can vary depending on the type of event. For a full description of all possible events, please refer to the Rasa Events Documentation.
Here are a few examples:
Example 1: User Uttered Event
{
"sender_id": "f9e5db46255c42e8aefd7fce720d192f",
"event": "user",
"timestamp": 1692186822.4774666,
"metadata": {
"model_id": "003d55f2a67147a597cec7e1df3e96e9",
"assistant_id": "rich-response-rasa"
},
"text": "/mood_great",
"parse_data": {
"intent": {
"name": "mood_great",
"confidence": 1
},
"entities": [],
"text": "/mood_great",
"message_id": "7457d2d8174243409e39b165164c79c7",
"metadata": {},
"intent_ranking": [
{
"name": "mood_great",
"confidence": 1
}
]
},
"input_channel": "cmdline",
"message_id": "7457d2d8174243409e39b165164c79c7"
}
Example 2: Bot Uttered Event
{
"sender_id": "f9e5db46255c42e8aefd7fce720d192f",
"event": "bot",
"timestamp": 1692186813.6298656,
"metadata": {
"utter_action": "utter_greet",
"model_id": "003d55f2a67147a597cec7e1df3e96e9",
"assistant_id": "rich-response-rasa"
},
"text": "Hey! How are you?",
"data": {
"elements": null,
"quick_replies": [
{
"title": "great",
"payload": "/mood_great"
},
{
"title": "super sad",
"payload": "/mood_unhappy",
"image_url": "https://i.imgur.com/l4pF9Fb.jpg"
}
],
"buttons": [
{
"title": "great",
"payload": "/mood_great"
},
{
"title": "super sad",
"payload": "/mood_unhappy",
"image_url": "https://i.imgur.com/l4pF9Fb.jpg"
}
],
"attachment": null,
"image": null,
"custom": null
}
}
Example 3: Action Executed Event
{
"sender_id": "f9e5db46255c42e8aefd7fce720d192f",
"event": "action",
"timestamp": 1692186813.2051082,
"metadata": {
"model_id": "003d55f2a67147a597cec7e1df3e96e9",
"assistant_id": "rich-response-rasa"
},
"name": "action_session_start",
"policy": null,
"confidence": 1,
"action_text": null,
"hide_rule_turn": false
}
Example curl Request
Here's an example cURL request to the rawConversations endpoint:
curl -X POST https://<your-api-url>/api/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-d '{"query": "query rawConversations($input: RawConversationsInput!) { rawConversations(input: $input) { conversations { id, conversationEvents }, count } }", "variables": { "input": { "assistantId": "12345", "fromTime": "2024-01-01T00:00:00Z", "toTime": "2024-01-31T23:59:59Z", "limit": 10, "offset": 0 } }}'
Mutation: addConversationTagToConversation
Schema:
type Mutation {
addConversationTagToConversation(
input: AddConversationTagToConversationInput!
): Boolean!
}
input AddConversationTagToConversationInput {
conversationId: ID!
tagId: ID!
}
Input: AddConversationTagToConversationInput
| Field | Description |
|---|---|
conversationId | The unique identifier of the conversation to which the tag will be added. |
tagId | The unique identifier of the tag to be added to the conversation. |
Output
Returns true if the tag was successfully added.
Note: If the tag already exists, the endpoint will also return true. If a non-existent conversation, tag, or resource mismatch occurs, a descriptive error message with an appropriate error code is returned.
Example curl Request
curl -X POST https://<your-api-url>/api/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-d '{"query": "mutation addConversationTagToConversation($input: AddConversationTagToConversationInput!) { addConversationTagToConversation(input: $input) }", "variables": { "input": { "conversationId": "12345", "tagId": "67890" } }}'
Mutation: removeConversationTagFromConversation
Schema:
type Mutation {
removeConversationTagFromConversation(
input: RemoveConversationTagFromConversationInput!
): Boolean!
}
input RemoveConversationTagFromConversationInput {
conversationId: ID!
tagId: ID!
}
Input: RemoveConversationTagFromConversationInput
| Field | Description |
|---|---|
conversationId | Unique identifier of the conversation from which the tag should be removed. |
tagId | Unique identifier of the tag to be removed from the conversation. |
Output
Returns true if the tag was successfully removed.
Note: If the provided tagId is not linked to the conversationId, or if the provided conversationId or tagId is not present in the system, the endpoint will still return true.
Example curl Request
curl -X POST https://<your-api-url>/api/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-d '{"query": "mutation removeConversationTagFromConversation($input: RemoveConversationTagFromConversationInput!) { removeConversationTagFromConversation(input: $input) }", "variables": { "input": { "conversationId": "12345", "tagId": "67890" } }}'
Mutation: deleteConversations
Schema:
type Mutation {
deleteConversations(input: DeleteConversationsInput!): Int!
}
input DeleteConversationsInput {
conversationIds: [ID!]!
}
Input: DeleteConversationsInput
| Field | Description |
|---|---|
conversationIds | List of conversation IDs to be deleted. |
Output
Returns the count of deleted conversations.
Note: Count only counts conversations that were actually deleted. If all IDs passed to API were invalid count will be zero.
Example curl Request
curl -X POST https://<your-api-url>/api/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-d '{"query": "mutation deleteConversations($input: DeleteConversationsInput!) { deleteConversations(input: $input) }", "variables": { "input": { "conversationIds": ["12345"] } }}'