openapi: 3.2.0
info:
  contact:
    email: support@pypestream.com
  termsOfService: https://www.pypestream.com/privacy-policy/
  title: Engagement Endpoints API
  version: 1.0.0
  description: API to be consumed by the 3rd party apps.
servers:
- url: https://engagement-api.pypestream.com/
  description: Live
- url: https://engagement-api-sandbox.pypestream.com/
  description: Sandbox
security: []
tags:
- description: API to be consumed by the 3rd party apps.
  name: Endpoints
paths:
  /messaging/v1/consumers/anonymous_session:
    post:
      callbacks: {}
      deprecated: false
      operationId: anonymous_session
      parameters:
      - name: X-Pypestream-Webhook-URL
        in: header
        description: 'When a valid URL is provided in this header, all asynchronous events will be sent to the specified URL as `POST` requests. The request body will contain a JSON object with two fields: `type` (event name) and `payload` (an object containing the same information that would have been sent through WebSocket).'
        required: false
        schema:
          type: string
          format: uri
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnonymousSession'
        description: Creates an User
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnonymousSessionResponse'
          description: Successful operation
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
          description: Internal Error
      summary: Create User
      description: The Engagement API provides a user creation method, which is essential before starting an engagement. Follow the instructions below to set up a user properly.
      tags:
      - Endpoints
  /messaging/v1/chats/{chat_id}/start:
    post:
      callbacks: {}
      deprecated: false
      operationId: start
      parameters:
      - description: The 'chat_id' received with the Create User response
        in: path
        name: chat_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartChat'
        description: Starts an Engagement
        required: true
      responses:
        '202':
          description: Successful operation
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExistingActiveConversation'
          description: Existing active conversation
        '428':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreconditionRequired'
          description: The engagement is not ready to receive messages yet, please wait until you receive the 'chat:ready' event through the Websocket connection
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
          description: Internal Error
      security:
      - BearerAuth: []
      summary: Start Engagement
      description: Use this method to start an engagement.
      tags:
      - Endpoints
  /messaging/v1/chats/{chat_id}/message:
    post:
      callbacks: {}
      deprecated: false
      operationId: message
      parameters:
      - description: The 'chat_id' received with the Create User response
        in: path
        name: chat_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessage'
        description: Sends a new message to the engagement
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
          description: Internal Error
      security:
      - BearerAuth: []
      summary: Send Message
      description: Use this method to send a message.
      tags:
      - Endpoints
  /messaging/v1/chats/{chat_id}/ping:
    post:
      tags:
      - Endpoints
      summary: Keep alive Engagement
      description: Maintain Engagement Connection
      operationId: ping
      parameters:
      - name: chat_id
        in: path
        required: true
        description: The 'chat_id' value obtained from the response of the 'Create User' method.
        schema:
          type: string
          format: uuid
      requestBody:
        description: 'To keep the engagement alive, send a ping request with the following parameters:'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Ping'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pong'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
      - BearerAuth: []
  /messaging/v1/chats/{chat_id}/type:
    post:
      tags:
      - Endpoints
      summary: Typing Indicator
      description: Request to signal that the end user has started or stopped typing
      operationId: type
      parameters:
      - name: chat_id
        in: path
        required: true
        description: The 'chat_id' value obtained from the response of the 'Create User' method.
        schema:
          type: string
          format: uuid
      requestBody:
        description: This request helps identify whether the end user is currently typing or not.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Type'
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '500':
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
      - BearerAuth: []
  /messaging/v1/chats/{chat_id}/snapshot:
    post:
      callbacks: {}
      deprecated: false
      operationId: snapshot
      parameters:
      - description: The 'chat_id' received with the Create User response
        in: path
        name: chat_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Snapshot'
        description: Generate Snapshot
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotResponse'
          description: Successful operation
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
          description: Internal Error
      security:
      - BearerAuth: []
      summary: Generate Snapshot
      description: Use this method to generate a snapshot of the engagement. It includes information such as the conversation history.
      tags:
      - Endpoints
  /messaging/v1/chats/{chat_id}/end:
    post:
      callbacks: {}
      deprecated: false
      operationId: end
      parameters:
      - description: The 'chat_id' received with the Create User response
        in: path
        name: chat_id
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndChat'
        description: Ends the Engagement
        required: true
      responses:
        '204':
          description: Successful operation
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad request
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
          description: Internal Error
      security:
      - BearerAuth: []
      summary: End Engagement
      description: Use this request to end an engagement.
      tags:
      - Endpoints
