openapi: "3.0.1"
info:
  title: "Rasa Platform - Messaging"
  version: "1.0.0"
  description: >-
    Rasa Platform messaging endpoints
servers:
- url: http://demo-bot.rasa.com/core
  description: Demo
paths:
  /conversations:
    get:
      tags:
      - Messages
      summary: Fetch list of conversations
      operationId: getConversations
      parameters:
      - in: query
        name: intent
        schema:
          type: string
          default: null
        required: false
        description: comma-separated intents to filter on
      - in: query
        name: entity
        schema:
          type: string
          default: null
        required: false
        description: comma-separated entities to filter on
      - in: query
        name: action
        schema:
          type: string
          default: null
        required: false
        description: comma-separated actions to filter on
      - in: query
        name: text
        schema:
          type: string
          default: null
        required: false
        description: User utterance text to filter on
      - in: query
        name: start
        schema:
          type: number
          default: null
        required: false
        description: Minimum timestamp of latest user event
      - in: query
        name: until
        schema:
          type: number
          default: null
        required: false
        description: Maximum timestamp of latest user event
      - in: query
        name: policies
        schema:
          type: string
          default: null
        required: false
        description: Comma-separated list of policies used for prediction
      - in: query
        name: maximumConfidence
        schema:
          type: number
          default: null
        required: false
        description: Maximum value of the minimum action confidence
      - in: query
        name: minimumUserMessages
        schema:
          type: number
          default: null
        required: false
        description: Minimum number of user messages per conversation
      - in: query
        name: in_training_data
        schema:
          type: boolean
          default: null
        required: false
        description: >-
          Only show conversations that appear in the training data. If false,
          only show conversations not appearing in training data . If
          unset, show all conversations.
      - in: query
        name: sort_by_confidence
        schema:
          type: boolean
          default: true
        required: false
        description: >-
          Sort conversations that are not found in the training data
          by their minimum action confidence from high to low.
          Has no effect if `in_training_data` is anything other than false.
      - in: query
        name: sort_by_latest_event_time
        schema:
          type: boolean
          default: true
        required: false
        description: >-
          Sort conversations by their latest activity from most recent to
          least recent.
      - in: query
        name: is_flagged
        schema:
          type: boolean
          default: false
        required: false
        description: >-
          Filter for conversations which contain flagged messages.
      responses:
        200:
          description: List of conversations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationMetadata'

  /conversations/{sender_id}:
    get:
      tags:
      - Messages
      summary: Fetch a client's tracker
      operationId: getClientConversation
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      responses:
        200:
          description: List of conversations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Conversation'

  /conversationActions:
    get:
      tags:
      - Messages
      summary: Fetch a list of unique actions from all conversations
      operationId: getUniqueActions
      responses:
        200:
          description: List of actions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: action

  /conversationEntities:
    get:
      tags:
      - Messages
      summary: Fetch a list of unique entities from all conversations
      operationId: getUniqueEntities
      responses:
        200:
          description: List of entities
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: entity

  /conversationIntents:
    get:
      tags:
      - Messages
      summary: Fetch a list of unique intents from all conversations
      operationId: getUniqueIntents
      responses:
        200:
          description: List of intents
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: intent

  /conversationPolicies:
    get:
      tags:
      - Messages
      summary: Fetch a list of unique Rasa Core policies in all conversations
      operationId: getUniquePolicies
      responses:
        200:
          description: List of policies
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  description: policy

  /conversations/{sender_id}/messages:
    get:
      tags:
      - Messages
      summary: Fetch messages in conversation with conversation
      operationId: getMessages
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      - in: query
        name: until
        description: Upper bound of timestamp for data to be dumped
        schema:
          type: integer
      - in: query
        name: use_history
        description: Whether to include data before the last reset
        schema:
          type: boolean
      responses:
        200:
          description: Messages in conversation with conversation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        404:
          description: Conversation not found
  /conversations/{sender_id}/messages/{message_timestamp}:
    put:
      tags:
      - Messages
      summary: Flags this message
      operationId: flagMessage
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      - in: path
        name: message_timestamp
        schema:
          type: float
        required: true
      responses:
        201:
          description: Flag was added successfully
        400:
          description: message_timestamp was not a float
    delete:
      tags:
      - Messages
      summary: Removes a flag from a message
      operationId: deleteFlagFromConversation
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      - in: path
        name: message_timestamp
        schema:
          type: float
        required: true
      responses:
        200:
          description: Flag was removed successfully
        400:
          description: message_timestamp was not a float
  /conversations/{sender_id}/debug-dump.json:
    get:
      tags:
      - Messages
      summary: Download debug dump in JSON format
      operationId: downloadDebugDumpJson
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      - in: query
        name: until
        description: Upper bound of timestamp for data to be dumped
        schema:
          type: integer
      - in: query
        name: use_history
        description: Whether to include data before the last reset
        schema:
          type: boolean
      responses:
        200:
          description: Attachment of debug dump in JSON
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        404:
          description: Sender not found
  /conversations/{sender_id}/debug-dump.md:
    get:
      tags:
      - Messages
      summary: Download debug dump in Markdown format
      operationId: downloadDebugDumpMarkdown
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      - in: query
        name: until
        description: Upper bound of timestamp for data to be dumped
        schema:
          type: integer
      - in: query
        name: use_history
        description: Whether to include data before the last reset
        schema:
          type: boolean
      responses:
        200:
          description: Attachment of debug dump in Markdown
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        404:
          description: Conversation not found
  /conversations/{sender_id}/events:
    get:
      tags:
      - Messages
      summary: Fetch events in conversation with conversation
      operationId: getEvents
      parameters:
      - in: path
        name: sender_id
        schema:
          type: string
        required: true
      - in: query
        name: until
        description: Upper bound of timestamp for data to be dumped
        schema:
          type: integer
      - in: query
        name: use_history
        description: Whether to include data before the last reset
        schema:
          type: boolean
      responses:
        200:
          description: Events in conversation with conversation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        404:
          description: Client not found
  /statistics:
    get:
      tags:
      - Statistics
      summary: Fetch conversation statistics
      operationId: getConversationStatistics
      responses:
        200:
          description: Conversation statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationStatistics'
        404:
          description: Conversation not found

  /analytics:
    get:
      tags:
      - Analytics
      summary: Fetch analytics
      operationId: userAnalytics
      parameters:
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/end'
      - $ref: '#/components/parameters/window'
      responses:
        200:
          description: Analytics result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResult'
        404:
          $ref: '#/components/responses/AnalyticsNotFound'

