Conversation API | Rasa Documentation

Build your first agent in just a few minutes with Rasa Copilot.

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

`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.

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.

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.

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
}