openapi: 3.0.0
info:
  title: Notifications API
  contact:
    name: API Integration Support
    email: integration@dintero.com
  description: |
    # Changelog
    All notable changes to the API.

    ## 2020-04-01

    > Add support for `metadata` when publishing a message
    > - [POST /notifications/publish](#tag/publish)

    ## 2019-08-31

    > Support for `time_to_live` when publishing a SMS message
    > - [POST /notifications/publish](#tag/publish)
  version: LATEST
  license:
    name: UNLICENSED
    url: https://dintero.com
  x-logo:
    url: https://docs.dintero.com/img/dintero-dark-padded.svg
    altText: Dintero Logo
security:
  - JWT: []
tags:
  - name: Publish
    description: |
      Publish notifications
paths:
  /accounts/{aid}/notifications/publish:
    post:
      operationId: aid_notifications_publish_post
      summary: aid_notifications_publish_post
      description: |
        Publish a message

        **scopes**:
        - admin:notifications
        - write:notifications
        - admin:accounts
        - write:accounts
      x-scopes:
        - admin:notifications
        - write:notifications
        - admin:accounts
        - write:accounts
      tags:
        - publish
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationMessage'
        required: true
      responses:
        '201':
          $ref: '#/components/responses/PublishCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-mint:
        metadata:
          title: Publish a message
          sidebarTitle: Publish a message
x-tagGroups:
  - name: Notifications
    tags:
      - publish
servers:
  - url: https://api.dintero.com/v1
components:
  parameters:
    accountId:
      name: aid
      description: |
        An id that uniquely identifies the account.
      in: path
      required: true
      schema:
        type: string
        format: ^[PT]{1}\d{8}$
        minLength: 9
        maxLength: 9
  responses:
    PublishCreated:
      description: Message published
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: Message id
    BadRequest:
      description: Bad / Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    JWT:
      type: http
      description: >
        Bearer authentication (token authentication) should be used for
        accessing the API.


        Use [Get Token](/api-reference/authenticate/aid_auths_oauth_token_post)
        to get an access token for client credentials.

        Pass the token in the request header:

            Authorization: Bearer {access_token}

        where the **access_token** is JSON Web Tokens (JWT).
      scheme: bearer
      bearerFormat: JWT
  schemas:
    NotificationMessage:
      type: object
      required:
        - sms
        - message
      properties:
        sms:
          type: object
          description: |
            Publish message with SMS.
          required:
            - sender_id
            - phone_number
          properties:
            transaction_id:
              type: string
              description: |
                Transaction id. Must be unique per message if used.
                This can be used for guarding against resending messages.
            sender_id:
              type: string
              description: |
                The sender ID is displayed as the message sender on the
                receiving device.

                Can be an alphanumeric string, a phone number or a short number
            phone_number:
              type: string
              format: E.164
              example: '+4799999999'
              description: |
                The phone number to which you want to deliver an SMS message.
            time_to_live:
              type: integer
              minimum: 5
              maximum: 1440
              default: 120
              description: |
                Time-To-Live (TTL) in minutes
        message:
          type: string
          description: |
            The message you want to send.

            Constraints:

            - For SMS, each message can contain up to 140 characters. If you
              publish a message that exceeds this size limit, Dintero sends
              the message as multiple messages, each fitting within the size
              limit. Messages aren't truncated mid-word but are cut off at
              whole-word boundaries
        metadata:
          type: object
          description: |
            A set of key/value pairs of associated custom properties
          additionalProperties:
            type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            code:
              type: string
              description: The code used to identify the error/warning
            errors:
              type: array
              description: The nested error(s) encountered during validation
              items:
                type: object
            message:
              type: string
              description: The human readable description of the error/warning