Conversation API - Rasa Documentation

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.

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.

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.

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
}

​Requirements

​Quick Reference

​Queries

​rawConversations

​conversationTags

​Mutations

​addConversationTagToConversation

​removeConversationTagFromConversation

​deleteConversations

​Reference

​Conversation Events Structure

​User Uttered Event

​Bot Uttered Event

​Action Executed Event

Requirements

Quick Reference

Queries

`rawConversations`

`conversationTags`

Mutations

`addConversationTagToConversation`

`removeConversationTagFromConversation`

`deleteConversations`

Reference

Conversation Events Structure

User Uttered Event

Bot Uttered Event

Action Executed Event