components:
  responses:
    AnalyticsNotFound:
      description: Analytics not found
      content:
        application/json:
          schema:
            type: object
            properties:
              exception:
                type: string
              reasons:
                oneOf:
                - type: string
  parameters:
    start:
      in: path
      name: start
      example: 2018-01-01T11:03:01.141
      description: >-
        Start time. Accepts ISO-8601 format (as in the example) or Unix time.
      schema:
        type: string
      required: false
    end:
      in: path
      name: end
      example: 2018-11-02T13:44:09.932
      description: >-
        End time. Accepts ISO-8601 format (as in the example) or Unix time.
      schema:
        type: string
      required: false
    window:
      in: path
      name: window
      example: 1d
      description: >-
        Bin size used in the accumulation of the requested analytics result.
        If not specified, 10 bins are returned by default.
        Multiple formats are supported. A full list is available
        at https://pypi.org/project/pytimeparse/1.1.8/.
      schema:
        type: string
      required: false
  schemas:
    AnalyticsResult:
      type: object
      properties:
        newUsers:
          type: array
          description: Number of new users
          items:
            type: number
        conversations:
          type: array
          description: Number of active conversations
          items:
            type: number
        user_messages:
          type: array
          description: Number of user messages
          items:
            type: number
        bot_messages:
          type: array
          description: Number of bot messages
          items:
            type: number
        total_messages:
          type: array
          description: Total number of user and bot messages
          items:
            type: number
        sessions_per_user:
          type: array
          description: Average number of sessions per user
          items:
            type: number
        conversation_length:
          type: array
          description: Average conversation length
          items:
            type: number
        conversation_steps:
          type: array
          description: Average number of conversation steps
          items:
            type: number
    Intent:
      type: object
      properties:
        confidence:
          type: integer
        name:
          type: string
    ParseData:
      type: object
      properties:
        entites:
          type: array
        intent:
          $ref: '#/components/schemas/Intent'
        intent_ranking:
          type: array
          items:
            $ref: '#/components/schemas/Intent'
        text:
          type: string
    ActionEvent:
      type: object
      properties:
        event:
          type: string
          enum:
          - action
        name:
          type: string
        timestamp:
          type: integer
    UserEvent:
      type: object
      properties:
        event:
          type: string
          enum:
          - user
        parse_data:
          $ref: '#/components/schemas/ParseData'
        text:
          type: string
        timestamp:
          type: integer
        is_flagged:
          type: boolean
          default: false
          description: True if message was flagged.
    BotEvent:
      type: object
      properties:
        event:
          type: string
          enum:
          - bot
        data:
          type: object
          nullable: true
        text:
          type: string
        timestamp:
          type: integer
        is_flagged:
          type: boolean
          default: false
          description: True if message was flagged.
    RestartEvent:
      type: object
      properties:
        event:
          type: string
          enum:
          - restart
        timestamp:
          type: integer
    Event:
      oneOf:
      - $ref: '#/components/schemas/UserEvent'
      - $ref: '#/components/schemas/BotEvent'
      - $ref: '#/components/schemas/ActionEvent'
      - $ref: '#/components/schemas/RestartEvent'
    Conversation:
      type: object
      properties:
        sender_id:
          type: string
          description: Username of client
        latest_event_time:
          type: integer
          description: Timestamp of most recent event (in seconds)
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        latest_message:
          type: string
          description: Latest user message
        paused:
          type: boolean
          description: Conversation paused
        followup_action:
          type: string
          description: name of the followup action
        slots:
          type: array
          description: Filled slots
          items:
            type: object
        latest_input_channel:
          type: string
          description: Name of the input channel last used
        latest_action_name:
          type: string
          description: Name of last bot action
        active_form:
          type: string
          description: Name of the active form
        flagged_messages:
          type: array
          description: List of flagged messages
    ConversationMetadata:
      type: object
      properties:
        sender_id:
          type: string
          description: Username of client
        latest_event_time:
          type: number
          description: Timestamp of most recent event (in seconds)
        latest_input_channel:
          type: string
          description: Name of the input channel last used
        intents:
          type: array
          items:
            type: string
          description: Set of intents in the conversation
        actions:
          type: array
          items:
            type: string
          description: Set of actions in the conversation
        minimum_action_confdience:
          type: number
          description: Minimum action confidence in the conversation
        in_training_data:
          type: boolean
          description: Whether the entire conversation appear in training data
        policies:
          type: array
          items:
            type: string
          description: Set of policies used in the action predictions
        n_user_messages:
          type: number
          description: Number of user messages in the conversation
        flagged_messages:
          type: array
          description: List of flagged messages
        unflagged_messages:
          type: array
          description: List of unflagged messages
    ConversationStatistics:
      type: object
      properties:
        user_messages:
          type: integer
        bot_messages:
          type: integer
        top_intents:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              count:
                type: integer
        top_entities:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              count:
                type: integer
        top_actions:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              count:
                type: integer
        top_policies:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              count:
                type: integer