openapi: 3.0.0
info:
  title: AMEEX SMS API
  description: API to submit SMS and query status
  version: 1.0.0
servers:
  - url: 'https://a2p.ameex-mobile.com/api'
    description: AMEEX A2P SMS API
  - url: 'https://virtserver.swaggerhub.com/v897/sms/1.0.0'
    description: SwaggerHub API Auto Mocking
security:
  - BasicAuth: []
paths:
  /sms:
    post:
      description: submit a message
      operationId: submit-message
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessage'
        required: true
      responses:
        '200':
          description: Successfully submitted a message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedMessage'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_400'
      callbacks:
        delivery-receipt:
          callbackUrl(to be provided by client):
            post:
              summary: Delivery Receipt
              description: >-
                you will need to provide us webhook(callback ulr)to receive
                delivery status
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/DeliveryReceipt'
                required: true
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback
  '/sms/{msgid}':
    get:
      description: query delivery status of a message
      operationId: query-delivery-status
      parameters:
        - name: msgid
          in: path
          description: >-
            the unique ID of a message, which is returned by server after
            submitting a message
          required: true
          style: simple
          explode: false
          schema:
            type: string
          example: HTTP-5C5CEFB6-8580
      responses:
        '200':
          description: Successfully queried a message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryReceipt'
components:
  schemas:
    NewMessage:
      required:
        - content
        - from
        - to
      type: object
      properties:
        from:
          type: string
          description: senderID of a message
          example: ABC
        to:
          type: string
          description: 'receipient of a message, in E.164 format'
          example: '96650403020'
        content:
          type: string
          description: The body of the message being sent. It can include any unicode defined characters in UTF-8 format. Concatenated message is supported
          example: Hello world
        base64url:
          type: integer
          description: set to 1 if "content" is base64url encoded. This is recommended to avoid encoding issue for non-latin characters
          format: int32
          default: 0
        udh:
          type: string
          description: Advanced usage your custom Hex encoded User Data Header
          example: 0003F90201
    CreatedMessage:
      type: object
      properties:
        message-count:
          type: integer
          description: the amount of messages submitted
          format: int32
          example: 1
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessagePart'
        errorcode:
          type: integer
          description: >-
            response of the submit-message request, 0 means successful, non 0
            means failure, refer to errorcode list for reasons
          format: int32
    DeliveryReceipt:
      type: object
      properties:
        msisdn:
          type: string
          description: The receipent of the message was sent to (E.164 format)
          example: '96650403020'
        to:
          type: string
          description: The SenderID you set in `from` in your request.
          example: ABC
        msgid:
          type: string
          description: The AMEEX ID for this message.
          example: HTTP-5C5CEFDC-EF700
        status:
          type: string
          description: delivery status
          example: DELIVRD
          enum: 
            - DELIVRD
            - EXPIRED
            - UNDELIV
            - REJECTD
            - UNKNOWN
        errorcode:
          type: integer
          description: non "0" value in the response of query-message if query failed
          format: int32
        dlr-timestamp:
          type: string
          description: >-
            When the DLR was recieved from the carrier in the following format
            `YYMMDDHHMM`. For example, `2001010100` is at `2020-01-01 01:00`
          example: '2001010100'
        timestamp:
          type: string
          description: >-
            Timestamp when AMEEX push this delivery receipt to your webhook end
            point.
          example: '2020-01-01 01:00:00'
    inline_response_400:
      type: object
      properties:
        message:
          type: string
    MessagePart:
      type: object
      properties:
        msgid:
          type: string
          description: unique ID of a message
          example: HTTP-5C5CEFDC-EF700
        to:
          type: string
          description: receipient of a message
          example: '96650403020'
  responses:
    401Error:
      description: Authentication failure
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    400Error:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/inline_response_400'
    404Error:
      description: Resource does not exists
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic