openapi: 3.2.0
info:
  title: Reporting Metadata API
  description: Access automation, conversation and agent data in Pypestream..
  version: '1.0'
servers:
- url: https://reporting.pypestream.com/api/v2/
  description: Production Environement
- url: https://reporting-sandbox.pypestream.com/api/v2/
  description: Sandbox Environment
tags:
- name: Metadata
paths:
  /single-chat/{chat_id}:
    get:
      summary: Single Session
      description: Retrieves a specific session's metadata identified by the Chat/Session ID.
      security:
      - BasicAuth: []
      parameters:
      - description: Chat/Session ID
        in: path
        name: chat_id
        required: true
        schema:
          example: 02e4c194-c2fd-4f49-826a-685f2f7c3be1
          type: string
      - description: Enables retrieval of Google Business Messages survey data.
        in: query
        name: include_survey
        required: false
        schema:
          type: boolean
          example: true
      - description: Enables retrieval of Flow completion data (as configured in the solution template).
        in: query
        name: flows
        required: false
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful request with response body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataObject'
        '400':
          description: Incomplete or invalid input
        '401':
          description: Unauthorized
        '409':
          description: Duplicated entry
      tags:
      - Metadata
  /multi-chat:
    get:
      summary: Multiple Sessions
      description: Retrieves metadata for multiple conversations between a specific time frame, no more than one hour apart.
      security:
      - BasicAuth: []
      parameters:
      - description: Timestamp in RFC3339 (YYYY-MM-DDTHH:MM:SSZ) format.
        in: query
        name: from
        required: true
        schema:
          example: '2021-12-20T00:00:00Z'
          type: string
      - description: Timestamp in RFC3339 (YYYY-MM-DDTHH:MM:SSZ) format.
        in: query
        name: to
        required: true
        schema:
          example: '2021-12-20T23:23:59Z'
          type: string
      - description: Enables retrieval of Google Business Messages survey data.
        in: query
        name: include_survey
        required: false
        schema:
          type: boolean
          example: true
      - description: Enables retrieval of Flow completion data (as configured in the solution template).
        in: query
        name: flows
        required: false
        schema:
          type: boolean
          example: true
      responses:
        '200':
          description: Successful request with response body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiMetadataObject'
        '400':
          description: Incomplete or invalid input
        '401':
          description: Unauthorized
        '409':
          description: Duplicated entry
      tags:
      - Metadata
