swagger: '2.0'
info:
  version: 2.0.0
  title: Alvaria Cloud Server Messaging 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&trade; Cloud Server Messaging REST APIs enable a custom server application to register and send messages and events using a text-based interaction. This interaction can also contain URLs for multimedia files. 
    The registered session has a maximum life cycle of 4 hours and will be disconnected by Alvaria&trade; Cloud if the session is still active after 4 hours.
    
    Custom server applications will receive messages and events through the preconfigured callback/webhook URL. These events and messages are defined in <a href="#callback-event-list">Calback Event List</a>.

    Backoff and retry procedures should be implemented for when error conditions occur (e.g. network outages, throttling, etc)
    
    
    # Steps to Invoke Server Messaging APIs
    
    ## Get oauth Token
    The first step is to get an Alvaria&trade; oauth access token. The Alvaria&trade; REST API endpoint oauth token generation process is defined in [Alvaria&trade; Cloud REST API Developer's Guide](ViaRestDeveloperGuide.html#security).
    
    The return value's `access_token` is used as the Bearer token in all subsequent REST calls.
    
    ```
      // Alvaria™ oauth token example response
      {
        "access_token": "fc1fee03-c4a2-4db4-add7-dd6c0542ff93",
        "scope": "servermessagingapi",
        "token_type": "Bearer",
        "expires_in": 3599
      }
    ```
    
    ## Establish a Server Messaging Session
    To create a server messaging session with Alvaria&trade; Cloud call the <a href="#create-session">Create Session</a> endpoint, which responds with a provisional Server Messaging sessionId. 
    Upon successful creation of the Server Messaging session, a <a href="#tocsnewsessioncallback">New Session</a> event will be sent as a callback event with status SUCCESS. 
    The return value's 'sessionId' is used as the 'server-messaging-session-id' header in all subsequent Server Messaging REST API calls.
    
    ## Send Message
    To send messages to the Alvaria&trade; Cloud call the <a href="#send-message-2">Send Message</a> endpoint. 
    The Server Messaging 'sessionId' from the previous step needs to be passed in each request. For every message sent, a unique 'messageId' will be returned. 
    In case of any failure in processing the message sent, <a href="#tocsmessagestatuscallback">Message Status</a> event will be sent with status FAILED.
    
    ## Disconnect a Server Messaging Session
    The client can end a Server Messaging session by calling the <a href="#delete-session">Delete Session</a> endpoint, which will immediately send a wrap message to the Agent (if there is one in the session). 
    A <a href="#tocssessionendcallback">Session End</a>  event will be sent as a callback event with the result of the request.
    
    
    # Callback Event List
    Callback (webhook) events received from Server Messaging API are grouped by category:
     - System Events
     - Messages
    
    Authentication of all server messaging callback events and messages can be performed using Alvaria Cloud generated JWT tokens.
    
    ## System Events
    The table below describes the events that may be generated when Server Messaging API calls are made or when the system initiates notifications such as interaction state changes.
    | **Event Type**  || **Description** |
      | --- | --- | --- |
      | <a href="#tocsnewsessioncallback">`NEW_SESSION`</a>  || This event is received in response to a POST session request. This event informs the client that the Server Messaging session has been created successfully or not.|
      | <a href="#tocsagentjoinedcallback">`AGENT_JOINED`</a>  || This event indicates that an agent has joined to a Server Messaging session.|
      | <a href="#tocs_messagestatuscallback">`MESSAGE_STATUS`</a>  || This event indicates the status of a POST message request.|
      | <a href="#tocssessionreroutecallback">`SESSION_REROUTE`</a>  || This event informs the client that the call has been transferred to a worktype or agent.|
      | <a href="#tocssessionendcallback">`SESSION_END`</a>  || This event will signal that client session has been disconnected from the Alvaria&trade; Cloud.  Once you receive this event you should not use the server messaging sessionId anymore.|
      
    ## Messages
    The table below describes the message that may be generated by the system or passed from an agent.
      | **Type**  || **Description** |
      | --- | --- | --- |
      | <a href="#tocsmessagecallback">`MESSAGE`</a>  || This event indicates that text or attachment has been received from the system or agent.|

    # Configure Webhook URL
    Before you can start receiving Server Messaging notifications you will need to create an endpoint (Callback URL) on your server to receive notifications. Once the callback URL is configured please share it with Alvaria Customer Care so that a manual configuration step can be completed. 

    Callback URL Specifications:
     - Callback URL must be reachable from the Alvaria System
     - Callback URL must be able to process HTTPS requests
     - Callback URL is like any regular URL. For example: https://www.example.com/webhooks/server-messaging
     - When Alvaria Server Messaging sends a webhook request to your callback URL then:
         - Your server response with an HTTP status code 200 is considered as successful.
         - If your server responds with an HTTP status code other than 200, or if we are unable to deliver the webhook for another reason, we will keep trying with decreasing frequency until the request succeeds, for up to 4 hours.

    # Callback Event Authentication
    Each Server Messaging callback request will include a JSON Web Token (JWT) in the ‘Authorization’ header. This token is generated using a preconfigured secret generated using the SHA-256 algorithm and can also be used to validate the payload of the request.
    The secret is generated once the callback URL is provided to Alvaria Customer Care as per <a href="#configure-webhook-url">Configure Webhook URL</a> and you will be notified of the secret securely.
    
host: orgId.via.aspect-cloud.net
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
paths:
  
  '/via/v2/organizations/{orgId}/serverMessaging/session':
    post:
      operationId: createSession 
      summary: Create Session
      description: Creates a new Server Messaging Session.
      tags:
        - Session
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: orgId
          in: path
          required: true
          type: string
          description: Name of a customer organization
        - 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: context
          in: body
          required: true
          schema:
            $ref: '#/definitions/NewSession'
          description: Name/Value pairs that are stored within the Session that can be accessed for channel specific functionality
      security:
        - oauth:
            - servermessagingapi
      responses:
        '202':
          description: Accepted
          schema:
            $ref: '#/definitions/SessionResponse'
        '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'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
    delete:
      operationId: deleteSession
      summary: Delete Session
      description: Deletes an existing Server Messaging Session.
      tags:
        - Session
      parameters:
        - name: orgId
          in: path
          required: true
          type: string
          description: Name of a customer organization
        - 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: server-messaging-session-id
          in: header
          required: true
          type: string
          description: Identifier representing the specific Server Messaging session. This is the 'sessionId' retruned from <a href='#create-session'>Create Session</a> request.
        - name: x-api-key
          in: header
          required: true
          type: string
          description: Alvaria-provided value used to track API endpoint usage
      security:
        - oauth:
            - servermessagingapi
      responses:
        '202':
          description: Accepted
        '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'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'
  '/via/v2/organizations/{orgId}/serverMessaging/message':
    post:
      operationId: sendMessage
      summary: Send Message
      description: This sends a request to the Server Messaging subsystem containing text and or url.
      tags:
        - Message
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: orgId
          in: path
          required: true
          type: string
          description: Name of customer organization.
        - 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: server-messaging-session-id
          in: header
          required: true
          type: string
          description: Identifier representing the specific Server Messaging session. This is the 'sessionId' retruned from <a href='#create-session'>Create Session</a> request.
        - name: Request
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'
      security:
        - oauth:
            - servermessagingapi
      responses:
        '202':
          description: Accepted
          headers:
            Access-Control-Allow-Origin:
              type: string
          schema:
            $ref: '#/definitions/MessageResponse'    
        '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'
        '429':
          description: Too Many Requests
          schema:
            $ref: '#/definitions/ErrorResponse'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ErrorResponse'         
definitions:
  NewSession:
    type: object
    required:
      - workTypeId
      - contactName
    properties:
      workTypeId:
        type: string
        description: Alvaria-generated unique identifier for the WorkType.
        example: 32
      contactName:
        type: string
        description: Name of the contact the interaction originated from. Typically the customer name.
        example: "Customer Name"
      integration:
        type: string
        description: Integration type the custom server application is using for tracking purposes
        example: "SMS"
  SessionResponse:
    type: object
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for the Server Messaging Session. Use this identifier in all subsequent Server Messaging API calls for this session.
        example: ab7dbcbc-c041-4ac0-8ca0-5a0961f7be5
    required:
        - sessionId    
  Message:
    type: object
    properties:
      text:
        type: string
        example: Hello there.
      attachment:
        $ref: '#/definitions/Attachment'
  Attachment:
      type: object
      properties:
        type:
          type: string
          description: Attachment type
          example: Image
          enum:
            - Image
            - File
            - Audio
            - Video
        url:
          type: string
          description: URL to the attachment
          example: "http://www.mydomain.com/image/graphics01.jpg"
      required:
        - type
        - url    
  MessageResponse:
    type: object
    properties:
      messageId:
        type: string
        description: Alvaria-generated unique identifier for the message
        example: 22D45513-66F7-4A02-9998-EF8E72AB2363   
    required:
        - messageId       
  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
  NewSessionCallback:
    type: object
    description: A client will receive this event in response to a <a href='#create-session'>Create Session</a> request.
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for a server messaging session
      event:
        type: string
        description: 'Type of event.'
        enum:
          - NEW_SESSION
      status:
        type: string
        description: 'Status of the event.'
        enum:
          - SUCCESS
          - FAILED
      statusMessage:
        type: string
        description: 'Status message if available. Present only when status is FAILED'
      eventId:
        type: string
        description: 'Alvaria-generated unique identifier for the event'
    required:
      - sessionId
      - event
      - status
      - eventId
    example:
      sessionId: '38D1FBA0-2079-42FB-93C2-0DE301CF8FF5'
      event: NEW_SESSION
      status: SUCCESS
      eventId: '22D45513-66F7-4A02-9998-EF8E72AB2363'
  AgentJoinedCallback:
    type: object
    description: 'An agent has been added to the server messaging session.'
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for a server messaging session
        example: 38D1FBA0-2079-42FB-93C2-0DE301CF8FF5
      event:
        type: string
        description: 'Type of event.'
        enum:
          - AGENT_JOINED
      agentAlias:
        type: string
        description: Agent's first name
        example: 'John'
      eventId:
        type: string
        description: 'Alvaria-generated unique identifier for the event'
        example: '22D45513-66F7-4A02-9998-EF8E72AB2363'
    required:
      - sessionId
      - event
      - agentAlias
      - eventId    
  MessageStatusCallback:
    type: object
    description: A client will receive this event in response to a <a href='#send-message-2'>Send Message </a> request. This will only be sent for failed messages.
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for a server messaging session
        example: 38D1FBA0-2079-42FB-93C2-0DE301CF8FF5
      event:
        type: string
        description: 'Type of event.'
        enum:
          - MESSAGE_STATUS
      status:
        type: string
        description: Status of the message
        enum:
          - FAILED
      messageId:
        type: string
        description: MessageId returned during POST message request
        example: 'd1e73bad-6efe-462f-8182-913f2f1306b4'  
      statusMessage:
        type: string
        description: 'Status message if availble. Present only when status is FAILED'
        example: 'Session does not exist'  
      eventId:
        type: string
        description: 'Alvaria-generated unique identifier for the event'
        example: '22D45513-66F7-4A02-9998-EF8E72AB2363'
    required:
      - sessionId
      - event
      - status
      - messageId
      - eventId        
  SessionReRouteCallback:
    type: object
    description: 'Server messaging session has been rerouted to a worktype or agent'
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for a server messaging session.
      event:
        type: string
        description: 'Type of event.'
        enum:
          - SESSION_REROUTE
      agentAlias:
        type: string
        description: Agent's first name to which the interaction rerouted. Present only if interaction is rerouted to an agent.
      worktypeId:
        type: string
        description: Worktype Id to which the interaction rerouted. Present only if interaction is rerouted to a worktype.
      eventId:
        type: string
        description: 'Alvaria-generated unique identifier for the event'
    required:
      - sessionId
      - event
      - eventId  
    example:
      sessionId: '38D1FBA0-2079-42FB-93C2-0DE301CF8FF5'
      event: SESSION_REROUTE
      eventId: '22D45513-66F7-4A02-9998-EF8E72AB2363'
      agentAlias: John
  SessionEndCallback:
    type: object
    description: A client will receive this event in response to a <a href='#delete-session'>Delete Session</a> request or signal that the Server Messaging session has been disconnected by Alvaria&trade; Cloud.
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for a server messaging session
        example: 38D1FBA0-2079-42FB-93C2-0DE301CF8FF5
      event:
        type: string
        description: 'Type of event.'
        enum:
          - SESSION_END
      status:
        type: string
        description: 'Status of the event.'
        enum:
          - SUCCESS
          - FAILED
      from:
        type: string
        description: Only present if Session is disconnected by Alvaria&trade; Cloud.
        enum:
          - SYSTEM
      eventId:
        type: string
        description: 'Alvaria-generated unique identifier for the event'
        example: '22D45513-66F7-4A02-9998-EF8E72AB2363'
    required:
      - sessionId
      - event
      - status
      - eventId
  MessageCallback:
    type: object
    description: 'This event signals that a message has been sent from Alvaria&trade;.'
    properties:
      sessionId:
        type: string
        description: Alvaria-generated unique identifier for a server messaging session
        example: 38D1FBA0-2079-42FB-93C2-0DE301CF8FF5
      senderId:
        type: string
        description: 'Origin of message  (agent/system).'
        example: SYSTEM
      message:
        $ref: '#/definitions/Message'
      eventId:
        type: string
        description: 'Alvaria-generated unique identifier for the event'
        example: '22D45513-66F7-4A02-9998-EF8E72AB2363'
    required:
      - sessionId
      - event
      - senderId
      - message
      - eventId      
securityDefinitions:
  oauth:
    type: oauth2
    authorizationUrl: 'https://myaspect.{region}.id.aspect-cloud.net/tokenservice/oauth2/access_token?realm={orgId}'
    flow: implicit
    scopes:
      servermessagingapi: manage access to server messaging api