Conversation API

The Conversation API allows external access to retrieve, delete, and tag conversations within Rasa Studio.

Requirements

• Required API Role Manage conversations (or View conversations for read-only operations). See Authorization page to learn how to access configuration.

• Assistant name. See guide for user configuration for more details.

  

• Tag IDs. To see how to access page from screenshot see guide for conversation review.

  

Quick Reference

Type	Operation	Description
Query	rawConversations	Retrieve conversations with optional filters
Query	conversationTags	List all tags for an assistant
Mutation	addConversationTagToConversation	Add a tag to a conversation
Mutation	removeConversationTagFromConversation	Remove a tag from a conversation
Mutation	deleteConversations	Delete one or more conversations

---

Queries

rawConversations

Retrieves conversations for an assistant with optional filtering by time range and tags.

Schema:

type Query {
  rawConversations(input: RawConversationsInput!): RawConversationsOutput!
}

input RawConversationsInput {
  assistantName: String!
  fromTime: String
  toTime: String
  limit: Int
  offset: Int
  tags: [String!]
}

type RawConversation {
  id: ID!
  conversationEvents: [JSON!]!
  tags: [ConversationTag!]!
}

type RawConversationsOutput {
  conversations: [RawConversation!]!
  count: Int!
}

Input: RawConversationsInput

Field	Description
assistantName	The unique identifier of the assistant.
fromTime	Optional start time filter in ISO 8601 UTC format (YYYY-MM-DDTHH:MM:SS.sssZ).
toTime	Optional end time filter 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.
tags	Optional list of tag names to filter conversations by.

Output: RawConversationsOutput

Field	Description
conversations	A list of raw conversation objects. Each conversation contains an id, a list of conversationEvents in JSON format, and a list of tags.
count	Total count of conversations matching the query criteria. Not affected by limit and offset.

Example:

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, tags { id, name } }, count } }", "variables": { "input": { "assistantName": "assistant-name", "fromTime": "2024-01-01T00:00:00Z", "toTime": "2024-01-31T23:59:59Z", "limit": 10, "offset": 0, "tags": ["example-tag"] } }}'

---

conversationTags

Retrieves all conversation tags available for a given assistant.

Schema:

type Query {
  conversationTags(input: ConversationTagsInput!): [ConversationTag!]!
}

input ConversationTagsInput {
  assistantName: String!
}

type ConversationTag {
  id: ID!
  name: String!
  assistantId: ID!
}

Input: ConversationTagsInput

Field	Description
assistantName	The unique identifier of the assistant.

Output: [ConversationTag!]!

Returns a list of conversation tags:

Field	Description
id	The unique identifier of the tag.
name	The display name of the tag.
assistantId	The unique identifier of the assistant.

Example:

curl -X POST https://<your-api-url>/api/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-d '{"query": "query conversationTags($input: ConversationTagsInput!) { conversationTags(input: $input) { id, name, assistantId } }", "variables": { "input": { "assistantName": "assistant-name" } }}'

---

Mutations

addConversationTagToConversation

Adds a tag to a conversation.

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

---

removeConversationTagFromConversation

Removes a tag from a conversation.

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

---

deleteConversations

Deletes one or more conversations.

Schema:

type Mutation {
  deleteConversations(input: DeleteConversationsInput!): Int!
}

input DeleteConversationsInput {
  conversationIds: [ID!]!
}

Input: DeleteConversationsInput

Field	Description
conversationIds	List of conversation IDs to delete.

Output: Returns the count of deleted conversations.

note

The count only includes conversations that were actually deleted. If all IDs passed to the API were invalid, count will be zero.

Example:

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

---

Reference

Conversation Events Structure

The conversationEvents field in rawConversations contains a list of events that occur within a conversation. These events follow a specific structure that varies by event type. For a full description of all possible events, see the Rasa Events Documentation.

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

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
  }
}

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
}