openapi: 3.0.3
info:
  description: |
    Unified Messaging Service provides APIs to send notifications and messages
    like sending SMS, Email and also get status updates.  

    # Introduction

    The API is used by different applications, services to send notifications
    
    # API Functionality

    This API allows to clients to send SMS and Email.

    # The API provides several endpoints/operations:
     - An endpoint to send a single SMS
     - An endpoint to send a multiple SMS
     - An endpoint to breadcast a message
     - A set of endpoints to retrieve information about these transactions.
   
  version: 0.9.0
  title: Omnichannel Notification Service
servers:
  - url: https://apigw.omantel.om
    variables:
      apiRoot:
        default: https://apigw.omantel.om
        description: API root
      basePath:
        default: /v1/unified-messaging
        description: Base path for the unified messaging service
paths:
  /v1/unified-messaging/send-single:
    post:
      security:
        - oAuth2ClientCredentials: []
      tags:
        - SMS Delivery
      summary: Send Single SMS 
      operationId: sendSingleSms
      description: This operation is used to send single SMS to Mobile customers.
      requestBody:
        description: Send Single SMS
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSendSingleSms"
            examples:
              SendEnglishMessage:
                summary: Send English SMS
                value:
                    clientCorrelatorId: '1234567890'
                    sender: 'Omantel'
                    recipient: '968925069XX'
                    smsText: 'Welcome to SMS Service!'
              SendArabicMessage:
                summary: Send Arabic SMS
                value:
                    clientCorrelatorId: '1234567890'
                    sender: 'Omantel'
                    recipient: '968925069XX'
                    smsText: 'مرحبا بكم في خدمة الرسائل القصيرة!'
              EnableExpiryDate:
                summary: Send English SMS with Expiry Date
                value:
                    clientCorrelatorId: '1234567890'
                    sender: "Omantel"
                    recipient: "96892xxxxxx"
                    smsText: "Welcome to SMS Service!"
                    expiryTime: "2023-11-12T07:24:43.997Z"
              EnableDeliveryReportRequest:
                summary: Enable delivery report for the SMS
                value:
                    clientCorrelatorId: '1234567890'
                    sender: "Omantel"
                    recipient: "96892xxxxxx"
                    smsText: "Welcome to SMS Service!"
                    enableDeliveryReport: true
              SendFlashMessage:
                summary: Send Flash SMS
                value:
                    clientCorrelatorId: '1234567890'
                    sender: "Omantel"
                    recipient: "96892xxxxxx"
                    smsText: "Welcome to SMS Service!"
                    flashMessage: true
              SendMessageWithPriority:
                summary: Send SMS with priority
                value:
                    clientCorrelatorId: '1234567890'
                    sender: "Omantel"
                    recipient: "96892xxxxxx"
                    smsText: "Welcome to SMS Service!"
                    priority: 2
              EnableExpiryDateAndDeliveryReport:
                summary: Enable Expiry Date and Delivery Report
                value:
                    clientCorrelatorId: '1234567890'
                    sender: "Omantel"
                    recipient: "96892xxxxxx"
                    smsText: "Welcome to SMS Service!"
                    expiryTime: "2023-11-12T07:24:43.997Z"
                    enableDeliveryReport: false
      responses:
        201:
          description: <b>Created</b>
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedSendSingleSms"
        400:
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Schema validation failed
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Schema validation failed at  ..."
                InvalidInput:
                  summary: Invalid Input in the request
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "Invalid value for input field: fieldName"
                DuplicateClientCorrelator:
                  summary: clientCorrelatorId already exist
                  value:
                    code: INVALID_ARGUMENT
                    status: 400
                    message: "clientCorrelatorId already exist on server"
        401:
          $ref: "#/components/responses/Generic401"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic403:
                  summary: Forbidden
                  value:
                    status: 403
                    code: PERMISSION_DENIED
                    message: "Operation not allowed: ..."
        409:
          $ref: "#/components/responses/Generic409"
        500:
          $ref: "#/components/responses/Generic500"
        503:
          $ref: "#/components/responses/Generic503"
        504:
          $ref: "#/components/responses/Generic504"
