openapi: 3.0.0
info:
  title: Mentions
  description: |
    <p>
      In Zoho Cliq, you can use mentions (by using @) to tag users and send notifications, even in muted channels. These mentions will appear in the "@" tab at the top of the bar.
      <br>
      When you include a mention in a message, it not only notifies the person or group referenced but also highlights it in the conversation. 
      <br><br> 
      To include different types of content, use the <code>slides</code> key. Any content you want to attach should be placed within the <code>slides</code> JSON object. The <code>slides</code> key is a JSON array that lets you include various textual and visual message payloads.
      <br><br> 
      You can use mentions to:
      <ul>
       <li>Notify a specific user.</li>
       <li>Reference a channel.</li>
       <li>Mention a team.</li>
       <li>Notify all participants in a channel using <b>@all</b>.</li>
       <li>Notify only available participants using <b>@available</b>.</li>
      </ul>
      Additionally, you can view the last 30 days of mentions in a dedicated tab.<br><br>
      Note: Message delivery will fail if the authenticated user does not have permission to use restricted mentions like <b>@all</b> or <b>@available</b> in the specified channel.
    </p>
  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: mentions
    description: Mentions Module
paths:
  /chats/{CHAT_ID}/message:
    post:
      summary: Mentioning a User
      operationId: mentioningUser
      description: |
        To mention a user, use the syntax <b>{@zohoid}</b> or <b>{@email}</b>.<br><br>
        When you mention a user in any team-level or organization-level channel, the user will be notified. This syntax applies only to the <code>text</code> and <code>comments</code> fields of the payload.
      parameters:
        - name: CHAT_ID
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: Unique identifier of the chat where the message needs to be sent To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
      requestBody:
        required: true
        content:
          application/json:
            examples:
              userid:
                summary: User mention with userID
                value:
                  text: Hey there {@userid}, please review the latest project updates
              email:
                summary: User mention with user email
                value:
                  text: Hey there {@scott.fisher@zylker.com}, please review the latest project updates
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                  description: |
                    The text content of the message to be sent.<br>
                    <b>Maximum length</b>: 10,000 characters.
                  maxLength: 10000
                  example: Hi Team! Please find the sales performance chart for this quarter.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-response'
        '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.Webhooks.CREATE
      tags:
        - mentions
  /chats/{CHAT_ID1}/message:
    post:
      summary: Silent mentions
      x-display-path: /chats/{CHAT_ID}/message
      x-virtual-endpoint: true
      x-note: |
        CHAT_ID1 is a documentation alias for CHAT_ID path parameter used in silentMentions operation. This alias is used to document the silent mention use case separately while keeping it under the same POST /chats/{CHAT_ID}/message endpoint, because the actual API path does not change and only the message text syntax differs. The actual endpoint for silentMentions operation remains /chats/{CHAT_ID}/message as specified in the paths object.
      operationId: silentMentions
      description: |
        Silent mentions allow you to reference a user in a conversation without triggering a notification.<br><br>
        Use the syntax <code>[User Name](zohoid:userid)</code> or <code>[User Name](mail:user_email)</code> to mention a user silently in any conversation. This will not notify the user. This format can also be used to mention a user in fields other than the <code>text</code> and <code>comments</code> keys.
      parameters:
        - name: CHAT_ID1
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: |
            Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
            <b>Note:</b> <code>CHAT_ID1</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Silent mentions" use case separately while sharing the same <code>/chats/{CHAT_ID}/message</code> endpoint, since the path is unchanged and only the message text syntax differs.
      requestBody:
        required: true
        content:
          application/json:
            examples:
              userid:
                summary: Silent mention with userID
                value:
                  text: Hey there [Scott Fisher](zohoid:873421), could you check the campaign details when you get a chance?
              email:
                summary: Silent mention with user email
                value:
                  text: Hey there [Scott Fisher](mail:scott.fisher@zylker.com), could you check the campaign details when you get a chance?
            schema:
              type: object
              required:
                - text
              properties:
                text:
                  type: string
                  description: |
                    The text content of the message to be sent.<br>
                    <b>Maximum length</b>: 10,000 characters.
                  maxLength: 10000
                  example: Hi Team! Please find the sales performance chart for this quarter.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-response'
        '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.Webhooks.CREATE
      tags:
        - mentions
  /chats/{CHAT_ID2}/message:
    post:
      summary: Mentioning a Channel
      x-display-path: /chats/{CHAT_ID}/message
      x-virtual-endpoint: true
      x-note: |
        CHAT_ID2 is a documentation alias for CHAT_ID path parameter used in mentioningChannel operation. This alias is used to document the channel mention use case separately while keeping it under the same POST /chats/{CHAT_ID}/message endpoint, because the actual API path does not change and only the message content pattern differs. The actual endpoint for mentioningChannel operation remains /chats/{CHAT_ID}/message as specified in the paths object.
      operationId: mentioningChannel
      description: |
        To mention a channel, use the syntax <code>{#CHANNEL_ID}</code>.<br><br>
        When you mention a team-level or organization-level channel, all participants of that channel will be notified. Additionally, an informational message will be posted in the channel indicating that it has been mentioned.
      parameters:
        - name: CHAT_ID2
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: |
            Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
            <b>Note:</b> <code>CHAT_ID2</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Mentioning a Channel" use case separately while sharing the same <code>/chats/{CHAT_ID}/message</code> endpoint, since the path is unchanged and only the message content pattern differs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: |
                    The text content of the message to be sent.<br>
                     <b>Maximum length</b>: 10,000 characters.
                  maxLength: 10000
                  example: Please review the latest deployment updates in {#CHANNEL_ID} and share your feedback.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-response'
        '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.Webhooks.CREATE
      tags:
        - mentions
  /chats/{CHAT_ID3}/message:
    post:
      summary: Mentioning all users in a channel
      x-display-path: /chats/{CHAT_ID}/message
      x-virtual-endpoint: true
      x-note: |
        CHAT_ID3 is a documentation alias for CHAT_ID path parameter used in mentioningAllUsers operation. This alias is used to document the mention-all use case separately while keeping it under the same POST /chats/{CHAT_ID}/message endpoint, because the actual API path does not change and only the message content pattern differs. The actual endpoint for mentioningAllUsers operation remains /chats/{CHAT_ID}/message as specified in the paths object.
      operationId: mentioningAllUsers
      description: |
        To mention all users in a channel, use the syntax {@all}.<br>
        This will notify every participant who is a member of the channel.<br>
        <b>Note:</b> The ability to use {@all} depends on the authenticated user's role and channel permissions. If the user does not have permission to mention all participants, the message posting request will fail.
      parameters:
        - name: CHAT_ID3
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: |
            Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
            <b>Note:</b> <code>CHAT_ID3</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Mentioning all users in a channel" use case separately while sharing the same <code>/chats/{CHAT_ID}/message</code> endpoint, since the path is unchanged and only the message content pattern differs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: |
                    The text content of the message to be sent.<br>
                     <b>Maximum length</b>: 10,000 characters.
                  maxLength: 10000
                  example: Attention @all, please review the quarterly sales report and share your inputs before tomorrow’s strategy meeting.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-response'
        '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.Webhooks.CREATE
      tags:
        - mentions
  /chats/{CHAT_ID4}/message:
    post:
      summary: Mentioning available users in a Channel
      x-display-path: /chats/{CHAT_ID}/message
      x-virtual-endpoint: true
      x-note: |
        CHAT_ID4 is a documentation alias for CHAT_ID path parameter used in mentioningAvailableUsers operation. This alias is used to document the available-users mention use case separately while keeping it under the same POST /chats/{CHAT_ID}/message endpoint, because the actual API path does not change and only the message content pattern differs. The actual endpoint for mentioningAvailableUsers operation remains /chats/{CHAT_ID}/message as specified in the paths object.
      operationId: mentioningAvailableUsers
      description: |
        To mention all users who are currently available in a channel, use the syntax {@available}.<br><br>
        This will notify only the participants whose status is set to Available at the time the message is posted.
      parameters:
        - name: CHAT_ID4
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: |
            Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
            <b>Note:</b> <code>CHAT_ID4</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Mentioning available users in a Channel" use case separately while sharing the same <code>/chats/{CHAT_ID}/message</code> endpoint, since the path is unchanged and only the message content pattern differs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: |
                    The text content of the message to be sent.<br>
                     <b>Maximum length</b>: 10,000 characters.
                  maxLength: 10000
                  example: Hello @available, we need immediate assistance with the production issue. Please respond if you can take this up.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-response'
        '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.
  /chats/{CHAT_ID5}/message:
    post:
      summary: Mentioning a Team
      x-display-path: /chats/{CHAT_ID}/message
      x-virtual-endpoint: true
      x-note: |
        CHAT_ID5 is a documentation alias for CHAT_ID path parameter used in mentioningTeam operation. This alias is used to document the team mention use case separately while keeping it under the same POST /chats/{CHAT_ID}/message endpoint, because the actual API path does not change and only the message content pattern differs. The actual endpoint for mentioningTeam operation remains /chats/{CHAT_ID}/message as specified in the paths object.
      operationId: mentioningTeam
      description: |
        To mention a team in a message, use the syntax <code>{@team_id}</code>.<br><br>
        You can mention a team only within team-level or organization-level channels. When a team is mentioned, all members of that team will be notified.
      parameters:
        - name: CHAT_ID5
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: |
            Unique identifier of the chat where the message needs to be sent. To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.<br><br>
            <b>Note:</b> <code>CHAT_ID5</code> is a documentation alias for <code>CHAT_ID</code>, used to document the "Mentioning a Team" use case separately while sharing the same <code>/chats/{CHAT_ID}/message</code> endpoint, since the path is unchanged and only the message content pattern differs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: |
                    The text content of the message to be sent.<br>
                     <b>Maximum length</b>: 10,000 characters.
                  maxLength: 10000
                  example: Hello {@1234567890}, please review the updated deployment plan and share your feedback.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/empty-response'
        '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.Webhooks.CREATE
      tags:
        - mentions
components:
  schemas:
    empty-response:
      type: object
      description: Response returned when there is no content.
      properties:
        Response_Code:
          type: string
          example: 204 No response
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Webhooks.CREATE: Send messages
