openapi: 3.1.0
info:
  title: Intelligent Messaging API
  version: 0.0.1
  description: This is the Intelligent Messaging API for sending messages with automated fallback to other delivery channels.
  termsOfService: https://www.modicagroup.com/privacy-policy
  contact:
    name: API Support
    email: support@ezitxt.com
    url: https://www.modicagroup.com
  license:
    name: Modica API - Terms Of Use
    url: https://confluence.modicagroup.com/download/attachments/12386319/Modica%20Group%20-%20Terms%20of%20Use.pdf?version=1&modificationDate=1500544212144&api=v2
servers:
  - url: https://new.eziapi.com/rest/im/v1
    description: The Intelligent Messaging API.
paths:
  /message:
    post:
      tags:
        - messages
      operationId: message_post
      summary: Send a message with automated fallback to other delivery channels.
      description: Send a message with automated fallback to other delivery channels.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessagePostRequest'
      responses:
        "202":
          $ref: "#/components/responses/ResponseMessagePost"
        "400":
          $ref: "#/components/responses/ResponseBadRequest"
        "401":
          $ref: "#/components/responses/ResponseUnauthorized"
        "404":
          $ref: "#/components/responses/ResponseNotFound"
        "422":
          $ref: "#/components/responses/ResponseUnprocessableEntity"
        "429":
          $ref: "#/components/responses/ResponseTooManyRequests"
        "500":
          $ref: "#/components/responses/ResponseInternalServerError"
      callbacks:
        messageCallback:
          "{$statusCallbackUrl}":
            post:
              summary: Status/DLR callback
              description: Sent when the status of a MT message is updated
              requestBody:
                $ref: "#/components/requestBodies/RequestMessageStatusCallback"
              responses:
                "200":
                  description: callback successfully processed
                  headers:
                    X-RateLimit-Limit:
                      $ref: "#/components/headers/X-RateLimit-Limit"
                "401":
                  $ref: "#/components/responses/ResponseUnauthorized"
                "429":
                  $ref: "#/components/responses/ResponseTooManyRequests"
                "500":
                  $ref: "#/components/responses/ResponseInternalServerError"
components:
  responses:
    ResponseMessagePost:
      description: Successful Post Message response structure.
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                $ref: "#/components/schemas/Uuid"
          example:
            id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    ResponseBadRequest:
      description: Invalid request data. This response is returned when the request data is invalid or improperly formatted.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            message: API bad request error
            statusCode: 400
            error: bad request error message
    ResponseNotFound:
      description: Not Found. This response indicates that the requested resource was not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            message: API not found error
            statusCode: 404
            error: not found error message
    ResponseInternalServerError:
      description: Internal server error. This response is returned when an internal server error occurs.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            message: API internal server error
            statusCode: 500
            error: internal server error message
    ResponseUnauthorized:
      description: Unauthorized. This response is returned when the user is not authorized to perform the requested action.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            message: API unauthorized error
            statusCode: 401
            error: unauthorized error message
    ResponseUnprocessableEntity:
      description: Unprocessable Entity. This response is returned when the request data is correct but cannot be processed.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            message: API unprocessable entity error
            statusCode: 422
            error: unprocessable entity error message
    ResponseTooManyRequests:
      description: Too Many Requests. This response indicates that the client has exceeded the rate limits.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/APIError"
          example:
            message: API too many requests error
            statusCode: 429
            error: too many requests error message
  schemas:
    MessagePostRequest:
      title: Message Send Request
      type: object
      properties:
        destination:
          $ref: "#/components/schemas/Destination"
        message:
          $ref: "#/components/schemas/Message"
        delivery_attempts:
          type: array
          items:
            $ref: "#/components/schemas/DeliveryAttempt"
          minItems: 1
          maxItems: 10
        reference:
          type: string
          format: none
          maxLength: 255
        scheduler_pipe:
          $ref: "#/components/schemas/SchedulerPipe"
      required:
        - destination
        - message
    Destination:
      title: Destination
      type: object
      minProperties: 1
      properties:
        contact_id:
          $ref: "#/components/schemas/Uuid"
        mobile:
          $ref: "#/components/schemas/E164"
        email:
          $ref: "#/components/schemas/Email"
    Source:
      title: Source
      type: object
      minProperties: 1
      properties:
        source_id:
          $ref: "#/components/schemas/Uuid"
        channel_sources:
          type: array
          items:
            $ref: "#/components/schemas/ChannelSource"
          minItems: 1
          maxItems: 10
    SchedulerPipe:
      description: The scheduler pipe can be specified here.
      type: string
      enum:
        - dynamic
        - eventbridge
        - sqs
    ChannelSource:
      description: The source for this channel.
      type: object
      properties:
        channel:
          $ref: "#/components/schemas/Channel"
        source:
          type: string
          minLength: 1
          maxLength: 30
      required:
        - channel
        - source
      example:
        channel: email
        source: im-email@modicagroup.com
    Message:
      title: Message
      type: object
      minProperties: 2
      properties:
        type:
          $ref: "#/components/schemas/MessageType"
        text:
          $ref: "#/components/schemas/TextMessage"
        media:
          $ref: "#/components/schemas/MediaMessage"
        template:
          $ref: "#/components/schemas/TemplateMessage"
      required:
        - type
    TextMessage:
      title: Content of a Text message.
      type: object
      properties:
        body:
          $ref: "#/components/schemas/LongString"
      required:
        - body
    MediaMessage:
      title: Content of a Media message.
      type: object
      properties:
        type:
          $ref: "#/components/schemas/MimeType"
        url:
          $ref: "#/components/schemas/Url"
      required:
        - type
        - url
      example:
        type: image/png
        url: https://www.luckyshrub.com/assets/succulents/aloe.png
    TemplateMessage:
      title: Content of a Template message.
      type: object
      properties:
        template_id:
          $ref: "#/components/schemas/Uuid"
        language:
          type: string
          minLength: 2
          maxLength: 5
          pattern: "^[_a-zA-Z]+$"
          example: en
        parameters:
          type: array
          items:
            $ref: "#/components/schemas/TemplateParameter"
          minItems: 0
          maxItems: 20
      required:
        - template_id
      example:
        template_id: otp_wab_template
    TemplateParameter:
      description: The text value that will replace the parameter in the template.
      type: object
      properties:
        name:
          description: Name of the template parameter.
          $ref: "#/components/schemas/ShortString"
        text:
          description: Value of the template parameter.
          type: string
          format: none
          maxLength: 256
      required:
        - name
        - text
      example:
        name: otp_code
        text: "458972"
    DeliveryAttempt:
      description: Sequence of channel delivery attempts.
      type: object
      properties:
        channel:
          $ref: "#/components/schemas/Channel"
        event:
          $ref: "#/components/schemas/ShortString"
        timeout:
          description: timeout in seconds.
          type: integer
          format: int32
          minimum: 0
          maximum: 604800
      required:
        - channel
      examples:
        - firstdeliveryattempt:
            channel: wab
            event: read
            timeout: 15
        - lastdeliveryattempt:
            channel: email
    Channel:
      type: string
      enum:
        - wab
        - sms
        - mms
        - email
        - rcs
    MessageType:
      type: string
      enum:
        - text
        - media
        - template
    MimeType:
      type: string
      pattern: \w+\/[-+.\w]+
      maxLength: 255
    E164:
      description: The destination number in E.164 format.
      type: string
      maxLength: 16
      pattern: ^\+[1-9]\d{1,14}$
    APIError:
      title: APIError
      type: object
      properties:
        code:
          type: integer
          format: int32
          minimum: 200
          maximum: 500
        message:
          $ref: "#/components/schemas/LongString"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/Error"
          maxItems: 100
      description: Generic API Errors object.
    Error:
      title: Error
      description: A generic error object.
      type: object
      properties:
        field:
          $ref: "#/components/schemas/ShortString"
        code:
          type: integer
          format: int64
          minimum: 200
          maximum: 500
        description:
          $ref: "#/components/schemas/LongString"
      required:
        - description
    LongString:
      description: A generic long string format.
      type: string
      pattern: "^[-_ a-zA-Z0-9]+$"
      maxLength: 10000
    ShortString:
      description: A generic short string format.
      type: string
      pattern: "^[-_ a-zA-Z0-9]+$"
      maxLength: 256
    Url:
      type: string
      format: url
    Uuid:
      description: A random UUID - version 4.
      type: string
      pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
      minLength: 36
      maxLength: 36
    Email:
      description: An email address.
      type: string
      format: email
      maximum: 320
    StatusCallback:
      description: Status callback structure.
      type: object
      properties:
        id:
          type: string
          format: uuid
          maxLength: 36
        detail:
          type: string
          format: none
          maxLength: 255
        status:
          type: string
          enum:
            - accepted
            - submitted
            - sent
            - received
            - read
            - frozen
            - rejected
            - failed
            - dead
            - expired
  headers:
    Content-Security-Policy:
      description: Content Security Policy to prevent certain types of attacks.
      schema:
        type: string
        pattern: "^['-_ a-zA-Z0-9]+$"
        maxLength: 255
        example: frame-ancestors 'none'
    Strict-Transport-Security:
      description: HSTS header to enforce HTTPS
      schema:
        type: string
        pattern: "^max-age=[0-9]+(; includeSubDomains)?(; preload)?$"
        maxLength: 255
        example: max-age=31536000; includeSubDomains; preload
    X-RateLimit-Limit:
      schema:
        type: integer
        format: int32
        maximum: 100
        minimum: 0
      description: Requests per second limit.
    RetryAfter:
      schema:
        type: integer
        format: int32
        maximum: 1000
        minimum: 10
      description: The number of seconds to wait before allowing a follow-up request.
  requestBodies:
    RequestMessageStatusCallback:
      description: Status callback payload
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StatusCallback"
          examples:
            received:
              value:
                id: 2af85f64-3645-1078-b3fc-2c963f66afa6
                detail: ref-abc123
                status: received
            read:
              value:
                id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                detail: ref-def456
                status: read
  securitySchemes:
    gateway_auth:
      type: apiKey
      in: header
      name: authorization
      description: A custom authorizer for the im-api service.
security:
  - gateway_auth: []
tags:
  - name: messages
    description: Messaging endpoints.