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