components:
  schemas:
    Sms:
      type: object
      required:
        - sender
        - recipient
        - smsText
      properties:
        messageId:
          type: string
          minLength: 1
          maxLength: 20
          description: |
            A unique identifier for the message generated by Omantel. 
            API consumer should not specify it. If consumer has 
            specified this value, then it will be ignored and Omantel
            system will generate an unique ID. 
          example: "12345"
        sender:
          type: string
          minLength: 1
          maxLength: 11
          description: SMS short code or SMS Sender. It will be displayed as SMS Sender.
          example: "Omantel"
        recipient:
          type: string
          minLength: 3
          maxLength: 11
          description: |
            Phone numbers of SMS recipients. 
            Phone number should be in E.164 format (starting with country code). 
          example: "96892xxxxxx"
        smsText:
          type: string
          minLength: 1
          maxLength: 1000
          description: |
            SMS message text. Maximum 1000 characters.  
          example: "Welcome to SMS Service!"
        expiryTime:
          type: string
          format: date-time
          description: |
            Date time, in ISO-8601 extended local date format.
            Specifies the time after which the SMS should no longer be 
            attempted to be delivered. This could be in a specific date-time format.
            By default, message will expire after 24 hrs.
        enableDeliveryReport:
          type: boolean
          default: false
          description: |
            Whether delivery report of this SMS is required or not. 
            If its value is `true`, service will initiate delivery report. 
            Delivery report can be received as even notification on callback URL.
            Currently, this feature is not implemented.
        flashMessage:
          type: boolean
          default: false
          description: |
            Whether SMS should be sent as Flash SMS. 
            Flash SMS displayed on screen directly.
            Please note that this message might go unnoticed if multiple
            messages are sent together as new SMS might hide previous SMS. 
            Moreover, long messages will not be displayed properly. 
        priority:
          type: number
          enum: [ '1', '2', '3' , '4' , '5' , '6' , '7' , '8' , '9' , '10']
          default: '10'
          description: |
            Priority of SMS delivery. 1 represents highest priority. 
            However, it should be used wisely. In some cases, service might ignore it.   
      # discriminator:
      #   propertyName: sender        


    OtlResponseCommon:
      type: object
      required:
        - otlTransactionId
        - transactionOperationStatus
      properties:
        otlTransactionId:
          type: string
          description: |
            Unique Identifier of the message created in Omantel System. It
            can be used to query status of the transaction 
        transactionOperationStatus:
          type: string
          enum: ["accepted", "sent", "expired", "failed", "error"]
          description:
            Specifies the transaction processing status.
        smsCount:
          type: integer
          description: |
            How many SMS message were found in the request. 
        smsParts:
          type: integer
          description: |
            How many SMS message parts will be sent out. Long SMS messages are sent in
            parts. Each part may decrease 1 count of the balance of total credits. 
    CreateSendSingleSms:
      type: object
      description: Allows sending single SMS
      allOf:
        - type: object
          required:
            - clientCorrelatorId
          properties:
            clientCorrelatorId:
              type: string
              minLength: 1
              maxLength: 20
              description: |
                A unique identifier on the client side to uniqly identify this request.
                If duplicate request is received, service will reject the request 
              example: "1234567890"
            webhook:
              $ref: "#/components/schemas/Webhook"             
        - $ref: '#/components/schemas/Sms'
    CreatedSendSingleSms:
      type: object
      description: Response for sending single SMS request
      allOf:
        - $ref: '#/components/schemas/OtlResponseCommon'
        # - $ref: '#/components/schemas/CreateSendSingleSms'
    Webhook:
      type: object
      required:
        - notificationUrl
      properties:
        notificationUrl:
          type: string
          description: Callback URL to allow asynchronous delivery of SmsInfo related events
        notificationAuthToken:
          type: string
          example: "c8974e592c2fa383d4a3960714"
          description: Authentification token for callback endpoint
    ErrorInfo:
      type: object
      required:
        - code
        - message
        - status
      properties:
        code:
          type: string
          description: Code given to this error
        status:
          type: string
          description: HTTP response status code
        message:
          type: string
          description: Detailed error description
  responses:
    Generic400:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: INVALID_ARGUMENT
            status: 400
            message: "Schema validation failed at  ..."
    Generic401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: UNAUTHORIZED
            status: 401
            message: "Authorization failed: ..."
    Generic403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: FORBIDDEN
            status: 403
            message: "Operation not allowed: ..."
    Generic404:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: NOT_FOUND
            status: 404
            message: "The specified resource is not found"
    Generic409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 409
            code: ALREADY_EXISTS
            message: "A specified resource duplicate entry found"
    Generic500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVER_ERROR
            status: 500
            message: "Server Error"
    Generic503:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: SERVICE_UNAVAILABLE
            status: 503
            message: "Service unavailable"
    Generic504:
      description: Request timeout exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            code: REQUEST_TIMEOUT_EXCEEDED
            status: 504
            message: "Request timeout exceeded"
  headers:
    Content-Last-Key:
      description: Indicates the index of the last result provided in the response
      schema:
        type: integer
    X-Total-Count:
      description: Total number of items matching criteria
      schema:
        type: integer
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://apigw.omantel.om/oauth2/accesstoken
          scopes: {}