openapi: 3.0.0 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. # Further info and support (FAQs will be added in a later version of the documentation) version: 0.9.0 title: Omnichannel Notification Service termsOfService: http://swagger.io/terms/ contact: email: MiddlewareESB@omantel.om license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: Product documentation at Omantel.om url: https://api.omantel.om/docs/ servers: - url: https://apigwsb.omantel.om variables: apiRoot: default: https://apigwsb.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. parameters: - name: mock-key in: query description: The mock-key parameter is used to simulate different response scenarios. Choose one of the available keys. **NOTE:- Mock keys are only applicable for sandbox environment and only give you mock responses.** required: true schema: type: string enum: - send-notification-post-201 - send-notification-post-400 - send-notification-post-401 - send-notification-post-403 - send-notification-post-409 - send-notification-post-500 - send-notification-post-503 - send-notification-post-504 requestBody: description: Send Single SMS required: true content: application/json: schema: $ref: "#/components/schemas/CreateSendSingleSms" examples: SendEnglishMessage: summary: Send English SMS value: clientCorrelatorId: 'SN-Test-001' sender: 'Omantel' recipient: '96892500000' smsText: 'Welcome to SMS Service!' SendArabicMessage: summary: Send Arabic SMS value: clientCorrelatorId: 'SN-Test-001' sender: 'Omantel' recipient: '96892500000' smsText: 'مرحبا بكم في خدمة الرسائل القصيرة!' EnableExpiryDate: summary: Send English SMS with Expiry Date value: clientCorrelatorId: 'SN-Test-001' sender: "Omantel" recipient: "96892500000" smsText: "Welcome to SMS Service!" expiryTime: "2023-11-12T07:24:43.997Z" EnableDeliveryReportRequest: summary: Enable delivery report for the SMS value: clientCorrelatorId: 'SN-Test-001' sender: "Omantel" recipient: "96892500000" smsText: "Welcome to SMS Service!" enableDeliveryReport: true SendFlashMessage: summary: Send Flash SMS value: clientCorrelatorId: 'SN-Test-001' sender: "Omantel" recipient: "96892500000" smsText: "Welcome to SMS Service!" flashMessage: true SendMessageWithPriority: summary: Send SMS with priority value: clientCorrelatorId: 'SN-Test-001' sender: "Omantel" recipient: "96892500000" smsText: "Welcome to SMS Service!" priority: 2 EnableExpiryDateAndDeliveryReport: summary: Enable Expiry Date and Delivery Report value: clientCorrelatorId: 'SN-Test-001' sender: "Omantel" recipient: "96892500000" smsText: "Welcome to SMS Service!" expiryTime: "2023-11-12T07:24:43.997Z" enableDeliveryReport: false responses: 201: description: Created 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" /v1/unified-messaging/send-sms-inquiry: get: security: - oAuth2ClientCredentials: [] tags: - SMS Delivery Requests Inquiry summary: Get a list of SMS transactions operationId: smsInquiry description: Retrieve a list of SMS sent based on some filtering criteria. parameters: - name: mock-key in: query description: The mock-key parameter is used to simulate different response scenarios. Choose one of the available keys. **NOTE:- Mock keys are only applicable for sandbox environment and only give you mock responses.** required: true schema: type: string enum: - list-sms-transacion-get-200 - list-sms-transacion-get-400 - list-sms-transacion-get-401 - list-sms-transacion-get-403 - list-sms-transacion-get-500 - list-sms-transacion-get-503 - list-sms-transacion-get-504 - $ref: "#/components/parameters/fromDate" - $ref: "#/components/parameters/toDate" - $ref: "#/components/parameters/Page" - $ref: "#/components/parameters/PerPage" - $ref: "#/components/parameters/Seek" responses: 200: description: OK headers: Content-Last-Key: $ref: "#/components/headers/Content-Last-Key" X-Total-Count: $ref: "#/components/headers/X-Total-Count" content: application/json: schema: $ref: "#/components/schemas/SendSmsInquiryReplyArray" 400: description: Invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: OutOfRange: summary: Request out of range value: status: 400 code: OUT_OF_RANGE message: "Client specified an invalid range" 401: $ref: "#/components/responses/Generic401" 403: $ref: "#/components/responses/Generic403" 500: $ref: "#/components/responses/Generic500" 503: $ref: "#/components/responses/Generic503" 504: $ref: "#/components/responses/Generic504" /v1/unified-messaging/send-sms-inquiry/{clientCorrelatorId}: get: security: - oAuth2ClientCredentials: [] tags: - SMS Delivery Requests Inquiry summary: Retrieve SMS transaction detail for the specified clientCorrelatorId operationId: smsInquiryByClientCorrelatorId description: Retrieve SMS transaction detail for the specified `clientCorrelatorId` parameters: - name: mock-key in: query description: The mock-key parameter is used to simulate different response scenarios. Choose one of the available keys. **NOTE:- Mock keys are only applicable for sandbox environment and only give you mock responses.** required: true schema: type: string enum: - retrieve-sms-transaction-detail-200 - retrieve-sms-transaction-detail-400 - retrieve-sms-transaction-detail-401 - retrieve-sms-transaction-detail-403 - retrieve-sms-transaction-detail-500 - retrieve-sms-transaction-detail-503 - retrieve-sms-transaction-detail-504 - name: clientCorrelatorId in: path description: clientCorrelatorId identifier that was specified in the request by the client required: true example: "SN-TEST-001" schema: type: string responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/SendSmsInquiryReply" 400: description: Invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" examples: OutOfRange: summary: Request out of range value: status: 400 code: OUT_OF_RANGE message: "Client specified an invalid range" 401: $ref: "#/components/responses/Generic401" 403: $ref: "#/components/responses/Generic403" 500: $ref: "#/components/responses/Generic500" 503: $ref: "#/components/responses/Generic503" 504: $ref: "#/components/responses/Generic504" components: schemas: SmsMessageBody: type: object required: - smsText Sms: type: object required: - sender - recipient - smsMessageBody properties: messageId: type: string minLength: 1 maxLength: 20 description: A unique identifier for the message, useful for tracking and in delivery reports. example: "3k3a5yOysEf0004513001" 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: "96892500000" 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'] description: | Priority of SMS delivery. 1 represents highest priority. However, it should be used wisely. In some cases, service might ignore it. SmsList: type: array items: $ref: "#/components/schemas/Sms" minItems: 1 maxItems: 100 description: List containing SMS to be sent OtlResponseCommon: type: object required: - otlTransactionId - transactionOperationStatus properties: otlTransactionId: type: string example: "3k3a5yOysEf0004513" 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 example: 1 description: | How many SMS message were found in the request. smsParts: type: integer example: 1 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: "SN-Test-001" 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' CreateSendMultipleSms: type: object description: Allows sending multiple SMS in one request allOf: - type: object required: - clientCorrelatorId - smsList properties: clientCorrelatorId: type: string minLength: 1 maxLength: 20 description: | A unique identifier on the client side to uniquely identify this request. If a duplicate request is received, the service will reject the request. example: "SN-Test-001" smsList: type: array items: $ref: "#/components/schemas/Sms" minItems: 1 maxItems: 100 description: List containing SMS messages to be sent. webhook: $ref: "#/components/schemas/Webhook" CreatedSendMultipleSms: type: object description: Response for sending multiple SMS request allOf: - $ref: '#/components/schemas/OtlResponseCommon' # - $ref: '#/components/schemas/CreateSendMultipleSms' CreateBroadcastSms: type: object required: - clientCorrelatorId - smsMessageBody - recipients properties: clientCorrelatorId: type: string minLength: 1 maxLength: 20 description: | A unique identifier on the client side to uniqly identify this request. Duplicate requests will be rejected. example: "SN-Test-001" smsMessageBody: $ref: "#/components/schemas/SmsMessageBody" recipients: type: array items: type: string minItems: 1 maxItems: 100 description: "An array of recipient phone numbers. Must contain at least 1 and no more than 100 elements." webhook: $ref: "#/components/schemas/Webhook" CreatedBroadcastSms: type: object description: Response for sending breadcasting SMS request allOf: - $ref: '#/components/schemas/OtlResponseCommon' # - $ref: '#/components/schemas/CreateSendMultipleSms' SmsDetail: type: object description: Represents one SMS with status of prpocessing allOf: - $ref: '#/components/schemas/Sms' - type: object required: - transactionStatus - smsParts properties: 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. transactionStatus: type: string description: The status of the SMS transaction (e.g., 'pending', 'sent', 'failed'). sentTime: type: string format: date-time description: The timestamp when the SMS was sent. SmsDetailList: type: array items: $ref: "#/components/schemas/SmsDetail" minItems: 1 maxItems: 100 description: List containing SMS details SendSmsInquiryReply: type: object description: Response for Send SMS Inquiry required: - clientCorrelatorId - otlTransactionId - transactionOperationStatus - smsCount - smsParts - smsList - requestTime properties: clientCorrelatorId: type: string minLength: 1 maxLength: 20 description: | A unique identifier on the client side to uniqly identify this request. example: "SN-Test-001" otlTransactionId: type: string example: "3k3a5yOysEf0004513" 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. smsList: $ref: '#/components/schemas/SmsDetailList' requestTime: type: string format: date-time description: | Date time, in ISO-8601 extended local date format. Specifies the time when request was received SendSmsInquiryReplyArray: type: array description: Response for Send SMS Inquiry items: $ref: "#/components/schemas/SendSmsInquiryReply" SmsInfo: type: object required: - sms - SmsInfoId properties: sms: $ref: "#/components/schemas/Sms" SmsInfoCreationDate: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the SmsInfo is created in server database. This is a technical information. Time-offset from UTC may be used to match local OB time. SmsInfoDate: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the SmsInfo is effectively performed. This is a business information. Time-offset from UTC may be used to match local OB time. webhook: $ref: "#/components/schemas/Webhook" SmsTransaction: type: object required: - clientCorrelatorId - smsList properties: clientCorrelatorId: type: string minLength: 1 maxLength: 20 description: A unique identifier on the client side to uniqly identify this request. example: "SN-Test-001" smsList: $ref: "#/components/schemas/SmsTransactionDetail" webhook: $ref: "#/components/schemas/Webhook" otlTransactionId: type: string example: "3k3a5yOysEf0004513" 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. requestTime: type: string format: date-time description: | Date time, in ISO-8601 extended local date format. Specifies the time when request was received SmsTransactionDetail: type: object allOf: - $ref: '#/components/schemas/Sms' - type: object properties: transactionStatus: type: string description: The status of the SMS transaction (e.g., 'pending', 'sent', 'failed'). sentTime: type: string format: date-time description: The timestamp when the SMS was sent. deliveryStatus: type: string description: The delivery status of the SMS (e.g., 'delivered', 'not delivered', 'pending'). deliveryTime: type: string format: date-time description: The timestamp when the SMS was deleivered. Will be available only if delivery report was active and SMS has returned delivery report errorDetail: type: string description: | Error details if any error occured like MSISDN was not correct or SMS delivery to the specified number is not allowed (opt-out). This error scope is limited to this SMS only. SmsTransactionList: type: array items: $ref: "#/components/schemas/SmsTransaction" minItems: 1 maxItems: 100 description: List containing SMS transactions BroadcastTransactionDetail: type: object allOf: - $ref: '#/components/schemas/CreateBroadcastSms' - type: object properties: otlTransactionId: type: string example: "3k3a5yOysEf0004513" 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. requestTime: type: string format: date-time description: | Date time, in ISO-8601 extended local date format. Specifies the time when request was received errorDetail: type: string description: | Error details if any error occured like MSISDN was not correct or SMS delivery to the specified number is not allowed (opt-out). This error scope is limited to this SMS only. BroadcastTransactionList: type: array items: $ref: "#/components/schemas/SmsTransaction" minItems: 1 maxItems: 100 description: List containing SMS transactions 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 EventNotification: type: object description: Generic data type for event notification structure required: - event properties: eventSubscriptionid: type: string description: subscription identifier event: $ref: "#/components/schemas/Event" Event: type: object description: Generic data type for event structure required: - eventType - eventTime - eventDetail properties: eventid: type: string format: uuid description: Identifier of the event from the server where the event was reported eventType: type: string description: | Type of event. Different types considered so far: - `SmsInfo_COMPLETED`: Notification indication about SmsInfo completion. - `SmsInfo_FAILED`: Notification about SmsInfo failure. eventTime: type: string format: date-time description: Date time, in ISO-8601 extended local date format, when the event occurred. Time-offset from UTC may be used to match local OB time. eventDetail: $ref: "#/components/schemas/EventDetail" EventDetail: type: object description: Data type to provide event detail information properties: otlTransactionId: type: string example: "3k3a5yOysEf0004513" description: Unique Identifier which was generated by Omantel clientCorrelatorId: type: string description: Client generated Unique Identifier of the SmsInfo status: type: string enum: - succeeded - failed - expired description: | Status of the procedure, according to `eventType` param. Possible status are: * `succeeded`: procedure was accomplished * `failed`: procedure failed. * `expired`: delivery expired. description: type: string description: Description of the notification, both used when process was `succeeded` or `failed` indicating in the latter case human understable reason about why process failed. SmsInfoDate: type: string description: Date when the SmsInfo is effectively performed, both in 1-step and 2-step scenarios. This is a business information. format: date-time required: - otlTransactionId - clientCorrelatorId - status - 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" parameters: phoneNumber: name: phoneNumber in: query description: Phone number of the customer. It must be a valid mobile number of the customer example: "92xxxxxx" schema: type: string fixedlineNumber: name: fixedlineNumber in: query description: Fixed line number of the customer example: "IA123456" schema: type: string internetAccount: name: internetAccount in: query description: Internet Account of the customer example: "24xxxxxx" schema: type: string customerAccountNumber: name: customerAccountNumber in: query description: Account number of the customer example: "12345678" schema: type: string clientCorrelatorId: name: clientCorrelatorId in: query schema: type: string description: | Client call can specify it to find individual transaction by its own unque ID. Service will return matching record only. If `clientCorrelatorId` is specified in the request, then service will consider only `clientCorrelatorId` and return matching transaction only, and will ignore all other parameters. fromDate: name: fromDate in: query description: Results should be taken from this transaction date example: "2023-01-15" schema: type: string format: date toDate: name: toDate in: query description: Results should be taken up-to this transaction date example: "2023-01-31" schema: type: string format: date Page: name: page in: query description: Requested index to indicate the start of the resources to be provided in the response schema: type: integer PerPage: name: perPage in: query description: Requested number of resources to be provided in response schema: type: integer Seek: name: seek in: query description: Index of last result read to create the next/previous number of results. This query parameter is used for pagination in systems with more than 1000 records. `seek` parameter offers finer control than `page` and could be used one or another as an alternative. If both are used in combination (not recommended) `seek` would mark the index starting from the page number specified by `page` and `perPage` [index = (page * perPage) + seek]. schema: type: integer 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://apigwsb.omantel.om/oauth2/accesstoken scopes: {}