components:
  schemas:
    MetadataObject:
      type: object
      properties:
        agents:
          type: array
          description: Agents that participated in the Conversation.
          items:
            type: object
            properties:
              agent_assign_ts:
                type: string
                description: Date and time last agent connected to Conversation.
                example: '2019-01-01T02:37:04.000Z'
              agent_msg_count:
                type: number
                description: Cumulative number of messages sent by all agents connected to Conversation.
                example: 30
              agent_id:
                type: string
                description: ID of agent connected to Conversation.
                example: 0e403bea-2249-4fd1-b121-13f41d5820a9
              agent_end_ts:
                type: string
                description: Date and time when the agent leave the chat.
                example: '2020-03-26T08:44:16.000Z'
              agent_email:
                type: string
                description: Email of agent connected to Conversation.
                example: agent@test.com
              agent_name:
                type: string
                description: Name of agent connected to Conversation.
                example: Jane Doe
              agent_response_ts:
                type: string
                description: Date and time of first message sent by last agent connected to Conversation.
                example: '2019-01-01T10:52:36.000Z'
              end_tags:
                type: array
                description: List of tags set by last agent on disconnect.
                items:
                  type: string
                  example: end_tag1
              skill:
                type: string
                description: Contains skill tag from last connected agent, if set.
                example: spanish_sales
        all_end_comments:
          type: array
          description: A list including the value of end_comment and any additional comments set by agents or platform.
          items:
            type: string
            example: Ended as anonymous webchat user stopped heartbeating.
        bots:
          type: array
          description: Solutions that participated in the Conversation.
          items:
            type: object
            properties:
              bot_end_ts:
                type: string
                description: Date and time of disconnect for first use case connected to Conversation.
                format: date-time
                example: '2019-01-01T17:05:44.000Z'
              bot_id:
                type: string
                description: Solution identifier of first use case connected to Conversation in "CustomerName.SolutionName" format.
                example: Customer.Solution
              bot_msg_count:
                type: number
                description: Cumulative number of messages sent by all use cases connected to the Conversation.
                example: 30
              bot_start_ts:
                type: string
                description: Date and time of connect for first use case connected to Conversation.
                format: date-time
                example: '2019-01-01T05:26:39.000Z'
              bot_version:
                type: string
                description: Solution version of first use case connected to Conversation.
                example: v6
              convo_tags:
                type: array
                description: List of tags associated with the conversation by the first use case connected to the Conversation.
                items:
                  type: string
                  example: tag1
              kill_reason:
                type: string
                description: Reason the first use case connected to the Conversation was terminated.
                enum:
                - killbot_via_graph_flag: null
                  description: Solution hits a node that ends the conversation or transfers to an agent.
                - killbot_via_consumer_end: null
                  description: Consumer ends the conversation.
                - killbot_abandon_timeout: null
                  description: Conversation times out and ends due to inactivity.
                - killbot_bot_error: null
                  description: Unexpected error occurs that causes a conversation with a solution to end abnormally.
                example: killbot_via_consumer_end
              num_nodes:
                type: number
                description: Number of nodes traversed in the use case graph by the first use case connected to the Conversation.
                example: 28
              user_traversal_path:
                type: array
                description: List of use case nodes that were followed in the course of the conversation with the first use case connected to the Conversation.
                items:
                  type: number
                  example: -23999
        chat_start_ts:
          type: string
          description: Start date and time of Conversation.
          example: '2019-01-01T12:56:33.000Z'
        chat_end_ts:
          type: string
          description: End date and time of Conversation.
          example: '2019-01-01T01:06:38.000Z'
        consumer_msg_count:
          type: number
          description: Number of messages sent by consumer in Conversation.
          example: 15
        consumer_name:
          type: string
          description: Name of end-user. While this field is always included, it may be listed as "Visitor" if the consumer name is not captured.
          example: Mary Smith
        end_comment:
          type: string
          description: Comment added by agent or system.
          example: Offered a discount on next purchase
        flows:
          type: array
          description: List of flows that the user traversed through during their session including details on the completion or abandonment of each flow.
          items:
            type: object
            properties:
              name:
                type: string
                example: resetPassword
              completed:
                type: boolean
              start_ts:
                type: string
                format: date-time
                example: '2019-01-01T01:06:38.000Z'
              complete_ts:
                type: string
                format: nullable
              time_to_completion:
                type: string
                format: nullable
        id:
          type: string
          description: Pypestream Chat ID
          example: 32a4a6d1-7e85-4cda-bb19-3f13d3d93798
        pype_name:
          type: string
          description: Name of Pype that Conversation occurred on.
          example: Company Name
        stream_name:
          type: string
          description: Name of Stream that Conversation was on.
          example: Support
        survey_gateway:
          type: string
          description: Name of the survey source. The value is `google_bm`.
          example: google_bm
        survey_rating:
          type: string
          description: Survey result. For example `VERY_SATISFIED`.
          example: VERY_SATISFIED
        survey_ts:
          type: string
          description: Start time of the survey. For example `2020-05-27T07:36:40.601Z`.
          example: '2019-01-02T07:36:40.601Z'
    MultiMetadataObject:
      type: array
      items:
        $ref: '#/components/schemas/MetadataObject'
      example:
      - agents:
        - agent_assign_ts: '2019-01-01T02:37:04.000Z'
          agent_msg_count: 30
          agent_id: 0e403bea-2249-4fd1-b121-13f41d5820a9
          agent_email: agent@test.com
          agent_end_ts: '2020-03-26T08:44:16.000Z'
          agent_name: Jane Doe
          agent_response_ts: '2019-01-01T10:52:36.000Z'
          end_tags:
          - end_tag1
          - end_tag2
          skill: spanish_sales
        all_end_comments:
        - Ended as anonymous webchat user stopped heartbeating
        - Offered a discount on next purchase
        bots:
        - bot_end_ts: '2019-01-01T17:05:44+00:00'
          bot_id: Customer.Solution
          bot_msg_count: 30
          bot_start_ts: '2019-01-01T05:26:39+00:00'
          bot_version: v6
          convo_tags:
          - tag1
          - tag2
          kill_reason: killbot_via_consumer_end
          num_nodes: 28
          user_traversal_path:
          - -23999
          - -15394
          - -17762
          - -6493
          - -11329
          - 29784
          - 17923
          - -26513
          - -22023
          - -11305
          - 8026
          - 19514
          - 31554
          - -7901
          - 4394
          - 23395
          - -20982
          - -22111
          - 350
          - 29628
          - 28253
          - -31511
          - 18236
          - -30396
          - 13506
          - 19194
          - -19153
          - 2961
        chat_end_ts: '2019-01-01T01:06:38.000Z'
        chat_start_ts: '2019-01-01T12:56:33.000Z'
        consumer_msg_count: 15
        consumer_name: Mary Smith
        end_comment: Offered a discount on next purchase
        flows:
        - name: resetPassword
          completed: false
          start_ts: '2019-01-01T01:06:38+00:00'
          complete_ts: null
          time_to_completion: null
        - name: checkAccountBalance
          completed: true
          start_ts: '2019-01-01T01:06:38+00:00'
          complete_ts: '2019-01-01T01:06:39+00:00'
          time_to_completion: 60000
        id: 32a4a6d1-7e85-4cda-bb19-3f13d3d93798
        pype_name: Company Name
        stream_name: Support
        survey_gateway: google_bm
        survey_rating: VERY_SATISFIED
        survey_ts: '2019-01-02T07:36:40.601Z'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic