swagger: '2.0'
host: orgId.via.aspect-cloud.net
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
info:
  version: 2.0.1
  title: Alvaria Public Cloud Messaging (Chat/SMS) REST API
  contact:
    name: Alvaria
    url: 'https://www.alvaria.com'
  license:
    name: 'License: Creative Commons Attribution 4.0 International Public License'
    url: 'https://creativecommons.org/licenses/by/4.0/legalcode'
  description: |-
    ## Overview

    The Alvaria Public Cloud&trade; Messaging (Chat/SMS) REST APIs enable a custom agent application to send text and URLs using a current chat or SMS interaction.  Please note that the group of scopes most likely needed when you create a custom agent interface are engagementcenterapi, provisioningapi, messagingapi, outreachapi and streamingapi.

    [Follow this link if you would like to see the events generated by sending these requests.](../../referencedocs/ViaStreamingEvents.pdf)

paths:
  '/via/v2/organizations/{orgId}/messaging/users/{userId}/sendText':
    post:
      tags:
        - Users
      operationId: Send Text
      summary: User Send Text
      description: This sends a request to the Messaging subsystem containing text on an interaction.
      consumes:
        - application/json
      produces:
        - application/json
      schemes:
        - https
      parameters:
        - name: orgId
          in: path
          description: Name of a customer organization
          required: true
          type: string
        - name: Authorization
          in: header
          description: 'Authentication token with the value: ''Bearer {accessToken}'', where {accessToken} was returned from a call to the authorization endpoint.'
          required: true
          type: string
        - name: x-api-key
          in: header
          required: true
          type: string
          description: Alvaria-provided value used to track API endpoint usage
        - name: via-client-sessionid
          in: header
          description: 'Identifier representing a long-lived HTTP interchange between Alvaria&trade; Cloud and an entity when the entity is a contact, external client application, or authenticated user. This interchange is called the streaming session. Streaming sessions are used for operations such as exchanging text messages and retrieving events related to user activity.'
          required: true
          type: string
        - name: userId
          in: path
          description: 'Alvaria-generated unique identifier for a user instance that can be retrieved prior to use from the provisioning rest API.  The url is /via/v2/organizations/{orgId}/provisioning/users.'
          required: true
          type: string
        - name: sendTextParms
          in: body
          description: Send Text information
          required: true
          schema:
            $ref: '#/definitions/SendTextParmsSchema'
      responses:
        '202':
          description: Successful response
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '405':
          description: Method Not Allowed
          schema:
            $ref: '#/definitions/ErrorResponse'
        '410':
          description: Gone
          schema:
            $ref: '#/definitions/ErrorResponse'
        '422':
          description: Cannot Process Entity
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - oauth:
            - messagingapi
  '/via/v2/organizations/{orgId}/messaging/users/{userId}/notification':
    post:
      tags:
        - Users
      operationId: Notification
      summary: User Send Notification state
      description: To allow for slight message delays in transit, the next `composing` notification should be sent before the `expiresAfterSeconds` timeframe. For example, if the `expiresAfterSeconds` field is set to ten seconds, it is recommended to send the `composing` state at least once every nine seconds while the user is actively typing. The receiving entity will reset its typing indicator expiration after each `composing` notification. After the typing indicator expiration (ten seconds in this example) of not receiving the `composing` notification, the receiving party's UI will hide the typing indicator.
      consumes:
        - application/json
      produces:
        - application/json
      schemes:
        - https
      parameters:
        - name: orgId
          in: path
          description: Name of a customer organization
          required: true
          type: string
        - name: Authorization
          in: header
          description: 'Authentication token with the value: ''Bearer {accessToken}'', where {accessToken} was returned from a call to the authorization endpoint.'
          required: true
          type: string
        - name: x-api-key
          in: header
          required: true
          type: string
          description: Alvaria-provided value used to track API endpoint usage
        - name: via-client-sessionid
          in: header
          description: 'Identifier representing a long-lived HTTP interchange between Alvaria&trade; Cloud and an entity when the entity is a contact, external client application, or authenticated user. This interchange is called the streaming session. Streaming sessions are used for operations such as exchanging text messages and retrieving events related to user activity.'
          required: true
          type: string
        - name: userId
          in: path
          description: 'Alvaria-generated unique identifier for a user instance that can be retrieved prior to use from the provisioning rest API.  The url is /via/v2/organizations/{orgId}/provisioning/users.'
          required: true
          type: string
        - name: notificationParms
          in: body
          description: Client change of state notification, e.g. composing.
          required: true
          schema:
            $ref: '#/definitions/NotificationParmsSchema'
      responses:
        '202':
          description: Successful response
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '405':
          description: Method Not Allowed
          schema:
            $ref: '#/definitions/ErrorResponse'
        '410':
          description: Gone
          schema:
            $ref: '#/definitions/ErrorResponse'
        '422':
          description: Cannot Process Entity
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - oauth:
            - messagingapi
  '/via/v2/organizations/{orgId}/messaging/users/{userId}/sendUrl':
    post:
      tags:
        - Users
      operationId: Push Url
      summary: User Push Url
      description: This sends a request to the Messaging subsystem containing a URL for an interaction.
      consumes:
        - application/json
      produces:
        - application/json
      schemes:
        - https
      parameters:
        - name: orgId
          in: path
          description: Name of a customer organization
          required: true
          type: string
        - name: Authorization
          in: header
          description: 'Authentication token with the value: ''Bearer {accessToken}'', where {accessToken} was returned from a call to the authorization endpoint.'
          required: true
          type: string
        - name: x-api-key
          in: header
          required: true
          type: string
          description: Alvaria-provided value used to track API endpoint usage
        - name: via-client-sessionid
          in: header
          description: 'Identifier representing a long-lived HTTP interchange between Alvaria&trade; Cloud and an entity when the entity is a contact, external client application, or authenticated user. This interchange is called the streaming session. Streaming sessions are used for operations such as exchanging text messages and retrieving events related to user activity.'
          required: true
          type: string
        - name: userId
          in: path
          description: 'Alvaria-generated unique identifier for a user instance that can be retrieved prior to use from the provisioning rest API.  The url is /via/v2/organizations/{orgId}/provisioning/users.'
          required: true
          type: string
        - name: pushUrlParms
          in: body
          description: send URL information
          required: true
          schema:
            $ref: '#/definitions/SendUrlParmsSchema'
      responses:
        '202':
          description: Successful response
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
          schema:
            $ref: '#/definitions/ErrorResponse'
        '405':
          description: Method Not Allowed
          schema:
            $ref: '#/definitions/ErrorResponse'
        '410':
          description: Gone
          schema:
            $ref: '#/definitions/ErrorResponse'
        '422':
          description: Cannot Process Entity
          schema:
            $ref: '#/definitions/ErrorResponse'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResponse'
        '503':
          description: Service Unavailable
          schema:
            $ref: '#/definitions/ErrorResponse'
      security:
        - oauth:
            - messagingapi
