openapi: 3.0.0
info:
  title: Widget Map Tickers
  description: |
    Tickers are pointers for the map view. Using tickers, you can track and monitor the movement or location of objects or individuals on a map in real-time. They can be updated instantaneously via REST API, which will be transmitted to users who are actively viewing the map. Live update works on a subscription model where users are updated for 10 minutes counting from the time they open the map view tab. Note: Ticker updates should be stored by the developer to send the updated data in widget response.
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs V2
  url: https://www.zoho.com/cliq/help/restapi/v2/
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: maptickers
    description: Widget Map Tickers Module
paths:
  /widgets/{WIDGET_ID}/maps/{MAP_ID}:
    put:
      summary: Add/Update a ticker
      operationId: addOrUpdateTicker
      description: |
        Use this API to add a new ticker/update a ticker in the map view in widgets. Note : You can get the ticker endpoint from the widget preview page (Profile -> Bots & tools -> Widgets -> Required widget)
      parameters:
        - name: WIDGET_ID
          in: path
          required: true
          description: Unique identifier of the widget To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#WIDGET_ID">WIDGET_ID</a> in the Glossary page.
          schema:
            type: string
        - name: MAP_ID
          in: path
          required: true
          description: Unique identifier of the map within the widget To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#MAP_ID">MAP_ID</a> in the Glossary page.
          schema:
            type: string
        - name: appkey
          in: query
          required: false
          schema:
            type: string
          description: |
            To specify updating a ticker that belongs to a widget bundled by an extension.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TickerObject'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickersResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Applications.UPDATE
      tags:
        - maptickers
    delete:
      summary: Delete a ticker
      operationId: deleteTicker
      description: |
        Use this API to delete an existing ticker in the map view in widgets.
      parameters:
        - name: WIDGET_ID
          in: path
          required: true
          description: Unique identifier of the widget To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#WIDGET_ID">WIDGET_ID</a> in the Glossary page.
          schema:
            type: string
        - name: MAP_ID
          in: path
          required: true
          description: Unique identifier of the map within the widget To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#MAP_ID">MAP_ID</a> in the Glossary page.
          schema:
            type: string
        - name: appkey
          in: query
          required: false
          schema:
            type: string
          description: |
            To specify deleting a ticker that belongs to a widget bundled by an extension.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMapTickerRequest'
      responses:
        '204':
          description: The request was successfully completed with no content returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Applications.DELETE
      tags:
        - maptickers
components:
  schemas:
    NoResponse:
      type: object
      description: Response envelope for successful operations with no payload.
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Operation completed successfully.
    TickerObject:
      type: object
      description: Configuration object representing a single ticker on the map.
      required:
        - title
        - type
        - last_modified_time
        - latitude
        - longitude
      properties:
        title:
          type: string
          maxLength: 20
          description: The display title for the ticker (e.g., vehicle number, location name).
        type:
          type: string
          enum:
            - person
            - bicycle
            - motorcycle
            - car
            - van
            - bus
            - plane
            - office
            - home
          description: |
            Type of ticker representing the object or location being tracked:
            <ul>
              <li><b>person</b>: Represents an individual being tracked.</li>
              <li><b>bicycle</b>: Represents a bicycle.</li>
              <li><b>motorcycle</b>: Represents a motorcycle.</li>
              <li><b>car</b>: Represents a car.</li>
              <li><b>van</b>: Represents a van.</li>
              <li><b>bus</b>: Represents a bus.</li>
              <li><b>plane</b>: Represents an aircraft.</li>
              <li><b>office</b>: Represents a fixed office location.</li>
              <li><b>home</b>: Represents a home location.</li>
            </ul>
        last_modified_time:
          type: integer
          format: int64
          description: Epoch timestamp in milliseconds representing the last time the ticker was updated.
        info:
          type: string
          maxLength: 30
          description: Optional additional information about the ticker.
        latitude:
          type: number
          format: double
          description: Latitude coordinate of the ticker location.
        longitude:
          type: number
          format: double
          description: Longitude coordinate of the ticker location.
      example:
        title: TN 07 AL 9916
        type: van
        info: Towards Zoho Corporation
        last_modified_time: 1721329461000
        latitude: 12.84567
        longitude: 80.06092
    MapTickerRequest:
      type: object
      description: Request body for adding or updating one or more tickers on the map.
      properties:
        tickers:
          type: object
          description: |
            A key-value object representing one or more tickers to be displayed on the map. Each key is a unique identifier (e.g., city name or location tag), and the value is the ticker configuration.
          properties: {}
          additionalProperties:
            $ref: '#/components/schemas/TickerObject'
      example:
        tickers:
          chennai:
            title: TN 07 AL 9916
            type: van
            info: Towards Zoho Corporation
            last_modified_time: 1721329461000
            latitude: 12.84567
            longitude: 80.06092
          mumbai:
            title: Zylker Office
            type: office
            info: Mumbai HQ
            last_modified_time: 1721329462000
            latitude: 19.076
            longitude: 72.8777
    TickersResponse:
      type: object
      description: Response containing details of tickers currently displayed on the map.
      properties: {}
      additionalProperties:
        $ref: '#/components/schemas/TickerObject'
      example:
        chennai:
          title: TN 07 AL 9916
          type: van
          last_modified_time: 1721329461000
          latitude: 12.84567
          longitude: 80.06092
          info: Towards Zoho Corporation
        mumbai:
          title: Zylker Office
          type: office
          last_modified_time: 1721329462000
          latitude: 19.076
          longitude: 72.8777
          info: Mumbai HQ
    DeleteMapTickerRequest:
      type: object
      description: Request to delete one or more tickers from the map.
      required:
        - ids
      properties:
        ids:
          type: array
          description: List of ticker IDs or keys that should be removed from the map.
          items:
            type: string
            description: A unique ticker ID or key to remove from the map.
      example:
        ids:
          - chennai
          - mumbai
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Applications.UPDATE: Update Application Info
            ZohoCliq.Applications.DELETE: Delete Application Info
