openapi: 3.0.0
info:
  title: WorkCloud Communication Services APIs
  contact: {}
  version: 1.49.25403.068
servers:
  - url: https://kag-uat-zwsusnpuat01t.pp.zebra.com
    description: Krakend
paths:
  /internal/admin/comms/v1/forums:
    get:
      summary: Get All Forums
      description: Get All Forums
      tags:
        - User Forums
      security:
        - BearerAuth: []
      parameters:
        - name: forumId
          in: query
          schema:
            type: integer
            default: 0
          description: Forum ID
        - name: filter
          in: query
          schema:
            type: string
          description: Filter
        - name: subscribedOnly
          in: query
          schema:
            type: boolean
          description: Subscribed only (will be ignored if forumId is provided)
        - name: page
          in: query
          schema:
            type: integer
            default: 0
          description: Page number
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
          description: Page size
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.GetAllForumResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
    post:
      summary: Create Forum
      description: Create Forum
      tags:
        - User Forums
      security:
        - BearerAuth: []
      parameters:
        - name: tenantId
          in: query
          required: true
          description: tenantId
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.CreateUpdateForumRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
  /internal/admin/comms/v1/forums/posts:
    get:
      summary: Get Forum Posts
      description: Get Forum Posts
      tags:
        - User Forums
      security:
        - BearerAuth: []
      parameters:
        - name: forumId
          in: query
          required: true
          schema:
            type: integer
          description: Forum ID
        - name: page
          in: query
          schema:
            type: integer
            default: 0
          description: Page number
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
          description: Page size
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.GetForumPostsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
    post:
      summary: Create Forum Post
      description: Create Forum Post
      tags:
        - User Forums
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.ExternalForumPostRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
    put:
      summary: Update Forum Post
      description: Update Forum Post
      tags:
        - User Forums
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.UpdateForumPostRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
  /internal/admin/comms/v1/forums/subscribers:
    get:
      summary: Get Forum Subscribers
      description: Get Forum Subscribers
      tags:
        - User Forums
      security:
        - BearerAuth: []
      parameters:
        - name: forumId
          in: query
          required: true
          schema:
            type: integer
          description: Forum ID
        - name: page
          in: query
          schema:
            type: integer
            default: 0
          description: Page number
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
          description: Page size
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.SubscribersList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
    post:
      summary: Subscribe to a Forum
      description: Subscribe to a Forum
      tags:
        - User Forums
      security:
        - BearerAuth: []
      parameters:
        - name: tenantId
          in: query
          required: true
          description: tenantId
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.ForumSubscribeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ForumResponse'
  /internal/admin/comms/v1/messages:
    post:
      summary: Send Message
      description: Post a message with at least one target
      tags:
        - User Messages
      security:
        - BearerAuth: []
      parameters:
        - name: user
          in: query
          schema:
            type: array
            items:
              type: string
            description: >
              User list (Note: Do not use site list input field if message is meant for a user.)
        - name: site
          in: query
          schema:
            type: array
            items:
              type: string
          description: Site list
        - name: role
          in: query
          schema:
            type: array
            items:
              type: string
          description: Role list
        - name: dept
          in: query
          schema:
            type: array
            items:
              type: string
          description: Department list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.MessageText'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.MessageResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'

  /internal/admin/comms/v1/help/request:
    post:
      summary: Create a new help request
      description: | 
        This API allows a user to create a new help request against specified target.

        Below is the map of notification type and what they represent:
          - 0 - Voice
          - 1 - UI
      tags:
        - Assistant
      security:
        - BearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HelpRequest'
      responses:
        '200':
          description: Request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Help'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
    get:
      summary: Get help requests for a tenant
      description: |
        This API retrieves help requests for a specified tenant and site with pagination support.

        Below is the map of status codes and what they represent:
          - 1 - Quota Met
          - 3 - Escalated
          - 4 - Stopped
          - 5 - No Ring
          - 6 - Completed By Escalation        
      tags:
        - Assistant
      security:
        - BearerAuth: [ ]
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
          description: Tenant ID of the request originator
        - name: site_name
          in: query
          required: true
          schema:
            type: string
          description: Site Name of the request
        - description: page number for returned records
          in: query
          name: page
          schema:
            type: integer
            default: 0
        - description: number of records to return per page.
          in: query
          name: page_size
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Help requests retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetHelpRequestsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
  
  /internal/admin/comms/v1/help/analytics:
    get:
      summary: Get analytics data
      tags:
        - Assistant
      security:
        - BearerAuth: [ ]
      parameters:
        - description: tenant id of required records
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Request created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'

  /internal/admin/comms/v1/help/request/status:
    get:
      summary: Get help request status
      description: |
        This API retrieves the status of a help request for a specified tenant and user.

        Below is the map of status codes and what they represent:
          - 1 - Quota Met
          - 3 - Escalated
          - 4 - Stopped
          - 5 - No Ring
          - 6 - Completed By Escalation 
      tags:
        - Assistant
      security:
        - BearerAuth: [ ]
      parameters:
        - name: tenant_id
          in: query
          required: true
          schema:
            type: string
          description: Tenant ID of the request
        - name: help_id
          in: query
          schema:
            type: integer
            format: int64
          description: Help request ID
        - name: user_login
          in: query
          required: true
          schema:
            type: string
          description: UserLogin
        - name: has_active_help_request
          in: query
          required: false
          schema:
            type: boolean
          description: Flag to check if the user has an active help request
      responses:
        '200':
          description: Status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpRequestStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
  /internal/admin/comms/v1/help/request/cancel:
    put:
      summary: Cancel a help request
      security:
        - BearerAuth: [ ]
      tags:
        - Assistant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelHelpRequest'
      responses:
        '200':
          description: successfully cancelled help request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPStatus'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HelpErrorResponse'

  /internal/admin/comms/v1/location/access-points:
    get:
      summary: Get list of access points
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      parameters:
        - description: tenant id of required records
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
        - description: site id of required records
          in: query
          name: site_id
          schema:
            type: string
        - description: page number for returned records
          in: query
          name: page
          schema:
            type: integer
            default: 0
        - description: number of records to return per page.
          in: query
          name: page_size
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: A list of access points
          content:
            application/json:
              schema:
                type: object
                properties:
                  bssid_mapping:
                    type: array
                    items:
                      type: object
                      properties:
                        bssid:
                          type: string
                        name:
                          type: string
                        customer_id:
                          type: integer
                        site_id:
                          type: string
                        location_friendly_name:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
    put:
      summary: Update access points
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tenant_id:
                  type: string
                bssid_mapping:
                  type: array
                  items:
                    $ref: '#/components/schemas/dto.AccessPoint'
      responses:
        '200':
          description: Access Points updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateResponse'
        '404':
          description: Not Found
          content:
            application/json:
              application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateErrorResponse'
    post:
      summary: Upload CSV for Access Points
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                -tenant_id
                -csvFile
              properties:
                tenant_id:
                  type: string
                  description: Tenant id of records
                csvFile:
                  description: CSV File Upload of Access Points
                  type: string
                  format: binary
      responses:
        '200':
          description: CSV uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CreateErrorResponse'
    delete:
      summary: Delete Access Points for a tenant
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      parameters:
        - description: Tenant id of the records to delete
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
        - description: BSSID of the records to delete
          in: query
          name: bss_id
          required: false
          schema:
            type: string
        - description: Site id of the records to delete
          in: query
          name: site_id
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Access Point deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
  /internal/admin/comms/v1/location/users/connected:
    get:
      summary: Get list of users connected to access points
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      parameters:
        - description: tenant id of required records
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
        - description: site id of required records
          in: query
          name: site_id
          schema:
            type: string
        - description: page number for returned records
          in: query
          name: page
          schema:
            type: integer
            default: 0
        - description: number of records to return per page.
          in: query
          name: page_size
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: A list of users and their connected access points
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        user_login:
                          type: string
                        bssid:
                          type: string
                        customer_id:
                          type: integer
                        site_id:
                          type: string
                        ap_location_friendly_name:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
  /internal/admin/comms/v1/location/user/access-point:
    post:
      summary: Update Access point for a user
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tenant_id:
                  type: string
                user_login:
                  type: string
                bss_id:
                  type: string
      responses:
        '200':
          description: User added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_login:
                    type: string
                  bssid:
                    type: string
                  customer_id:
                    type: integer
                  site_id:
                    type: string
                  ap_location_friendly_name:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
    get:
      summary: Get access point for user
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      parameters:
        - description: tenant id of required record
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
        - description: userLogin of required record
          name: user_login
          in: query
          required: true
          schema:
            type: string
        - description: site id of required record
          name: site_id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retrieves the most recent access point that specified user is connected to for a given tenant and site.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLastConnectedAPResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
  /internal/admin/comms/v1/location/access-points/download:
    get:
      summary: Download access points as CSV
      description: Downloads access point data as a CSV file that can be used for editing and re-uploading
      tags:
        - User Location
      security:
        - BearerAuth: [ ]
      parameters:
        - description: Tenant ID of the records to download
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
        - description: Site id to filter records (optional)
          in: query
          name: site_id
          required: false
          schema:
            type: string
        - description: page number for returned records
          in: query
          name: page
          schema:
            type: integer
            default: 0
        - description: number of records to return per page.
          in: query
          name: page_size
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: CSV file containing access point data
          content:
            text/csv:
              schema:
                type: string
                format: binary
              example: "bssid,name,tenant_id,site_id,location_friendly_name\n00:11:22:33:44:55,AP1,tenant123,Site1,Building A Floor 1\n"
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                  message:
                    type: string

  /internal/admin/comms/v1/user-presence:
    get:
      summary: Get Presence of User
      tags:
        - User Presence
      description: Get Presence of User
      security:
        - BearerAuth: [ ]
      consumes:
        - application/json
      parameters:
        - description: User Login
          in: query
          name: userLogin
          required: true
          schema:
            type: string
        - description: Tenant ID
          in: query
          name: tenant_id
          required: true
          schema:
            type: string
      produces:
        - application/json
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
  /internal/admin/comms/v1/user-presence/{siteName}:
    get:
      summary: Get presence of users belonging to a site
      tags:
        - User Presence
      description: Get presence of users belonging to a site
      security:
        - BearerAuth: []
      parameters:
        - name: tenantId
          in: query
          required: true
          schema:
            type: string
          description: Tenant ID
        - name: siteName
          in: path
          required: true
          schema:
            type: string
          description: Site Name
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: page number
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 50
          description: page size (Default - 20, Max - 50)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPStatus'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'                
  /internal/admin/comms/v1/user-presence/{siteName}/{deptName}:
    get:
      summary: Get presence of users belonging to a Department of a site
      tags:
        - User Presence
      description: Get presence of users belonging to a Department of a site
      security:
        - BearerAuth: []
      parameters:
        - name: tenantId
          in: query
          required: true
          schema:
            type: string
          description: Tenant ID
        - name: siteName
          in: path
          required: true
          schema:
            type: string
          description: Site Name
        - name: deptName
          in: path
          required: true
          schema:
            type: string
          description: Department Name
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: page number
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 50
          description: page size (Default - 20, Max - 50)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPStatus'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
  /internal/admin/comms/v1/group/all:
    get:
      summary: Get all groups
      description: Get all groups created by authenticated user
      tags:
        - User Groups
      security:
        - BearerAuth: [ ]
      parameters:
        - name: tenantId
          in: query
          required: true
          schema:
            type: string
          description: Tenant ID
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Page number (starts from 0)
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 50
          description: Number of groups per page (max 50)
      responses:
        '200':
          description: Successfully retrieved ad-hoc groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  site_name:
                    type: string
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExternalAdhocGroupInfoDTO'
                  total_rows:
                    type: integer
                    format: int64
                    description: Total number of ad-hoc groups
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
  /internal/admin/comms/v1/group:
    post:
      summary: Create Group
      description: >
        Creates a new user group. At least three targets are required. 
      tags:
        - User Groups
      security:
        - BearerAuth: [ ]
      parameters:
        - name: tenantId
          in: query
          required: true
          schema:
            type: string
          description: Tenant ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.ExternalGroupCreateDTO'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.ExternalGroupDTO'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPresenceResponse'
        "404":
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
  /internal/admin/comms/v1/group/{groupId}:
    get:
      description: Get details of a group as an external user
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: integer
          description: Group ID to retrieve
      responses:
        '200':
          description: Successfully retrieved group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExternalGroupDTO'
        "400":
          description: Invalid request parameters
          schema:
            $ref: '#/components/schemas/GroupResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "500":
          description: Server error while processing request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
      security:
        - BearerAuth: [ ]
      summary: Get Group Details
      tags:
        - User Groups
    put:
      summary: Update Group Info
      description: This API updates the groupname and description.
      tags:
        - User Groups
      security:
        - BearerAuth: [ ]
      parameters:
        - name: groupId
          in: path
          description: Group ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.ExternalGroupInfoDTO'
      responses:
        "200":
          description: Successfully updated group info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
    delete:
      description: Delete a group as an external user with admin
        privileges
      parameters:
        - name: groupId
          in: path
          description: Group ID
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successfully deleted group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "400":
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "500":
          description: Server error while processing request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
      security:
        - BearerAuth: [ ]
      summary: Delete Group
      tags:
        - User Groups
  /internal/admin/comms/v1/group/target/{groupId}:
    put:
      description: |
        NOTE: 'admin' and 'subscribe' fields, if not passed, will default to false.
      parameters:
        - name: groupId
          in: path
          description: Group ID
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.GroupTargetDTO'
      responses:
        "200":
          description: Successfully updated group targets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "400":
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "401":
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        "403":
          description: User does not have permission to update the group targets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "404":
          description: Group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
        "500":
          description: Server error while processing request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupResponse'
      security:
        - BearerAuth: [ ]
      summary: Update Group Targets
      tags:
        - User Groups
  /internal/admin/comms/v1/u-search:
    post:
      summary: Universal Search
      description: |
        Perform a universal search across communication services (scopes 1, 2, 4, 5, and 6) and Todo services (3, 7, 8, and 9).
 
        Scope values:
          - 1 = Broadcast
          - 2 = Messages
          - 3 = Tasks
          - 4 = Attachments
          - 5 = Forums
          - 6 = Contacts
          - 7 = TaskTags
          - 8 = TasksForYou
          - 9 = TasksAll
      tags:
        - U-Search
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/USearchRequest'
      responses:
        '200':
          description: Scope-wise search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/USearchResponse'
        '400':
          description: Bad request (validation errors)
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.HTTPStatus'
        '502':
          description: Upstream service failure
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