securityDefinitions:
  oauth:
    type: oauth2
    authorizationUrl: 'https://myaspect.{region}.id.aspect-cloud.net/tokenservice/oauth2/access_token?realm={orgId}'
    flow: implicit
    scopes:
      messagingapi: manage access to engagement center
definitions:
  SendTextParmsSchema:
    type: object
    properties:
      interactionId:
        type: string
        description: Alvaria-generated unique identifier for the interaction for which you want to send text.
        example: '4321'
      entityName:
        type: string
        description: This contains the name of the entity for which you want to send text.
        example: contactCenterAgent
      entityType:
        type: string
        description: This contains the type of entity for which you want to send text.
        example: Agent
        enum:
          - Agent
          - Monitor
          - System
      text:
        type: string
        description: This is the text string that you want to send.
        example: Hi this is an example of a text string.
    required:
      - interactionId
      - entityName
      - entityType
      - text
  NotificationParmsSchema:
    type: object
    properties:
      interactionId:
        type: string
        description: Alvaria-generated unique identifier for the interaction for which you want to send text.
        example: '4321'
      entityName:
        type: string
        description: This contains the name of the entity for which you want to send text.
        example: contactCenterAgent
      entityType:
        type: string
        description: This contains the type of entity for which you want to send text.
        example: Agent
        enum:
          - Agent
          - Monitor
          - System
      state:
        type: string
        description: Client change of state notification, e.g. composing.
        example: composing
        enum: 
          - composing
      expiresAfterSeconds:
        type: integer
        description: Number of seconds the notification should be considered active. Maximum value is 30 seconds.
        example: 10
    required:
      - interactionId
      - entityName
      - entityType
      - state
  SendUrlParmsSchema:
    type: object
    properties:
      interactionId:
        type: string
        description: Alvaria-generated unique identifier for the interaction for which you want to send a URL.
        example: '4321'
      entityName:
        type: string
        description: This contains the name of the entity for which you want to send a URL.
        example: contactCenterAgent
      entityType:
        type: string
        description: This contains the type of the entity for which you want to send a URL.
        example: Agent
        enum:
          - Agent
          - Monitor
          - System
      url:
        type: string
        description: This contains a URL.
        example: 'https://www.alvaria.com'
    required:
      - interactionId
      - entityName
      - entityType
      - url
  ErrorResponse:
    type: object
    properties:
      code:
        type: integer
        description: HTTP error status
        example: 404
      message:
        type: string
        example: not found
      errors:
        type: array
        items:
          $ref: '#/definitions/Error'
  Error:
    type: object
    properties:
      scope:
        type: string
        example: scope
      reason:
        type: string
        example: reason
      message:
        type: string
        example: message
tags: []
