openapi: 3.0.3
info:
  description: |

    This API provides the IoT Accelerator SMS Messaging API. The SMS Messaging API allows a web application to send and receive SMS messages over HTTPS and simplifies the communication between the enterprise and the IoT Accelerator SMSC. The service supports the sending and receiving of both binary and text SMS messages.

    The IoT Accelerator SMS Messaging API is based on the following OneAPI SMS interface:
    - OMA REST NetAPIs v1

    # Scope
     This specification covers the following topics

    - An overview of all services offered by the SMS Messaging API interface
    - A detailed description of all the procedures and operations that a user of the interface can perform and all the possible results

    # Target Groups
     This specification is intended for enterprise users that want to know how to use the DCP SMS Messaging API interface.

    # Prerequisites
    It is assumed that the user is familiar with the following

    - Extensible Markup Language® (XML)
    - Java Script Object Notation (JSON)
    - Basic understanding of RESTful web services
    - Tools and programming languages for consuming RESTful web services

  version: v2
  title: SMS Messaging API
  x-audience: external-public
paths:
  "/outbound/{senderAddress}/requests":
    post:
      summary: Sends an SMS message to one or more devices
      tags:
        - sendSMS
      operationId: sendSMS
      parameters:
        - name: senderAddress
          description: "A string that represents the address of the enterprise that sends the SMS. For example tel:12345678"
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          description: "Should contain a base64 Basic auth string"
          in: header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OutboundSMSMessageRequestHolder"
            example:
              outboundSMSMessageRequest:
                address:
                  - 'tel:13500000991'
                  - 'tel:13500000992'
                senderAddress: 'tel:12345678'
                senderName: "Me"
                outboundSMSTextMessage:
                  message: Hello World

      responses:
        '201':
          description: successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutboundSMSMessageRequestHolder"
              example:
                outboundSMSMessageRequest:
                  address:
                    - 'tel:13500000991'
                    - 'tel:13500000992'
                  deliveryInfoList:
                    deliveryInfo:
                    - address: "tel:13500000991"
                      deliveryStatus: "DeliveredToTerminal"
                    - address: "tel:13500000992"
                      deliveryStatus: "DeliveredToNetwork" 
                    resourceURL: "https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1/outbound/tel:12345/requests/dcp1234567/deliveryInfos"
                  senderAddress: "tel:12345"
                  senderName: "Me"
                  outboundSMSTextMessage:
                    message: "Deep Purple"
                  resourceURL: "https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1/outbound/tel:12345/requests/dcp1234567/"
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
              example:
                requestError:
                  serviceException:
                    messageId: "SVC0004"
                    text: "No valid addresses provided inmessage part %1"
                    variables: "address, (each address must be prefixed with tel:)"
        '401':
          description: "Authentication Failure"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
        '403':
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
              example:
                requestError:
                  policyException:
                    messageId: "POL0010"
                    text: "User has not been provisioned for %1"
                    variables: "SMSMessaging" 
        '404':
          description: "No Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
        '503':
          description: "Service Unavailable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"

  "/outbound/{senderAddress}/requests/{requestId}/deliveryInfos":
    get:
      summary: Queries the delivery status of an SMS.
      tags:
        - querySMS
      operationId: querySMS
      parameters:
        - name: senderAddress
          description: "A string that represents the address of the enterprise that raises the request.For example tel:12345678"
          in: path
          required: true
          schema:
            type: string
        - name: requestId
          description: "A string that must be entered as returned in the related sendSMS successful response."
          in: path
          required: true
          schema:
            type: string
        - name: Authorization
          description: "Should contain a base64 Basic auth string"
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeliveryInfoList"
              example:
                deliveryInfo:
                - address: "tel:13500000991"
                  deliveryStatus: "DeliveredToTerminal"
                - address: "tel:13500000992"
                  deliveryStatus: "DeliveredToNetwork"
                resourceURL: "https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1/outbound/tel:12345/requests/dcp1234567/deliveryInfos"
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
              example:
                requestError:
                  serviceException:
                    messageId: "SVC0010"
                    text: "Requested information unavailable as the retention time interval has expired."
                    variables: ""
        '401':
          description: "Authentication Failure"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
        '403':
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
              example:
                requestError:
                  policyException:
                    messageId: "POL0010"
                    text: "User has not been provisioned for %1"
                    variables: "SMSMessaging"  
        '404':
          description: "No Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
        '503':
          description: "Service Unavailable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
  "/inbound/registrations/{registrationID}/messages":
    get:
      summary: Retrieves an SMS sent to a web application.
      tags:
        - retrieveSMS
      operationId: retrieveSMS
      parameters:
        - name: registrationID
          description: "Identity provided by DCP that grants with unique access to the received SMS messages."
          in: path
          required: true
          schema:
            type: string
        - name: maxBatchSize
          description: "The maximum number of messages to retrieve in the request."
          in: query
          required: false
          schema:
            type: string
            default: "2147483647"
        - name: Authorization
          description: "Should contain a base64 Basic auth string"
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InboundSMSMessageRequest"
              example:
                inboundSMSMessageList:
                  inboundSMSMessage:
                    - dateTime: "2009-11-19T12:00:00"
                      destinationAddress: "3456"
                      messageId: "msg1"
                      message: "Come on Barca!"
                      resourceURL: "http://example.com/smsmessaging/v1/inbound/registrations/3456/messages/msg1"
                      senderAddress: "+447825123456"
                    - dateTime: "2009-11-19T12:00:00"
                      destinationAddress: "3456"
                      messageId: "msg2"
                      message: "aDffiuek5fjj="
                      resourceURL: "http://example.com/smsmessaging/v1/inbound/registrations/3456/messages/msg2"
                      senderAddress: "+447825789123"
                      messageType: "binary"
                  numberOfMessagesInThisBatch: "2"
                  resourceURL: "http://example.com/smsmessaging/v1/inbound/registrations/3456/messages"
                  totalNumberOfPendingMessages: "20"
        '400':
          description: "Bad Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
              example:
                requestError:
                  serviceException:
                    messageId: "SVC0003"
                    text: "Invalid input value for message part <text>, valid values are %2"
                    variables: "maxBatchSize, (positive integer)"
        '401':
          description: "Authentication Failure"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
        '403':
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
              example:
                requestError:
                  policyException:
                    messageId: "POL0010"
                    text: "User has not been provisioned for %1"
                    variables: "SMSMessaging" 
        '404':
          description: "No Found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
        '503':
          description: "Service Unavailable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RequestError"
