Build your first agent in just a few minutes with [Rasa Copilot](https://hello.rasa.com/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta).

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](/content/docs/studio/security/authorization/#creating-a-new-client-id/index.html) to learn how to access configuration.
- Assistant name. See [guide for user configuration](/content/docs/studio/build/set-up-your-assistant/index.html) for more details.

- Tag IDs. To see how to access page from screenshot see [guide for conversation review](/content/docs/studio/analyze/conversation-review/index.html).

## Quick Reference

| Type | Operation | Description |
| --- | --- | --- |
| Query | [`rawConversations`](/content/docs/reference/api/studio/conversation-api/#rawconversations/index.html) | Retrieve conversations with optional filters |
| Query | [`conversationTags`](/content/docs/reference/api/studio/conversation-api/#conversationtags/index.html) | List all tags for an assistant |
| Mutation | [`addConversationTagToConversation`](/content/docs/reference/api/studio/conversation-api/#addconversationtagtoconversation/index.html) | Add a tag to a conversation |
| Mutation | [`removeConversationTagFromConversation`](/content/docs/reference/api/studio/conversation-api/#removeconversationtagfromconversation/index.html) | Remove a tag from a conversation |
| Mutation | [`deleteConversations`](/content/docs/reference/api/studio/conversation-api/#deleteconversations/index.html) | Delete one or more conversations |

## Queries

### `rawConversations`

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

**Schema:**

```graphql
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:**

```bash
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:**

```graphql
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:**

```bash
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:**

```graphql
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:**

```bash
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:**

```graphql
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:**

```bash
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:**

```graphql
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:**

```bash
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](/content/docs/reference/primitives/events/index.html).

#### User Uttered Event

```json
{
  "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

```json
{
  "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

```json
{
  "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
}
```