openapi: 3.0.0
info:
  title: VDX SMS Gateway service
  description: API description for VDX SMS Gateway.
  version: 2.0.0-
  contact:
    email: development@kvalitetitsit.dk
tags:
  - name: Callback service
    description: Callback service used by SMS gateway
  - name: Sms V2
    description: SMS related operations
servers: [{url: 'https://videoapi.vconf-stage.dk', description: VDX SMS API}]
paths:
  /sms/v1/callback:
    get:
      tags:
        - Callback service
      summary: Callback service used by SMS gateway.
      description: Callback service used by SMS gateway provider.
      parameters:
        - name: sessionid
          in: query
          description: The session id provided in the request to the gateway.
          required: true
          schema:
            type: string
          example: 'abcdefgh'
        - name: rqStatus
          in: query
          description: The status code
          required: true
          schema:
            type: integer
          example: 4
      responses:
        '200':
          description: Ok
  /sms/v2/meeting/{uuid}:
    get:
      security:
        - keycloakOIDC: []
      tags:
        - Sms V2
      summary: Get status for sms deliveries for a meeting
      description: Get status for SMS deliveries for provided meeting. Can be used to get information about delivery status of the SMS.
      parameters:
        - $ref: '#/components/parameters/uuid'
      responses:
        200:
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/smsStatus'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    post:
      security:
        - keycloakOIDC: []
      tags:
        - Sms V2
      summary: Send SMS
      description: Send SMS
      parameters:
        - $ref: '#/components/parameters/uuid'
      requestBody:
        description: SMS message and phone number
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/smsRequest'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/smsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  securitySchemes:
    userContext:
      type: apiKey
      in: header
      name: X-SESSIONDATA
    keycloakOIDC:
      type: oauth2
      description: >-
        OIDC security implemented by Keycloak. The token should contain a user role claim with at least one of the following values: <br> * meeting-admin <br> * meeting-user
      flows:
        authorizationCode:
          authorizationUrl: https://login.vconf-stage.dk/auth/realms/broker/protocol/openid-connect/auth
          tokenUrl: https://login.vconf-stage.dk/auth/realms/broker/protocol/openid-connect/token
          scopes: {}
        clientCredentials:
          tokenUrl: https://login.vconf-stage.dk/auth/realms/broker/protocol/openid-connect/token
          scopes: {}
  parameters:
    uuid:
      name: uuid
      in: path
      description: the uuid for the requested information
      required: true
      schema:
        type: string
        format: uuid
      example: 46b46a1e-a4d3-4387-87ee-a67dcaa222cb
  responses:
    '400':
      description: >-
        Bad Request. This could be because: <br> * One of the required parameters/properties are missing or is empty <br> * Length of input is exceeding maximum length <br> (See a possible detailed error message in the response.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '401':
      description: >-
        Unauthorized. This could be because: <br> * The calling system has not been properly authenticated <br> * The user is not correct configured. It could be missing email or organisation <br> * The provided token is invalid, e.g. is expired or wrong issuer <br> (See a possible detailed error message in the response.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '403':
      description: >-
        Forbidden. This could be because: <br> * The requested information does not belong the organisation of the user <br>  * The calling user does not have the required roles <br> (See a possible detailed error message in the response.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
    '404':
      description: >-
        Not found. This could be because: <br> * The meeting for the SMS status request does not exist <br>  * There are no SMS statuses belonging to the request meeting <br> * The organisation requested has been deleted or has never existed <br> (See a possible detailed error message in the response.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/detailedError'
  schemas:
    smsResponse:
      type: object
      required:
        - reference
        - status
      properties:
        reference:
          description: Unique reference
          type: string
          format: uuid
          example: "5d950cbf-5a59-40f4-80dd-f7a25f3ac8bb"
        status:
          $ref: '#/components/schemas/status'
    smsRequest:
      type: object
      required:
        - message
        - to
      properties:
        message:
          description: Message to send. It must contain a placeholder for the meeting link. The placeholder is called %meeting_url%. See example for an example.
          type: string
          example: "Access your meeting at %meeting_url%"
          maxLength: 480
        to:
          description: Phone number to send message to.
          type: string
          maxLength: 20
          example: "+4512345678"
    smsStatus:
      type: object
      required:
        - reference
        - status
        - to
        - sendDateTime
      properties:
        reference:
          description: Unique reference
          type: string
          format: uuid
          example: "5d950cbf-5a59-40f4-80dd-f7a25f3ac8bb"
        status:
          $ref: '#/components/schemas/status'
        to:
          description: Phone number to send message to.
          type: string
          maxLength: 20
          example: "+4512345678"
        sendDateTime:
          description: Date/time when message was send.
          type: string
          format: date-time
          example: "2017-07-21T17:32:28Z"
    status:
      example: Registered
      description: "Status for message. Valid values: Registered, Failed, InProgress and Delivered"
      type: string
      enum:
        - Registered
        - Delivered
        - InProgress
        - Failed
        - Unknown
    detailedError:
      allOf:
        - $ref: '#/components/schemas/basicError'
        - type: object
          required:
            - detailed_error
            - detailed_error_code
          properties:
            detailed_error:
              description: Detailed error text. This could be a text describing an validation error.
              type: string
            detailed_error_code:
              description: >-
                Detailed error code. This could be a code describing an validation error. * 10: Input validation error * 20: Basic error.
              type: string
              enum:
                - 10
                - 20
    basicError:
      type: object
      required:
        - timestamp
        - status
        - error
        - path
      properties:
        error:
          description: Error message.
          type: string
        path:
          description: Path
          type: string
        status:
          description: HTTP status code
          type: integer
        timestamp:
          description: Time of error
          type: string
          format: date-time