openapi: 3.1.0
info:
  title: ThingsBoard Admin admin-controller notification-template-controller API
  description: 'ThingsBoard Admin API — subset of the ThingsBoard REST API (open-source IoT platform). Covers: Admin, Audit Log, Event, Usage Info, Queue, Queue Stats, Mail Config Template, Qr Code Settings, Job.'
  version: 4.3.0.3DEMO
  contact:
    name: ThingsBoard team
    url: https://thingsboard.io
    email: info@thingsboard.io
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://demo.thingsboard.io
  description: ThingsBoard Live Demo
- url: http://localhost:8080
  description: Local ThingsBoard server
tags:
- name: notification-template-controller
  description: Notification Template
paths:
  /api/notification/template:
    post:
      tags:
      - notification-template-controller
      summary: Save Notification Template (saveNotificationTemplate)
      description: "Creates or updates notification template.\n\nHere is an example of template to send notification via Web, SMS and Slack:\n```json\n{\n  \"name\": \"Greetings\",\n  \"notificationType\": \"GENERAL\",\n  \"configuration\": {\n    \"deliveryMethodsTemplates\": {\n      \"WEB\": {\n        \"enabled\": true,\n        \"subject\": \"Greetings\",\n        \"body\": \"Hi there, ${recipientTitle}\",\n        \"additionalConfig\": {\n          \"icon\": {\n            \"enabled\": true,\n            \"icon\": \"back_hand\",\n            \"color\": \"#757575\"\n          },\n          \"actionButtonConfig\": {\n            \"enabled\": false\n          }\n        },\n        \"method\": \"WEB\"\n      },\n      \"SMS\": {\n        \"enabled\": true,\n        \"body\": \"Hi there, ${recipientTitle}\",\n        \"method\": \"SMS\"\n      },\n      \"SLACK\": {\n        \"enabled\": true,\n        \"body\": \"Hi there, @${recipientTitle}\",\n        \"method\": \"SLACK\"\n      }\n    }\n  }\n}\n```\n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
      operationId: saveNotificationTemplate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationTemplate'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
  /api/notification/templates:
    get:
      tags:
      - notification-template-controller
      summary: Get Notification Templates (getNotificationTemplates)
      description: "Returns the page of notification templates owned by sysadmin or tenant.\n\nYou can specify parameters to filter the results. The result is wrapped with PageData object that allows you to iterate over result set using pagination. See response schema for more details. \n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority."
      operationId: getNotificationTemplates
      parameters:
      - name: pageSize
        in: query
        description: Maximum amount of entities in a one page
        required: true
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        description: Sequence number of page starting from 0
        required: true
        schema:
          type: integer
          format: int32
      - name: textSearch
        in: query
        description: Case-insensitive 'substring' filter based on template's name and notification type
        required: false
        schema:
          type: string
      - name: sortProperty
        in: query
        description: Property of entity to sort by
        required: false
        schema:
          type: string
      - name: sortOrder
        in: query
        description: Sort order. ASC (ASCENDING) or DESC (DESCENDING)
        required: false
        schema:
          type: string
      - name: notificationTypes
        in: query
        description: Comma-separated list of notification types to filter the templates
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageDataNotificationTemplate'
  /api/notification/template/{id}:
    get:
      tags:
      - notification-template-controller
      summary: Get Notification Template by Id (getNotificationTemplateById)
      description: 'Fetches notification template by id.


        Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
      operationId: getNotificationTemplateById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationTemplate'
    delete:
      tags:
      - notification-template-controller
      summary: Delete Notification Template by Id (deleteNotificationTemplateById
      description: 'Deletes notification template by its id.


        This template cannot be referenced by existing scheduled notification requests or any notification rules.


        Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
      operationId: deleteNotificationTemplateById
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
  /api/notification/slack/conversations:
    get:
      tags:
      - notification-template-controller
      summary: List Slack Conversations (listSlackConversations)
      description: 'List available Slack conversations by type.


        Available for users with ''SYS_ADMIN'' or ''TENANT_ADMIN'' authority.'
      operationId: listSlackConversations
      parameters:
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum:
          - DIRECT
          - PUBLIC_CHANNEL
          - PRIVATE_CHANNEL
      - name: token
        in: query
        description: Slack bot token. If absent - system Slack settings will be used
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SlackConversation'
components:
  schemas:
    NotificationTemplate:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/NotificationTemplateId'
        createdTime:
          type: integer
          format: int64
          description: Entity creation timestamp in milliseconds since Unix epoch
          example: 1746028547220
          readOnly: true
        tenantId:
          $ref: '#/components/schemas/TenantId'
        name:
          type: string
          minLength: 1
        notificationType:
          type: string
          enum:
          - GENERAL
          - ALARM
          - DEVICE_ACTIVITY
          - ENTITY_ACTION
          - ALARM_COMMENT
          - RULE_ENGINE_COMPONENT_LIFECYCLE_EVENT
          - ALARM_ASSIGNMENT
          - NEW_PLATFORM_VERSION
          - ENTITIES_LIMIT
          - ENTITIES_LIMIT_INCREASE_REQUEST
          - API_USAGE_LIMIT
          - RULE_NODE
          - RATE_LIMITS
          - EDGE_CONNECTION
          - EDGE_COMMUNICATION_FAILURE
          - TASK_PROCESSING_FAILURE
          - RESOURCES_SHORTAGE
        configuration:
          $ref: '#/components/schemas/NotificationTemplateConfig'
      required:
      - configuration
      - name
      - notificationType
    SlackConversation:
      type: object
      properties:
        type:
          type: string
          enum:
          - DIRECT
          - PUBLIC_CHANNEL
          - PRIVATE_CHANNEL
        id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        wholeName:
          type: string
        email:
          type: string
        title:
          type: string
      required:
      - id
      - name
      - type
    NotificationTemplateConfig:
      type: object
      properties:
        deliveryMethodsTemplates:
          type: object
          additionalProperties:
            oneOf:
            - $ref: '#/components/schemas/EmailDeliveryMethodNotificationTemplate'
            - $ref: '#/components/schemas/MicrosoftTeamsDeliveryMethodNotificationTemplate'
            - $ref: '#/components/schemas/MobileAppDeliveryMethodNotificationTemplate'
            - $ref: '#/components/schemas/SlackDeliveryMethodNotificationTemplate'
            - $ref: '#/components/schemas/SmsDeliveryMethodNotificationTemplate'
            - $ref: '#/components/schemas/WebDeliveryMethodNotificationTemplate'
          minProperties: 1
      required:
      - deliveryMethodsTemplates
    JsonNode:
      description: A value representing the any type (object or primitive)
      examples:
      - {}
    MicrosoftTeamsDeliveryMethodNotificationTemplate:
      allOf:
      - $ref: '#/components/schemas/DeliveryMethodNotificationTemplate'
      - type: object
        properties:
          subject:
            type: string
          themeColor:
            type: string
          button:
            $ref: '#/components/schemas/Button'
      required:
      - body
    Button:
      type: object
      properties:
        enabled:
          type: boolean
        text:
          type: string
        linkType:
          type: string
          enum:
          - LINK
          - DASHBOARD
        link:
          type: string
        dashboardId:
          type: string
          format: uuid
        dashboardState:
          type: string
        setEntityIdInState:
          type: boolean
    WebDeliveryMethodNotificationTemplate:
      allOf:
      - $ref: '#/components/schemas/DeliveryMethodNotificationTemplate'
      - type: object
        properties:
          subject:
            type: string
            minLength: 1
          additionalConfig:
            $ref: '#/components/schemas/JsonNode'
      required:
      - body
      - subject
    PageDataNotificationTemplate:
      type: object
      properties:
        data:
          type: array
          description: Array of the entities
          items:
            $ref: '#/components/schemas/NotificationTemplate'
          readOnly: true
        totalPages:
          type: integer
          format: int32
          description: Total number of available pages. Calculated based on the 'pageSize' request parameter and total number of entities that match search criteria
          readOnly: true
        totalElements:
          type: integer
          format: int64
          description: Total number of elements in all available pages
          readOnly: true
        hasNext:
          type: boolean
          description: '''false'' value indicates the end of the result set'
          readOnly: true
    DeliveryMethodNotificationTemplate:
      type: object
      discriminator:
        propertyName: method
      properties:
        enabled:
          type: boolean
        body:
          type: string
          minLength: 1
        method:
          type: string
      required:
      - body
      - method
    SmsDeliveryMethodNotificationTemplate:
      allOf:
      - $ref: '#/components/schemas/DeliveryMethodNotificationTemplate'
      required:
      - body
    EmailDeliveryMethodNotificationTemplate:
      allOf:
      - $ref: '#/components/schemas/DeliveryMethodNotificationTemplate'
      - type: object
        properties:
          subject:
            type: string
            minLength: 1
      required:
      - body
      - subject
    NotificationTemplateId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - NOTIFICATION_TEMPLATE
          example: NOTIFICATION_TEMPLATE
      required:
      - entityType
      - id
    TenantId:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the entity, time-based UUID v1
          example: 784f394c-42b6-435a-983c-b7beff2784f9
        entityType:
          type: string
          description: string
          enum:
          - TENANT
          example: TENANT
      required:
      - entityType
      - id
    MobileAppDeliveryMethodNotificationTemplate:
      allOf:
      - $ref: '#/components/schemas/DeliveryMethodNotificationTemplate'
      - type: object
        properties:
          subject:
            type: string
            minLength: 1
          additionalConfig:
            $ref: '#/components/schemas/JsonNode'
      required:
      - body
      - subject
    SlackDeliveryMethodNotificationTemplate:
      allOf:
      - $ref: '#/components/schemas/DeliveryMethodNotificationTemplate'
      required:
      - body
  securitySchemes:
    HTTP login form:
      type: http
      description: Enter Username / Password
      scheme: loginPassword
      bearerFormat: /api/auth/login|X-Authorization
    API key form:
      type: apiKey
      description: 'Enter the API key value with ''ApiKey'' prefix in format: **ApiKey <your_api_key_value>**


        Example: **ApiKey tb_5te51SkLRYpjGrujUGwqkjFvooWBlQpVe2An2Dr3w13wjfxDW**


        <br>**NOTE**: Use only ONE authentication method at a time. If both are authorized, JWT auth takes the priority.<br>

        '
      name: X-Authorization
      in: header