openapi: 3.0.0
info:
  title: Scheduled Messages
  description: |
    Scheduled messages are automatically sent to conversations at preferred times or based on user statuses such as available, checked in, or after a call ends.
    Use these APIs to create, update, and retrieve scheduled messages.
  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: scheduledmessages
    description: Scheduled Messages Module
paths:
  /chats/{CHAT_ID}/scheduledmessages:
    post:
      summary: Send a scheduled message
      operationId: sendScheduledMessage
      description: |
        Use this API to schedule a message for delivery at a future date and time.
        Threshold limit: 50 requests per minute per user. Lock period: 10 minutes.
      parameters:
        - name: CHAT_ID
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: The ID of the chat in which the message needs to be scheduled 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:
            schema:
              $ref: '#/components/schemas/ScheduledMessageRequest'
            examples:
              scheduleWithTime:
                summary: Schedule with specific time
                value:
                  text: Hello Ryan! Please provide an update on last month's sales!
                  schedule_time: 20250211T090000
                  schedule_timezone: America/New_York
              scheduleWithStatus:
                summary: Schedule with user status
                value:
                  text: Hello Ryan! Please provide an update on last month's sales!
                  schedule_status: user_available
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledMessageDetailsResponse'
              example:
                time_string: 20250211T114500
                creator: '697322516'
                message:
                  ctype: 8
                  channelData:
                    dn: '#Tickets'
                    cn: '#Tickets'
                  mtype: 12
                  msg: Hello Ryan! Please provide an update on last month's sales!
                  dname: Priya Raman
                  temp_info:
                    api: true
                    bm: 1
                  sender: '697322516'
                  language_detection_version: 4
                  detected_language: en
                  includesenderinunread: true
                  chid: CT_2243208015547740304_631836344
                  meta:
                    revision: 2
                  sync_message: false
                created_time: 1739182862958
                timezone: Asia/Kolkata
                time: 1739254500000
                id: 55741379-fddf-476c-8093-c3e05bdf9006
        '400':
          description: Bad Request. Malformed or missing parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized. Invalid AuthToken.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden. Insufficient permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Invalid URL or resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '406':
          description: Not Acceptable. Unsupported response type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - Cliq_Auth:
            - ZohoCliq.messages.CREATE
      tags:
        - scheduledmessages
  /scheduledmessages:
    get:
      summary: Get the list of scheduled messages
      operationId: getScheduledMessages
      description: |
        Use this API to retrieve the list of all scheduled messages.
        Threshold limit: 20 requests per minute per user. Lock period: 10 minutes.
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledMessagesListResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - Cliq_Auth:
            - ZohoCliq.messages.READ
      tags:
        - scheduledmessages
  /chats/{CHAT_ID}/scheduledmessages/{SCHEDULED_MESSAGE_ID}:
    put:
      summary: Update a scheduled message
      operationId: updateScheduledMessage
      description: |
        Use this API to update the content or scheduled time of an existing scheduled message.
        Threshold limit: 20 requests per minute per user. Lock period: 10 minutes.
      parameters:
        - name: CHAT_ID
          in: path
          required: true
          schema:
            type: string
          example: CHAT_ID
          description: The ID of the chat in which the message is scheduled To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
        - name: SCHEDULED_MESSAGE_ID
          in: path
          required: true
          schema:
            type: string
          example: SCHEDULED_MESSAGE_ID
          description: Unique identifier of the scheduled message To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#SCHEDULED_MESSAGE_ID">SCHEDULED_MESSAGE_ID</a> in the Glossary page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduledMessageRequest'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledMessageDetailsResponse'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      security:
        - Cliq_Auth:
            - ZohoCliq.messages.UPDATE
      tags:
        - scheduledmessages
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        message:
          type: string
          example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
    ScheduledMessageRequest:
      type: object
      description: |
        Request body for scheduling a message.
        <br><code>text</code> is mandatory. Either <code>schedule_time</code> or <code>schedule_status</code> must be provided.
      required:
        - text
      properties:
        text:
          type: string
          description: The text to be sent as a scheduled message.
          maxLength: 4096
          example: Hello Ryan! Please provide an update on last month's sales!
        schedule_time:
          type: string
          description: |
            The scheduled execution time of the message.<br>
            <br>Used in: <b>Schedule with specific time</b><br>
            Allowed format: <b>yyyyMMddTHHmmss</b>
            <ul>
              <li>yyyyMMdd - 2025-02-11 (Year:2025, Month:02, Day:11)</li>
              <li>T - Separator indicating the start of the time component</li>
              <li>HHmmss - 09:00:00 (Hour:09, Minute:00, Second:00)</li>
            </ul>
          example: 20250211T090000
        schedule_status:
          type: string
          description: |
            The user status that triggers the message to be sent.<br>
            <br><b>Used in</b>: Schedule with user status<br>
            The message will be sent when the user status matches the provided value.<br>
            <b>Allowed values</b>:
            <ul>
              <li><b>check_in</b> - Message will be sent when the user checks in to work.</li>
              <li><b>user_available</b> - Message will be sent when the user becomes available.</li>
              <li><b>call_end</b> - Message will be sent when a call involving the user ends.</li>
              <li><b>check_out</b> - Message will be sent when the user checks out from work.</li>
            </ul>
          enum:
            - check_in
            - user_available
            - call_end
            - check_out
          example: user_available
        schedule_timezone:
          type: string
          description: |
            Timezone of the scheduled time.<br>
            <br><b>Used in</b>: Schedule with specific time<br>
            Eg: Asia/Kolkata
          example: Asia/Kolkata
    ScheduledMessageDetailsResponse:
      type: object
      description: Details of a scheduled message.
      properties:
        id:
          type: string
          example: 55741379-fddf-476c-8093-c3e05bdf9006
        creator:
          type: string
          example: '697322516'
        created_time:
          type: integer
          format: int64
          example: 1739182862958
        timezone:
          type: string
          example: Asia/Kolkata
        time:
          type: integer
          format: int64
          example: 1739254500000
        message:
          type: object
          properties:
            msg:
              type: string
              example: Hello Ryan! Please provide an update on last month's sales!
            sender:
              type: string
              example: '697322516'
    ScheduledMessageSummary:
      type: object
      properties:
        chat_id:
          type: string
          example: CT_2684315214835428158_697322516
        creator:
          type: string
          example: '697322516'
        created_time:
          type: integer
          format: int64
          example: 1740456316369
        scheduled_time:
          type: integer
          format: int64
          example: 1740556970477
        id:
          type: integer
          format: int64
          example: 4000000131002
    ScheduledMessagesListResponse:
      type: object
      properties:
        url:
          type: string
          example: /v2/chats/2684315214835428158/scheduledmessages
        next_token:
          type: string
          example: es_cXsdfasdeiwlal
        type:
          type: string
          example: scheduledmessages
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledMessageSummary'
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.messages.CREATE: Create Messages
            ZohoCliq.messages.READ: Read Messages
            ZohoCliq.messages.UPDATE: Update Messages