components:
  securitySchemes:
    BearerAuth: # arbitrary name for the security scheme
      description: >-
        Enter the token
      type: http
      scheme: bearer
  schemas:
    admin.CreateUpdateForumRequest:
      type: object
      properties:
        adminOnly:
          type: boolean
        description:
          type: string
        forumId:
          type: integer
        name:
          type: string
        private:
          type: boolean
        subscribers:
          type: array
          items:
            $ref: '#/components/schemas/admin.ForumTarget'
    admin.ExternalForumPostRequest:
      type: object
      properties:
        forumId:
          type: integer
        title:
          type: string
        body:
          type: string
        anonymous:
          type: boolean
        commentsOff:
          type: boolean
    admin.FilteredPost:
      type: object
      properties:
        post:
          $ref: '#/components/schemas/admin.Post'
    admin.ForumResponse:
      type: object
      properties:
        details:
          type: string
        forumId:
          type: integer
        statusCode:
          type: integer
    admin.ForumSubscribeRequest:
      type: object
      properties:
        forumId:
          type: integer
        subscribers:
          type: array
          items:
            $ref: '#/components/schemas/admin.SubscribeTargetDTO'
    admin.GetAllForumResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/dto.PagedResults'
        statusCode:
          type: integer
    admin.GetForumPostsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/admin.FilteredPost'
        statusCode:
          type: integer
    admin.MessageResponse:
      type: object
      properties:
        text:
          type: string
        type:
          type: string
    admin.MessageText:
      type: object
      properties:
        text:
          type: string
    admin.Post:
      type: object
      properties:
        id:
          type: integer
        text:
          type: string
        title:
          type: string
    admin.SubscriberResponse:
      type: object
      properties:
        First Name:
          type: string
        Last Name:
          type: string
        Permission:
          type: string
    admin.SubscribersList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/admin.SubscriberResponse'
        statusCode:
          type: integer
    admin.SubscribeTargetDTO:
      type: object
      properties:
        subscribe:
          type: boolean
        tgtPerm:
          type: string
        userLogin:
          type: string
    admin.Target:
      type: object
      properties:
        is_admin:
          type: boolean
        user_login:
          type: string
    admin.ForumTarget:
      type: object
      properties:
        tgtPerm:
          type: string
        userLogin:
          type: string
    admin.UpdateForumPostRequest:
      type: object
      properties:
        anonymous:
          type: boolean
        body:
          type: string
        commentsOff:
          type: boolean
        postId:
          type: integer
        title:
          type: string
    dto.HTTPStatus:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: Success
    dto.PagedResults:
      type: object
      properties:
        data:
          description: json array with data objects
        page:
          type: integer
          format: int32
          description: Page number starting from 0
        pageSize:
          type: integer
          format: int32
          description: Page size
        totalRecords:
          type: integer
          format: int64
          description: Total number of records available for this query
    HelpRequest:
      type: object
      properties:
        initiatorLogin:
          type: string
          description: User Login of the request originator
        destination:
          type: string
          description: Destination for the responders to reach
        quota:
          type: integer
          format: int16
          description: The number of responders required
        tenant_id:
          type: string
          description: Tenant ID of the request originator
        notification_type:
          type: integer
          format: int16
          description: notification type - Voice - 0, UI - 1
        target:
            type: object
            properties:
              roleName:
                type: string
                nullable: true
              deptId:
                type: string
                nullable: true
      required:
        - initiatorLogin
        - tenant_id
        - targetList
    GetHelpRequestsResponse:
      type: object
      properties:
        statusCode:
          type: integer
        helpRequests:
          type: array
          items:
            $ref: '#/components/schemas/Help'
    Help:
      type: object
      properties:
        id:
          type: integer
          format: int64
        initiatorLogin:
          type: string
        quota:
          type: integer
          format: int16
        destination:
          type: string
        created_at:
          type: string
          format: date-time
        targetList:
          type: object
          additionalProperties: true
        notificationType:
          description: Voice - 0, UI - 1
          type: string
    HelpRequestStatus:
      type: object
      properties:
        helpId:
          type: integer
          format: int64
        user_logins:
          type: array
          items:
            type: string
        isQuotaReached:
          type: boolean
        status:
          type: integer
          format: int16
        quota:
          type: integer
          format: int16
        respondents:
          type: integer
          format: int16
        rejections:
          type: integer
          format: int16
        responders_user_logins:
          type: array
          items:
            type: string
        responses:
          type: array
          items:
            type: object
            properties:
              userLogin:
                type: string
              timestamp:
                type: integer
                format: int64
                description: Unix timestamp of when the response was recorded
    CancelHelpRequest:
      type: object
      properties:
        helpId:
          type: integer
          format: int64
          description: Help Request Id
        user_login:
          type: string
          description: User Login of the request originator
        tenant_id:
          type: string
          description: Tenant ID of the request originator
      required:
        - helpId
        - user_login
        - tenant_id
    AnalyticsResponse:
      type: object
      properties:
        totalRequests:
          type: integer
          format: int32
        totalInTimeResponses:
          type: integer
          format: int32
        escalations:
          type: integer
          format: int32
        averageResponseTime:
          type: number
          format: float
    ExternalAdhocGroupInfoDTO:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ExternalTargetDTO'
    ExternalTargetDTO:
      type: object
      properties:
        userLogin:
          type: string
        isAdmin:
          type: boolean
    HelpErrorResponse:
      type: object
      properties:
        code:
          type: integer
        errors:
          items:
            type: string
          type: array
    HTTPStatus:
      type: object
      properties:
        Code:
          type: integer
          example: 0
        Message:
          type: string
    dto.AccessPoint:
      type: object
      properties:
        bssid:
          type: string
        name:
          type: string
        tenant_id:
          type: string
        site_id:
          type: string
        ap_created_name:
          type: string
    GetLastConnectedAPResponse:
      type: object
      properties:
        statusCode:
          type: integer
        access_point_data:
          type: array
          items:
            type: object
            properties:
              user_id:
                type: integer
              user_login:
                type: string
              bssid:
                type: string
              name:
                type: string
              customer_id:
                type: integer
              site_name:
                type: string
              ap_friendly_name:
                type: string
              updated_at:
                type: string
                format: date-time
              created_at:
                type: string
                format: date-time
    dto.CreateResponse:
      type: object
      properties:
        code:
          type: integer
        totalRecords:
          type: integer
        successfullyProcessedRecords:
          type: integer
        ignoredRecords:
          type: integer
        errors:
          items:
            type: string
          type: array
    dto.CreateErrorResponse:
      type: object
      properties:
        code:
          type: integer
        errors:
          items:
            type: string
          type: array
    UserPresenceList:
      type: object
      properties:
        statusCode:
          type: integer
        presences:
          type: array
          items:
            $ref: '#/components/schemas/Presence'
    Presence:
      type: object
      properties:
        userLogin:
          type: string
        presence:
          type: string
        updatedAt:
          type: string
    UserPresenceResponse:
      type: object
      properties:
        statusCode:
          type: integer
        details:
          type: string
    admin.ExternalGroupCreateDTO:
      properties:
        name:
          type: string
        description:
          type: string
        targets:
          items:
            $ref: '#/components/schemas/admin.Target'
          type: array
      type: object
    admin.ExternalGroupInfoDTO:
      properties:
        name:
          type: string
        description:
          type: string
      type: object
    admin.SubscribeTarget:
      properties:
        is_admin:
          type: boolean
        subscribe:
          type: boolean
        user_login:
          type: string
      type: object
    admin.ExternalGroupDTO:
      properties:
        id:
          type: integer
        description:
          type: string
        name:
          type: string
        targets:
          items:
            $ref: '#/components/schemas/admin.Target'
          type: array
      type: object
    admin.GroupTargetDTO:
      properties:
        targets:
          items:
            $ref: '#/components/schemas/admin.SubscribeTarget'
          type: array
      type: object
    dto.TargetDTO:
      properties:
        depId:
          type: integer
        extension:
          description: used to set phone/extension number for TgtTypeSip
          type: string
        grpId:
          type: integer
        locId:
          type: integer
        regionId:
          type: integer
        roleId:
          type: integer
        siteId:
          type: integer
        tgtId:
          description: deprecated
          type: integer
        tgtName:
          description: deprecated
          type: string
        tgtPerm:
          description: 'optional permissions (default: ''rw'')'
          type: string
        tgtType:
          allOf:
            - $ref: '#/components/schemas/model.TargetType'
          description: deprecated
          format: int16
        userId:
          type: integer
      type: object
    model.TargetType:
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
        - 5
        - 6
        - 7
        - 10
      type: integer
      x-enum-varnames:
        - TgtTypeUser
        - TgtTypeGroup
        - TgtTypeSite
        - TgtTypeRegion
        - TgtTypeLocation
        - TgtTypeAddHocLocation
        - TgtTypeDepartment
        - TgtTypeRole
        - TgtTypeSip
    service.SubscriberChangeDTO:
      properties:
        depId:
          type: integer
        extension:
          description: used to set phone/extension number for TgtTypeSip
          type: string
        grpId:
          type: integer
        locId:
          type: integer
        regionId:
          type: integer
        roleId:
          type: integer
        siteId:
          type: integer
        subscribe:
          type: boolean
        tgtId:
          description: deprecated
          type: integer
        tgtName:
          description: deprecated
          type: string
        tgtPerm:
          description: 'optional permissions (default: ''rw'')'
          type: string
        tgtType:
          allOf:
            - $ref: '#/components/schemas/model.TargetType'
          description: deprecated
          format: int16
        userId:
          type: integer
      type: object
    GroupResponse:
      properties:
        details:
          type: string
        statusCode:
          type: integer
      type: object
    GetExternalGroupDTO:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        site_name:
          type: string
        targets:
          type: array
          items:
            $ref: '#/components/schemas/ExternalTargetDTO'
    USearchRequest:
      type: object
      required:
        - filter
        - scope
      properties:
        filter:
          type: string
          description: Search query string (non-empty)
        scope:
          type: array
          description: Array of search scope identifiers
          items:
            type: integer
            enum: [1, 2, 3, 4, 5, 6, 7, 8, 9]
            x-enumNames:
              - Broadcast
              - ChatFeeds
              - Tasks
              - Attachments
              - Forums
              - Contacts
              - TaskTags
              - TasksForYou
              - TasksAll
            description: |
              Scope (name -> value):
                Broadcast        = 1
                ChatFeeds        = 2
                Tasks            = 3
                Attachments      = 4
                Forums           = 5
                Contacts         = 6
                TaskTags         = 7
                TasksForYou      = 8
                TasksAll         = 9
        limit:
          type: integer
          description: Max results (default 3, max 50)
          minimum: 3
          maximum: 50
    USearchResponse:
      type: object
      properties:
        results:
          type: array
          description: Array of scope-wise results
          items:
            $ref: '#/components/schemas/ScopeResult'
    ScopeResult:
      type: object
      properties:
        scope:
          type: integer
          description: Scope identifier
        data:
          description: Scope-specific data (structure varies by scope)
        error:
          type: string
          description: Error message if this scope failed
    ValidationError:
      type: object
      properties:
        field:
          type: string
        message:
          type: string

tags:
  - name: Assistant
    description: Assistant/Help request operations
  - name: U-Search
    description: Universal search operations
  - name: User Forums
    description: Forum operations for users
  - name: User Groups
    description: Group management operations
  - name: User Location
    description: Location tracking and access point operations
  - name: User Messages
    description: Messaging operations
  - name: User Presence
    description: User presence and status operations