components:
  schemas:
    Type:
      type: object
      required:
      - chat_id
      - from
      - is_typing
      - from_side
      properties:
        chat_id:
          type: string
          format: uuid
          description: The 'chat_id' value obtained from the response of the 'Create User' method.
        from:
          type: string
          format: uuid
          description: The 'id' value obtained from the response of the 'Create User' method.
        is_typing:
          type: boolean
          description: Set to 'true' if the end user is typing and 'false' otherwise.
          example: true
        from_side:
          type: string
          description: The side that originates the typing status request.
          example: consumer
    Ping:
      type: object
      required:
      - user_id
      properties:
        user_id:
          type: string
          format: uuid
          description: The 'id' value obtained from the response of the 'Create User' method.
        seq:
          type: integer
          description: An incremental integer that will be the same in the pong response. This helps in tracking the correspondence between ping and pong messages.
          example: 1
    EndChat:
      properties:
        ended_by:
          description: The ID of the user that ended the engagement
          example: consumer_3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        pype_id:
          description: The 'web_chat_pype_id' received with the Create User response
          type: string
        source:
          description: Source of the end engagement request (client or server)
          example: client
          type: string
        user_id:
          description: The 'id' received with the Create User response
          format: uuid
          type: string
        version:
          description: API version
          example: '1'
          type: string
      required:
      - pype_id
      - user_id
      - ended_by
      - source
      - version
      type: object
    Error:
      properties:
        message:
          type: string
        source:
          type: string
        type:
          type: string
      required:
      - source
      - type
      - message
      type: object
    SnapshotResponse:
      properties:
        consumer_type:
          type: string
          description: Type of consumer. Possible values are 'anonymous' and 'server'
          example: anonymous
        start_ts:
          description: Unixtime for start of the engagement
          example: 1643423689
          type: integer
        id:
          description: The 'id' of the engagement
          format: uuid
          type: string
        initial_msg:
          description: Initial message of engagement
          type: string
        end_ts:
          description: Unixtime for end of the engagement
          example: 1643423689
          type: integer
        bot:
          description: The microapp ID
          type: string
        participants:
          description: List of participants of the engagement
          items:
            properties: {}
            type: object
          type: array
        status:
          description: Status of the engagement
          type: string
          example: active
        consumer_name:
          description: The Name of the consumer
          format: uuid
          type: string
        history:
          description: List of all messages of the engagement
          items:
            properties: {}
            type: object
          type: array
        consumer:
          description: The ID of the consumer
          format: uuid
          type: string
        with_end_bot:
          description: Indicates if the engagement contains a survey microapp
          type: boolean
        read_receipts:
          items:
            type: string
          type: array
        originating_side:
          type: string
          description: 'The entity that started the engagement. Possible values: ''consumer'', ''bot'' and ''agent'''
          example: bot
        consumer_msg_count:
          description: The number of messages sent by the consumer
          type: integer
        participant_history:
          description: List of participants changes of the engagement
          items:
            properties: {}
            type: object
          type: array
        bot_name:
          description: The 'id' of the last microapp used
          example: MyNewCustomer.MyNewMicroapp
          type: string
        pype_id:
          description: ID of the Pype
          format: uuid
          type: string
        seq_num:
          description: Sequential number of the last message received or sent
          type: integer
        version:
          description: Version of chat:snapshot_response
          type: integer
        agent_name:
          description: The name of the agent
          type: string
        agent:
          description: The agent ID
          type: string
        encrypted:
          description: Indicates if the engagement is encrypted
          type: boolean
        end_tags:
          description: Engagement end tags
          items:
            type: string
          type: array
        agent_response_ts:
          description: Unixtime of the last agent response
          example: 1643423689
          type: integer
        pype_name:
          description: The 'id' of the Pype
          format: uuid
          type: string
        stream_name:
          description: Name of the Stream
          type: string
        stream_id:
          description: ID of the Stream
          format: uuid
          type: string
        bots_started_count:
          description: Number of microapps that ran in the engagement
          type: integer
        persist_bot_history:
          description: Indicates if the engagement should save the microapp history
          type: boolean
        bot_enabled:
          description: The chat has a micrapp assigned
          type: boolean
        target_bot_node:
          type: string
          description: Last node reached by the MicroApp.
        ended_by:
          description: The ID of the user that ended the engagement
          example: consumer_3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        gateway:
          description: 'Platform used by the client app. Possible value(s): pypestream_widget'
          example: pypestream_widget
          type: string
        originator_user_id:
          type: string
          description: The ID of the user who originated the engagement
        agent_msg_count:
          description: The number of messages sent by the agent
          type: integer
        originator_name:
          type: string
          description: The name of the user who originated the engagement
        bot_msg_count:
          description: The number of messages sent by the microapp
          type: integer
        agent_is_assigned:
          description: Indicates if an agent is assigned to the engagement
          type: boolean
        participant_changed:
          description: Indicates if the engagement participant has changed
          type: boolean
        agent_routing:
          description: Who routed this agent.
          type: string
        app_id:
          description: The ID of the Pype to engage with
          format: uuid
          type: string
        user_read_counts:
          description: List of consumer reads.
          items:
            properties: {}
            type: object
          type: array
        end_comment:
          description: Engagement end comment
          type: string
        gateway_metadata:
          description: User information
          properties: {}
          type: object
        delivery_receipts:
          items:
            type: string
          type: array
        agent_assign_ts:
          description: Unixtime of the agent assignment time
          example: 1643423689
          type: integer
      required:
      - id
      - history
      type: object
    PreconditionRequired:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
        message:
          type: string
      required:
      - message
      - errors
      type: object
    ExistingActiveConversation:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
        message:
          type: string
      required:
      - message
      - errors
      type: object
    AnonymousSessionResponse:
      properties:
        access_token:
          description: Access token to be sent as Bearer token on authorization header for all engagement requests
          format: hash
          type: string
        apn_token:
          type: string
        avatar:
          format: uri
          type: string
        avatar_generated:
          type: boolean
        chat_id:
          description: The ID of the Engagement you've been assigned to.
          format: uuid
          type: string
        created_at:
          example: 1643423689
          format: int64
          type: integer
        data_version:
          format: int32
          type: integer
        email:
          format: email
          type: string
        first_name:
          type: string
        gcm_token:
          type: string
        id:
          description: ID of your User
          format: uuid
          type: string
        last_name:
          type: string
        location:
          type: string
        masking_rules:
          items:
            format: regex
            type: string
          type: array
        phone:
          format: phone
          description: The Phone Number of the client.
          type: string
        pype_logo:
          format: uri
          type: string
        role:
          type: string
        sneekpeak:
          type: boolean
        web_chat_pype_id:
          description: ID of the Pype
          type: string
        web_chat_pype_name:
          type: string
        web_chat_stream_id:
          description: ID of the Stream
          format: uuid
          type: string
        widget_auto_start_with_bot:
          type: boolean
        widget_branding:
          type: string
        widget_data:
          properties: {}
          type: object
        widget_gateway_id:
          type: string
        widget_version:
          type: string
      required:
      - access_token
      - chat_id
      - id
      - web_chat_pype_id
      - web_chat_stream_id
      type: object
    NotFound:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
        message:
          type: string
      required:
      - message
      - errors
      type: object
    Snapshot:
      properties:
        from:
          description: The 'id' received with the Create User response
          format: uuid
          type: string
      required:
      - from
      type: object
    BadRequest:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/Error'
          type: array
        message:
          type: string
      required:
      - message
      - errors
      type: object
    SendMessage:
      properties:
        app_object:
          format: hash
          description: An object for the embedded object data.
          type: string
        campaign_id:
          type: string
          description: The id of the campaign this message originated from.
        client_msg_id:
          type: string
          description: Client generated unique message id.
        correlation_id:
          type: string
          description: A unique ID set by the client which can be used to correlate the responding acknowledgement of the request.
        file:
          description: A URL to a file to embed in the message.
          format: uri
          type: string
        file_status:
          example: uploading
          description: 'Indicates if the file is available for downloading from the URL. States are: uploading, ready, failed'
          type: string
        from:
          description: The 'id' received with the Create User response
          format: uuid
          type: string
        from_side:
          description: 'Indicates the source of the message. Possible value(s): anonymous_consumer'
          example: anonymous_consumer
          type: string
        gateway:
          description: 'Platform used by the client app. Possible value(s): pypestream_widget'
          example: pypestream_widget
          type: string
        msg:
          description: The message that's being sent
          type: string
        msg_type:
          description: Message type. We support `text` and `embed`. If it is `text`, then the `msg` field is required, but if it is `embed`, then the msg will be null, and the `app_object` and `secure_app_object` fields are required.
          example: text
          type: string
        persist_to_history:
          type: boolean
          description: Flags whether this message should be written to the persistent history.
        secure_app_object:
          type: boolean
          description: Flags whether this is a secure message and thus should not be persisted.
        user_id:
          description: The 'id' received with the Create User response
          format: uuid
          type: string
        version:
          description: API version
          example: '1'
          type: string
      required:
      - from
      - from_side
      - msg
      - msg_type
      - user_id
      - version
      - gateway
      type: object
    AnonymousSession:
      properties:
        app_id:
          description: The unique identifier of the Pype that the user will engage with.
          format: uuid
          type: string
        app_type:
          description: 'The category of the app. Valid options are: ''consumer''.'
          example: consumer
          type: string
        browser_language:
          description: The language locale used by the client's browser (e.g., 'en-US').
          example: en-US
          type: string
        device_id:
          description: The device's universally unique identifier (UUID) connecting to the conversation.
          type: string
        device_type:
          description: 'The category of the client device. Valid options include: ''apple,'' ''android'', ''browser,'' ''mobile-browser,'' and ''web.'''
          example: web
          type: string
        ip_address:
          description: The IP address of the client.
          type: string
        language:
          type: string
          description: The language used in the microapp.
          example: en
        last_viewed_url:
          description: The most recently visited URL by the client.
          example: http://www.example.com
          type: string
        location:
          description: The geographical location of the client (e.g., 'Richmond, VA, United States').
          type: string
        passthrough:
          description: Additional user information in JSON format.
          type: string
        platform:
          description: The client's platform or operating system (e.g., 'ios', 'android', 'MacOSX', etc.).
          example: Mac OS X10_14_4
          type: string
        referring_site:
          description: The website that referred the client.
          example: http://www.example.com
          type: string
        screen_resolution:
          description: The screen resolution of the client's device (e.g., '1280x720').
          example: 1280 x 800
          type: string
        token:
          description: The APN/GCM token is provided by the client.
          format: hash
          type: string
        user_browser:
          description: The browser used by the client.
          example: Chrome 74.0.3729.131
          type: string
      required:
      - app_id
      - browser_language
      - referring_site
      - user_browser
      type: object
    StartChat:
      properties:
        app_id:
          description: The 'app_id' sent when creating a user
          format: uuid
          type: string
        consumer:
          description: The ID of the consumer.
          example: consumer_3fa85f64-5717-4562-b3fc-2c963f66afa6
          type: string
        gateway:
          description: 'Platform used by the client app. Possible value(s): pypestream_widget'
          example: pypestream_widget
          type: string
        stream_id:
          description: The 'web_chat_stream_id' received with the Create User response.
          format: uuid
          type: string
        user_id:
          description: The 'id' received with the Create User response.
          format: uuid
          type: string
        version:
          description: API version
          example: '1'
          type: string
      required:
      - app_id
      - stream_id
      - user_id
      - consumer
      - version
      - gateway
      type: object
    Pong:
      type: object
      required:
      - chat_id
      - user_id
      properties:
        chat_id:
          type: string
          format: uuid
          description: The 'id' of the chat
        user_id:
          type: string
          format: uuid
          description: The 'id' received with the Create User response
        seq:
          type: integer
          description: Incremental integer, will be the same on Ping response
          example: 1
    InternalError:
      properties:
        message:
          type: string
      required:
      - message
      type: object
  securitySchemes:
    BearerAuth:
      description: 'access_token received with the Create User response must be provided via `Authorization: Bearer ` header'
      scheme: bearer
      type: http
x-readme:
  explorer-enabled: true
  proxy-enabled: true
  samples-enabled: true