openapi: 3.1.0
info:
  version: 3.0.3
  title: AST Services
  license:
    name: Commercial
servers:
  - url: /
paths:
  /v1/tenants/{tenantId}/clients/{astClientId}/pushtoken:
    get:
      description: >-
        Retrieves push token information for the specified `tenantId` and
        `astClientId`. The actual push token is excluded from the response for
        security reasons.
      operationId: getPushToken
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/AstClientId'
      tags:
        - Push
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Push Token details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushToken'
        '401':
          $ref: '#/components/responses/NOT_AUTHORIZED_401'
        '404':
          $ref: '#/components/responses/NOT_FOUND_404'
        '500':
          $ref: '#/components/responses/INTERNAL_SERVER_ERROR_500'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/tenants/{tenantId}/push_notification/send:
    post:
      description: |
        Send push notification message to:
          - either a specific astClient of a user
          - or all astClients of a user
          - or all astClients of all users in a tenant using broadcast (topic-based) messaging
      operationId: sendPushNotification
      parameters:
        - $ref: '#/components/parameters/TenantId'
      tags:
        - Push
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushNotificationEvent'
      responses:
        '202':
          description: A list of NotificationResponse objects
          content:
            application/json:
              schema:
                type: array
                description: >
                  A list of NotificationResponse objects.

                  Each object represents a notification with details such as
                  tenantId, userId, astClientId, notificationId, result, etc.

                  - When a notification is sent to an astClient, it returns only
                  one entry in the list.

                  - When a notification is sent to all astClients of a user, it
                  returns multiple entries in the list.

                  - When notification is sent to all astClients of all users in
                  a tenant, it returns multiple entries in the list,

                  each represent the result of broadcast (topic-based) message
                  for an app in a given tenant.
                items:
                  $ref: '#/components/schemas/NotificationResponse'
        '401':
          $ref: '#/components/responses/NOT_AUTHORIZED_401'
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AppName:
      description: Unique application name
      type: string
      minLength: 1
      examples:
        - clientBackend
    TenantId:
      description: Tenant unique id
      type: string
    PushTokenId:
      description: Unique id of device ( ast client id)
      type: string
      examples:
        - 01G9CKX0QGA840G610MXMMF22K
    UserId:
      description: Unique id of user
      type: string
      minLength: 1
      examples:
        - e2eec6ce-c698-4823-af6a-548a491a84df
    HpkCredentials:
      type: object
      properties:
        hpkClientId:
          type: string
        hpkClientSecret:
          type: string
      required:
        - hpkClientId
        - hpkClientSecret
      additionalProperties: false
    FcmCredentials:
      type: object
      properties:
        androidApiKey:
          type: string
      required:
        - androidApiKey
      additionalProperties: false
    ApnsCredentials:
      type: object
      properties:
        iosApnsCertificate:
          type: string
        iosApnsPrivateKey:
          type: string
        iosBundleId:
          type: string
        iosIsDevelopment:
          type: boolean
      required:
        - iosApnsCertificate
        - iosApnsPrivateKey
        - iosBundleId
        - iosIsDevelopment
      additionalProperties: false
    ApnsHpk:
      allOf:
        - $ref: '#/components/schemas/ApnsCredentials'
        - $ref: '#/components/schemas/HpkCredentials'
      additionalProperties: false
    FcmHpk:
      allOf:
        - $ref: '#/components/schemas/FcmCredentials'
        - $ref: '#/components/schemas/HpkCredentials'
      additionalProperties: false
    FcmApns:
      allOf:
        - $ref: '#/components/schemas/FcmCredentials'
        - $ref: '#/components/schemas/ApnsCredentials'
      additionalProperties: false
    AllProvider:
      allOf:
        - $ref: '#/components/schemas/ApnsCredentials'
        - $ref: '#/components/schemas/HpkCredentials'
        - $ref: '#/components/schemas/FcmCredentials'
      additionalProperties: false
    ProviderPushToken:
      type: string
      examples:
        - >-
          e34Z8kaIuEn2kKy6g7qwlT:APA91bEb2wn61tCvfVg0gcZ4VZ_To5J1zbBeJ1UMDmDMVHiuK0PBO2M9A-zXrzlSY4sPKGn-Zs4-wePcmt7-541RCNLv7bRCHbl6IikdzhOuP7xc6ReZW18ioMqYAytcbxzbsXhiox8
      description: >
        Push token from the push provider. It also supports push provider prefix
        like `FCM:`, `FCMF:`, `GCM:`, `APN:`, `APNS:`, `HPK:` to support legacy
        system.
      minLength: 1
    ProviderPushTokenAllowsEmpty:
      type: string
      examples:
        - >-
          e34Z8kaIuEn2kKy6g7qwlT:APA91bEb2wn61tCvfVg0gcZ4VZ_To5J1zbBeJ1UMDmDMVHiuK0PBO2M9A-zXrzlSY4sPKGn-Zs4-wePcmt7-541RCNLv7bRCHbl6IikdzhOuP7xc6ReZW18ioMqYAytcbxzbsXhiox8
      description: >
        Push token from the push provider. It also supports push provider prefix
        like `FCM:`, `FCMF:`, `GCM:`, `APN:`, `APNS:`, `HPK:` to support legacy
        system.

        Deprecated feature - if empty then pushToken will be removed.
    PushProvider:
      type: string
      enum:
        - APN
        - APNS
        - FCM
        - FCMF
        - GCM
        - HPK
      examples:
        - FCM
      description: Prefix for push provider, used for selection push backend and formatting
    Recipient:
      type: object
      additionalProperties: false
      description: The recipient information, to whom the push notification is to be sent.
      properties:
        tenantId:
          type: string
          description: The unique identifier for the tenant.
        userId:
          type: string
          description: The unique identifier for the user.
        astClientId:
          type: string
          description: The unique identifier for the ast-client.
        topic:
          type: string
          description: The name of the topic.
      anyOf:
        - required:
            - tenantId
            - userId
        - required:
            - tenantId
            - userId
            - astClientId
        - required:
            - tenantId
            - topic
    Payload:
      type: object
      additionalProperties: false
      description: The payload of Push notification.
      properties:
        message:
          $ref: '#/components/schemas/Message'
        customData:
          type: object
          description: >-
            A JSON object containing custom data that is pass to App as it is in
            push notification.
          additionalProperties: true
      required:
        - message
    Message:
      type: object
      additionalProperties: true
      description: Message of push notification
      properties:
        title:
          type: string
          description: The title of the push notification.
        titleLocKey:
          type: string
          description: The localization key for the title of the push notification.
        titleLocArgs:
          description: >-
            The localization message arguments for the title of the push
            notification.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        body:
          type: string
          description: The body of the push notification.
        bodyLocKey:
          type: string
          description: The localization key for the body of the push notification.
        bodyLocArgs:
          description: >-
            The localization message arguments for the body of the push
            notification.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        sound:
          type: string
          description: The sound of the push notification.
        icon:
          type: string
          description: The icon of the push notification.
        collapseKey:
          type: string
          description: >
            The message collapsing key of the push notification.

            Message collapsing allows multiple push notifications with the same
            collapseKey to be merged into a single

            notification if the device has not yet received the previous
            notifications.
        timeToLive:
          type: integer
          format: int64
          description: >
            The number of seconds before your message expires.

            If the push service(FCM, APNs, HPK) can’t deliver a notification
            immediately, it may store the notification

            for 30 days or fewer, depending on the value you specify. The push
            service attempts to deliver the notification

            the next time the device activates and is available online. If the
            push service can’t deliver the notification,

            the push service removes the notification from storage permanently.
            The number of notifications the push services

            stores while the device is offline is limited.
        priority:
          type: string
          description: >
            Indication of whether to send the notification immediately or
            prioritize the recipient’s device power considerations

            for delivery. Provide one of the following values: low, normal, or
            high. To attempt to deliver the notification

            immediately, specify `HIGH`.
          enum:
            - HIGH
            - NORMAL
            - LOW
    Sender:
      type: object
      additionalProperties: false
      description: Sender of push notification
      properties:
        tenantId:
          type: string
          description: The unique identifier for the tenant.
        userId:
          type: string
          description: The unique identifier for the user.
      required:
        - tenantId
        - userId
    NotificationResult:
      required:
        - result
      type: object
      properties:
        result:
          description: The result of push notification
          oneOf:
            - type: string
            - $ref: '#/components/schemas/Error'
        astClientId:
          description: Unique id of device (ast client id)
          type: string
          pattern: ^[0-9A-Za-z]{26}$
          examples:
            - 01F6MJ6J1AA8HWB7G6XRJB709S
    Error:
      required:
        - message
        - code
        - subsystem
      type: object
      properties:
        message:
          description: The error message indicating what the issue is
          type: string
        code:
          description: >-
            The http status code if 100=<code=<600. A custom KOBIL error code
            otherwise
          type: integer
        subsystem:
          description: KOBIL subsystem group. For Ast-Version the value is 517.
          type: integer
    PushToken:
      type: object
      properties:
        appName:
          $ref: '#/components/schemas/AppName'
        pushProvider:
          $ref: '#/components/schemas/PushProvider'
        isValid:
          type: boolean
          description: Push token is valid or it is invalidated by provider
        assignedUsers:
          description: List of assigned users.
          type: array
          items:
            type: string
            examples:
              - e2eec6ce-c698-4823-af6a-548a491a84df
      required:
        - appName
        - pushToken
        - pushProvider
    PushNotificationEvent:
      type: object
      description: Push notification
      additionalProperties: false
      properties:
        category:
          type: string
          description: The type of category
          enum:
            - chat
            - payment
            - tms
        recipient:
          $ref: '#/components/schemas/Recipient'
        payload:
          $ref: '#/components/schemas/Payload'
        sender:
          $ref: '#/components/schemas/Sender'
        silent:
          type: boolean
          description: Indicates whether the push notification is silent or not.
          default: false
      required:
        - category
        - recipient
        - payload
      examples:
        - category: tms
          recipient:
            tenantId: testTenant
            userId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            astClientId: 01F6MJ6J1AA8HWB7G6XRJB709E
          payload:
            message:
              title: Hello
              body: Hello
              priority: HIGH
          silent: false
    NotificationResponse:
      type: object
      required:
        - tenantId
        - results
        - isSuccessful
      properties:
        tenantId:
          type: string
          description: The unique identifier for the tenant.
        userId:
          type: string
          description: The unique identifier for the user.
        astClientId:
          type: string
          description: Unique id of device (ast client id)
        topic:
          type: string
          description: The name of the topic.
        notificationId:
          type: string
          pattern: ^[0-9A-Za-z]{26}$
          examples:
            - 01F6MJ6J1AA8HWB7G6XRJB709E
        isSuccessful:
          type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/NotificationResult'
        metadata:
          type: object
          description: JSON object containing notification information.
          additionalProperties: true
  responses:
    NOT_AUTHORIZED_401:
      description: >-
        The request wasn't authorized (the Authorization header was missing or
        contained invalid jwt token)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NOT_FOUND_404:
      description: Resource is Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    INTERNAL_SERVER_ERROR_500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    TenantId:
      name: tenantId
      in: path
      required: true
      description: Tenant unique id
      schema:
        type: string
        examples:
          - vertx
    AstClientId:
      name: astClientId
      in: path
      required: true
      description: Unique id of device (ast client id)
      schema:
        type: string
        examples:
          - 01G9CKX0QGA840G610MXMMF22K
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  links: {}