servers:
  - url: https://sms.iot-api.aeris.com/dcpapi/smsmessaging/v1
    description: SMS API server
security: 
  -  BasicAuth: []
components:
  schemas:
    RequestError:
      type: object
      properties: 
        requestError:
          type: object
          properties:
            serviceException:
              type: object
              properties:
                messageId:
                  type: string
                  description: "violation identifier, ref. User Guide"
                text:
                  type: string
                  description: "describes the violation"
                variables:
                  type: string
                  description: "points to the variable(s) in violation"
            policyException:
              type: object
              properties:
                messageId:
                  type: string
                  description: "violation identifier, ref. User Guide"
                text:
                  type: string
                  description: "describes the violation"
                variables:
                  type: string
                  description: "points to the variable(s) in violation"
    InboundSMSMessageRequest:
      type: object
      properties:
        inboundSMSMessageList:
          type: object
          properties:
            inboundSMSMessage:
              type: array
              items:
                $ref: "#/components/schemas/InboundSMSMessage"
            numberOfMessagesInThisBatch:
              type: string
              description: "The number of SMS messages retrieved in the successful response."
            resourceURL:
              type: string
              description: "Link to the successful response."
            totalNumberOfPendingMessages:
              type: string
              description: "Total number of SMS messages that are awaiting for retrieval from storage."
    InboundSMSMessage:
      type: object
      properties:
        dateTime:
          type: string
          description: "Date and time when the successful response is created."
        destinationAddress:
          type: string
          description: "The number associated with your service. It corresponds to the registrationID."
        messageId:
          type: string
          description: "Message identifier generated automatically by the server."
        message:
          type: string
          description: "For Text SMS: a string with maximum 160 characters. For Binary SMS: a Base64 (RFC4648) encoded string with up to 140 bytes of binary data. For example: AQIDBAUGBwgJCg=="
        resourceURL:
          type: string
          description: "Link to the SMS message."
        senderAddress:
          type: string
          description: "The name of the enterprise that sent the SMS."
        messageType:
          type: string
          description: "The type of SMS message. For Binary SMS: use 'binary'. When field is not present, the message is a text message"
    DeliveryInfo:
      type: object
      required:
        - address
        - deliveryStatus
      properties:
        address:
          type: string
          description: "The recipients MSISDN including the tel: protocol identifier. For example: tel:16309700001"
        deliveryStatus:
          type: string
          description: "Delivery status for the recipient identified by address. "
          enum:
            - DeliveredToTerminal
            - DeliveryUncertain
            - DeliveryImpossible
            - MessageWaiting
            - DeliveredToNetwork
    DeliveryInfoList:
      type: object
      required:
        - deliveryInfo
        - resourceURL
      properties:
        deliveryInfo:
          type: array
          description: "List of deliveryInfos"
          items:
            $ref: "#/components/schemas/DeliveryInfo"
        resourceURL:
          type: string
          description: "Link to the successful response."
    DeliveryInfoObject:
      type: object
      properties: 
        deliveryInfoList:
          items: 
            $ref: "#/components/schemas/DeliveryInfoList"
    OutboundSMSBinaryMessage:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: "Base64 coded string"
    OutboundSMSMessageRequest:
      type: object
      required:
        - address
        - senderAddress
      properties:
        address:
          type: array
          description: "The recipients MSISDN including the ‘tel:' protocol identifier and the country code. For example: tel:16309700001"
          items:
            type: string
        deliveryInfoList:
          $ref: "#/components/schemas/DeliveryInfoList"
        senderAddress:
          type: string
          description: "A string that represents the address of the enterprise that sends the SMS. For example: tel:12345678"
        outboundSMSTextMessage:
          $ref: "#/components/schemas/OutboundSMSTextMessage"
        outboundSMSBinaryMessage:
          $ref: "#/components/schemas/OutboundSMSBinaryMessage"
        senderName:
          type: string
          description: "The name of the sender"
        validityPeriod:
          type: integer
          format: int32
          description: "The SMSC expiration time, after which the message is discarded if still not delivered to the destination."
        resourceURL:
          type: string
        subAddress:
          type: string
          description: "A string that represents the sub-address of the device to send the message to. Supports only SIM card. For example: subAddress:sim"
    OutboundSMSMessageRequestHolder:
      type: object
      required:
        - outboundSMSMessageRequest
      properties:
        outboundSMSMessageRequest:
          $ref: "#/components/schemas/OutboundSMSMessageRequest"
    OutboundSMSTextMessage:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: "Regular text string of up to 160 characters."
  securitySchemes:   
    BasicAuth:
      type: http
      scheme: basic
