Skip to content

GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.

222 KB
Raw Blame
openapi: "3.0.0"
info:
  title: WhatsApp API MultiDevice
  version: "9.7.0"
  description: |
    This API is used for sending whatsapp via API.

    The web dashboard is a separate project (gowa-ui); the server downloads its
    latest release asset and serves it at `/` (or returns a JSON banner when
    APP_UI_ENABLED=false).

    Device scoping:
    - Send `X-Device-Id` on all device-scoped REST calls.
    - WebSocket: connect to `/ws?device_id=<id>`.
    - WebSocket auth (when basic auth is enabled): browsers cannot set an
      Authorization header on WebSocket connections, so also pass
      `&authorization=<base64(user:pass)>` in the query string. Use TLS in
      production since the credential is visible in the URL.
servers:
  - url: http://localhost:3000
tags:
  - name: app
    description: Initial Connection to Whatsapp server
  - name: device
    description: Device management for multi-device support
  - name: user
    description: Getting information
  - name: send
    description: Send Message (Text/Image/File/Video).
  - name: message
    description: Message manipulation (revoke/react/update).
  - name: call
    description: Call management (reject incoming calls)
  - name: chat
    description: Chat conversations and messaging
  - name: group
    description: Group setting
  - name: newsletter
    description: newsletter setting
  - name: chatwoot
    description: Chatwoot integration for customer support
security:
  - basicAuth: []

paths:
  /health:
    get:
      operationId: health
      tags:
        - app
      summary: Health check
      description: Public health probe registered at `/health`; it is not prefixed by `APP_BASE_PATH`.
      security: []
      responses:
        '200':
          description: Service healthy
          content:
            text/plain:
              schema:
                type: string
                example: OK
        '503':
          description: Service unavailable
          content:
            text/plain:
              schema:
                type: string
                example: Service Unavailable
  /app/login:
    get:
      operationId: appLogin
      tags:
        - app
      summary: Login to whatsapp server
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/login-with-code:
    get:
      operationId: appLoginWithCode
      tags:
        - app
      summary: Login with pairing code
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: phone
          in: query
          schema:
            type: string
          example: '628912344551'
          description: Your phone number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginWithCodeResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/passkey:
    get:
      operationId: appPasskeyStatus
      tags:
        - app
      summary: Get pending passkey pairing state
      description: >
        Passkey pairing is initiated from the phone during QR login. When the phone requests it,
        the server sends a WebAuthn challenge which is stored here (also broadcast over the
        websocket as PASSKEY_REQUEST) until a response is submitted.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasskeyStatusResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/passkey/response:
    post:
      operationId: appPasskeyResponse
      tags:
        - app
      summary: Submit the WebAuthn assertion for passkey pairing
      description: >
        Send the WebAuthn assertion produced for the pending challenge (see GET /app/passkey).
        The assertion must be produced by an authenticator holding the WhatsApp account's passkey,
        against WhatsApp's relying-party ID; the payload format matches PublicKeyCredential.toJSON().
        If the assertion is submitted within the 5-minute handoff window, pairing is confirmed
        automatically; otherwise a confirmation code is issued (PASSKEY_CONFIRMATION websocket event)
        and must be confirmed via POST /app/passkey/confirm.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebAuthnAssertion'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/passkey/confirm:
    post:
      operationId: appPasskeyConfirm
      tags:
        - app
      summary: Confirm the passkey pairing code
      description: >
        Confirms that the pairing code from the PASSKEY_CONFIRMATION event was shown to the user
        and matches the code displayed on the phone. Only needed when skip_handoff_ux is false.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/logout:
    get:
      operationId: appLogout
      tags:
        - app
      summary: Logout the active device (keeps the device slot)
      description: >-
        Logs the active device out of WhatsApp and clears its session. The device
        slot (id and display name) is kept, so it stays listed (disconnected) and
        can be re-paired under the same id. Use DELETE /devices/{device_id} to remove the slot.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/reconnect:
    get:
      operationId: appReconnect
      tags:
        - app
      summary: Reconnecting to whatsapp server
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/devices:
    get:
      operationId: appDevices
      tags:
        - app
      summary: Get list connected devices
      description: >
        Returns all device IDs known to the server, including placeholders
        created via the device API. Devices are now persisted in the storage
        registry so IDs remain stable after application restarts.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/status:
    get:
      operationId: appStatus
      tags:
        - app
      summary: Get connection status
      description: Check whether the WhatsApp client is connected and logged in
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Connection status retrieved
                  results:
                    type: object
                    properties:
                      is_connected:
                        type: boolean
                        description: Whether the device is connected to WhatsApp servers
                      is_logged_in:
                        type: boolean
                        description: Whether the device is logged in to WhatsApp
                      device_id:
                        type: string
                        description: Session ID registered via POST /devices
                        example: 'org_2'
                      jid:
                        type: string
                        description: WhatsApp JID of the logged-in account (empty until login)
                        example: '[email protected]'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /app/metrics:
    get:
      operationId: appMetrics
      tags:
        - app
      summary: Get server health metrics
      description: >
        Memory of the process and of its container (cgroup v2, then v1), CPU
        time, size of statics/media and storages (walk cached for a minute),
        free space on the volume, the session store and how many devices are
        registered, logged in and connected. Requires no device. Nullable fields
        are unknown on the current platform (non-Linux) or unlimited (container
        memory limit). Folder usage is best effort: missing or unreadable entries
        are omitted, and symlink targets are not traversed. Container metrics use
        the standard /sys/fs/cgroup mount and are null when unavailable. Uptime
        includes process initialization.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: integer, example: 200 }
                  code: { type: string, example: SUCCESS }
                  message: { type: string, example: Fetch app metrics success }
                  results:
                    type: object
                    properties:
                      version: { type: string, example: v9.6.0 }
                      session_store: { type: string, enum: [sqlite, postgres] }
                      devices:
                        type: object
                        properties:
                          total: { type: integer, example: 5 }
                          logged_in: { type: integer, example: 3 }
                          connected: { type: integer, example: 3 }
                      system:
                        type: object
                        properties:
                          started_at: { type: string, format: date-time }
                          uptime_seconds: { type: integer, example: 3600 }
                          go_version: { type: string, example: go1.26.9 }
                          cpu_seconds: { type: number, nullable: true, example: 17.9 }
                          memory:
                            type: object
                            properties:
                              heap_alloc_bytes: { type: integer, format: int64 }
                              runtime_sys_bytes: { type: integer, format: int64 }
                              process_rss_bytes: { type: integer, format: int64, nullable: true }
                              container_bytes: { type: integer, format: int64, nullable: true }
                              container_limit_bytes: { type: integer, format: int64, nullable: true }
                              goroutines: { type: integer }
                              gc_cycles: { type: integer }
                          folders:
                            type: object
                            additionalProperties:
                              type: object
                              properties:
                                bytes: { type: integer, format: int64 }
                                files: { type: integer, format: int64 }
                          filesystem:
                            type: object
                            properties:
                              total_bytes: { type: integer, format: int64, nullable: true }
                              free_bytes: { type: integer, format: int64, nullable: true }
  /app/info:
    get:
      operationId: appInfo
      tags:
        - app
      summary: Get server metadata
      description: >
        Returns server version, base path, media size limits, and enabled
        features. Requires no device; intended for standalone UIs (gowa-ui)
        that previously read these values from the embedded dashboard HTML.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Fetch app info success
                  results:
                    type: object
                    properties:
                      version:
                        type: string
                        example: 'v9.0.0'
                      os:
                        type: string
                        example: 'GOWA'
                      base_path:
                        type: string
                        example: ''
                      max_file_size:
                        type: integer
                        format: int64
                        description: Max document upload size in bytes
                        example: 50000000
                      max_video_size:
                        type: integer
                        format: int64
                        description: Max video upload size in bytes
                        example: 100000000
                      max_image_size:
                        type: integer
                        format: int64
                        description: Max image upload size in bytes
                        example: 20000000
                      chatwoot_enabled:
                        type: boolean
                        description: Whether Chatwoot integration routes are registered
                      scheduled_sends:
                        type: boolean
                        description: Whether send endpoints accept schedule fields and the /send/schedules routes exist
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  # Device Management API (v8)
  /devices:
    get:
      operationId: listDevices
      tags:
        - device
      summary: List all devices
      description: Returns all registered devices with their connection status
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceListResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    post:
      operationId: addDevice
      tags:
        - device
      summary: Add a new device
      description: Create a new device slot for multi-device management
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device_id:
                  type: string
                  description: Optional custom device ID. If not provided, one will be generated.
                  example: 'my-custom-device-id'
                webhook_url:
                  type: string
                  description: Optional device-specific webhook URL. If set, events for this device will be sent here instead of the global webhook.
                  example: 'https://device-webhook.example.com/handler'
                webhook_secret:
                  type: string
                  description: Optional secret used to sign device-specific webhook payloads (HMAC).
                  example: 'super-secret-key'
                webhook_events:
                  type: string
                  description: Optional comma-separated list of event names to forward to the device-specific webhook. Empty means all events.
                  example: 'message,message.ack'
                webhook_insecure_skip_verify:
                  type: boolean
                  description: Optional. Skip TLS certificate verification when delivering to the device-specific webhook.
                  example: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAddResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}:
    get:
      operationId: getDevice
      tags:
        - device
      summary: Get device info
      description: Get detailed information about a specific device
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceInfoResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    delete:
      operationId: removeDevice
      tags:
        - device
      summary: Remove a device
      description: >-
        Remove a device slot from the server. This also logs it out of WhatsApp and
        clears its session and chat data. To log out while keeping the slot, use the
        logout endpoint instead.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}/login:
    get:
      operationId: loginDevice
      tags:
        - device
      summary: Login a device with QR code
      description: >-
        Start QR pairing for a specific device slot and return a link to the QR
        image to scan. Equivalent to `GET /app/login` with
        `X-Device-Id: <device_id>`, with the device taken from the path instead.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceLoginResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}/login/code:
    post:
      operationId: loginDeviceWithCode
      tags:
        - device
      summary: Login a device with pairing code
      description: >-
        Start pairing-code login for a specific device slot and return the code to
        enter on the phone. Equivalent to `GET /app/login-with-code` with
        `X-Device-Id: <device_id>`, with the device taken from the path instead.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
        - name: phone
          in: query
          required: true
          schema:
            type: string
          example: '628912344551'
          description: Phone number to pair with
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceLoginWithCodeResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}/logout:
    post:
      operationId: logoutDevice
      tags:
        - device
      summary: Logout device
      description: >-
        Logs a specific device out of WhatsApp and clears its session, but keeps the
        device slot (id and display name) so it can be re-paired under the same id.
        To remove the slot entirely, use DELETE /devices/{device_id}.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}/reconnect:
    post:
      operationId: reconnectDevice
      tags:
        - device
      summary: Reconnect device
      description: Reconnect a specific device to WhatsApp
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}/status:
    get:
      operationId: getDeviceStatus
      tags:
        - device
      summary: Get device connection status
      description: Get the current connection status of a specific device
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceStatusResponse'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /devices/{device_id}/webhook:
    get:
      operationId: getDeviceWebhook
      tags:
        - device
      summary: Get device webhook configuration
      description: Get the webhook configuration for a specific device. Returns empty values if no device-specific webhook is set.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Device webhook retrieved
                  results:
                    type: object
                    properties:
                      device_id:
                        type: string
                        description: The device ID
                        example: 'my-device'
                      webhook_url:
                        type: string
                        description: The configured webhook URL (empty if not set)
                        example: 'https://example.com/webhook'
                      webhook_secret:
                        type: string
                        description: Secret used to sign payloads for this device webhook
                        example: 'super-secret-key'
                      webhook_events:
                        type: string
                        description: Comma-separated event whitelist for this device webhook
                        example: 'message,message.ack'
                      webhook_insecure_skip_verify:
                        type: boolean
                        description: Whether TLS verification is skipped for this device webhook
                        example: false
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    patch:
      operationId: updateDeviceWebhook
      tags:
        - device
      summary: Set device webhook configuration
      description: |
        Set a custom webhook configuration for a specific device. When set, webhook events for this device
        will be sent to this URL instead of the global webhook URL. Device-level `webhook_secret`,
        `webhook_events`, and `webhook_insecure_skip_verify` override the global webhook settings for this device.

        Set to empty string to clear and use the global webhook.
      parameters:
        - name: device_id
          in: path
          required: true
          schema:
            type: string
          description: Device ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type: string
                  description: Custom webhook URL to use for this device. Set to empty string to clear.
                  example: 'https://example.com/webhook'
                webhook_secret:
                  type: string
                  description: Optional secret used to sign payloads for this device webhook.
                  example: 'super-secret-key'
                webhook_events:
                  type: string
                  description: Optional comma-separated event whitelist for this device webhook. Empty means all events.
                  example: 'message,message.ack'
                webhook_insecure_skip_verify:
                  type: boolean
                  description: Optional. Skip TLS certificate verification for this device webhook.
                  example: false
              required:
                - webhook_url
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Device webhook updated
                  results:
                    type: object
                    properties:
                      device_id:
                        type: string
                        description: The device ID
                        example: 'my-device'
                      webhook_url:
                        type: string
                        description: The configured webhook URL
                        example: 'https://example.com/webhook'
                      webhook_secret:
                        type: string
                        description: Secret used to sign payloads for this device webhook
                        example: 'super-secret-key'
                      webhook_events:
                        type: string
                        description: Comma-separated event whitelist for this device webhook
                        example: 'message,message.ack'
                      webhook_insecure_skip_verify:
                        type: boolean
                        description: Whether TLS verification is skipped for this device webhook
                        example: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /user/presence/subscribe:
    post:
      operationId: userSubscribePresence
      tags:
        - user
      summary: Subscribe to contact presence
      description: |
        Subscribe the selected logged-in device to an individual contact's online/offline updates.
        Updates arrive through presence webhooks. For continuous tracking, set
        WHATSAPP_PRESENCE_ON_CONNECT=available and WHATSAPP_PRESENCE_PULSE_ENABLED=false.
        Keeping the device available suppresses phone push notifications.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phone
              properties:
                phone:
                  type: string
                  description: Individual contact phone number with country code
                  example: '6289685028129'
      responses:
        '200':
          description: Subscription accepted. This does not guarantee contact presence delivery.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Success subscribe to user presence
                  results:
                    type: object
                    properties:
                      subscribed:
                        type: boolean
                        example: true
                      jid:
                        type: string
                        example: '[email protected]'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/info:
    get:
      operationId: userInfo
      tags:
        - user
      summary: User Info
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: phone
          in: query
          schema:
            type: string
          example: '[email protected]'
          description: Phone number with country code
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/avatar:
    get:
      operationId: userAvatar
      tags:
        - user
      summary: User Avatar
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: phone
          in: query
          schema:
            type: string
          example: '[email protected]'
          description: Phone number with country code
        - name: is_preview
          in: query
          schema:
            type: boolean
          example: true
          description: Whether to fetch a preview of the avatar
        - name: is_community
          in: query
          schema:
            type: boolean
          example: false
          description: Whether to fetch a community avatar
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAvatarResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '403':
          description: 'AVATAR_HIDDEN: the contact hides the picture from this account (says nothing about whether one exists)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorForbidden'
              example:
                code: AVATAR_HIDDEN
                message: the user has hidden their profile picture from you
        '404':
          description: 'The contact has no profile picture (AVATAR_NOT_SET) or the device is unknown (DEVICE_NOT_FOUND). Check `code`, not only the status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
              examples:
                avatarNotSet:
                  summary: The contact has no profile picture
                  value:
                    code: AVATAR_NOT_SET
                    message: that user or group does not have a profile picture
                deviceNotFound:
                  summary: Unknown device
                  value:
                    code: DEVICE_NOT_FOUND
                    message: device not found; create a device first from /api/devices or provide a valid X-Device-Id
                    results:
                      device_id: my-device
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    post:
      operationId: userChangeAvatar
      tags:
        - user
      summary: User Change Avatar
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                avatar:
                  type: string
                  format: binary
                  description: Avatar to send
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/pushname:
    post:
      operationId: userChangePushName
      tags:
        - user
      summary: User Change Push Name
      description: Update the display name (push name) shown to others in WhatsApp
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                push_name:
                  type: string
                  example: 'John Doe'
                  description: The new display name to set
              required:
                - push_name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/my/privacy:
    get:
      operationId: userMyPrivacy
      tags:
        - user
      summary: User My Privacy Setting
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPrivacyResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/my/groups:
    get:
      operationId: userMyGroups
      tags:
        - user
      summary: User My List Groups
      description: |
        Get all groups that the authenticated user has joined.

        ⚠️ **Known Limitation**: This endpoint returns a maximum of 500 groups due to a WhatsApp protocol limitation.
        The underlying whatsmeow library's `GetJoinedGroups()` function sends a single query to WhatsApp servers,
        which enforces this limit. This is not a bug in this API - it's a constraint imposed by WhatsApp's
        multi-device protocol. Users with more than 500 groups will only receive the first 500 groups.

        For more details, see: https://github.com/tulir/whatsmeow/blob/main/group.go
      externalDocs:
        description: WhatsApp protocol limitation reference (whatsmeow source)
        url: https://github.com/tulir/whatsmeow/blob/main/group.go
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroupResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /user/my/newsletters:
    get:
      operationId: userMyNewsletter
      tags:
        - user
      summary: User My List Groups
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/my/contacts:
    get:
      operationId: userMyContacts
      tags:
        - user
      summary: Get list of user contacts
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyListContactsResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/check:
    get:
      operationId: userCheck
      tags:
        - user
      summary: Check if user is on WhatsApp
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: phone
          in: query
          schema:
            type: string
          example: '628912344551'
          description: Phone number with country code
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCheckResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /user/business-profile:
    get:
      operationId: userBusinessProfile
      tags:
        - user
      summary: Get Business Profile Information
      description: Retrieve detailed business profile information for a WhatsApp business account
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: phone
          in: query
          required: true
          schema:
            type: string
          example: '[email protected]'
          description: Phone number with country code of the business account
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessProfileResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /send/message:
    post:
      operationId: sendMessage
      tags:
        - send
      summary: Send Message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                message:
                  type: string
                  example: selamat malam
                  description: Message to send
                reply_message_id:
                  type: string
                  example: 3EB089B9D6ADD58153C561
                  description: Message ID that you want reply
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
                mentions:
                  type: array
                  items:
                    type: string
                  example: ["628123456789", "@everyone"]
                  description: |
                    List of phone numbers to mention (ghost mentions - no @ required in message text).
                    Use special keyword "@everyone" to mention all group participants.
                allow_reshare:
                  type: boolean
                  example: false
                  description: Show the reshare button to status viewers. Requires `phone` to be `status@broadcast`; GOWA rejects the field for any other recipient.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/image:
    post:
      operationId: sendImage
      tags:
        - send
      summary: Send Image
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                caption:
                  type: string
                  example: selamat malam
                  description: Caption to send
                mentions:
                  type: array
                  items:
                    type: string
                  example: ["628123456789", "@everyone"]
                  description: |
                    List of phone numbers to mention (ghost mentions - no @ required in caption).
                    `@phone` in the caption is also mentioned. Use special keyword "@everyone" to mention all group participants.
                    Send one `mentions` form field per entry.
                reply_message_id:
                  type: string
                  example: 3EB089B9D6ADD58153C561
                  description: Message ID that you want reply
                view_once:
                  type: boolean
                  example: false
                  description: View once
                image:
                  type: string
                  format: binary
                  description: Image to send
                image_url:
                  type: string
                  example: https://example.com/image.jpg
                  description: Image URL to send
                compress:
                  type: boolean
                  example: false
                  description: Compress image
                hd:
                  type: boolean
                  example: true
                  description: Send a high-definition image rendition (maximum edge 2560px). Overrides compress when true.
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                allow_reshare:
                  type: boolean
                  example: false
                  description: Show the reshare button to status viewers. Requires `phone` to be `status@broadcast`; GOWA rejects the field for any other recipient.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/audio:
    post:
      operationId: sendAudio
      tags:
        - send
      summary: Send Audio
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                audio:
                  type: string
                  format: binary
                  description: Audio to send
                audio_url:
                  type: string
                  example: https://example.com/audio.mp3
                  description: Audio URL to send
                ptt:
                  type: boolean
                  example: false
                  description: Send as a WhatsApp voice note. When true, ffmpeg is required to transcode to OGG Opus.
                reply_message_id:
                  type: string
                  example: 3EB089B9D6ADD58153C561
                  description: Message ID that you want reply
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/file:
    post:
      operationId: sendFile
      tags:
        - send
      summary: Send File
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                caption:
                  type: string
                  example: selamat malam
                  description: Caption to send
                mentions:
                  type: array
                  items:
                    type: string
                  example: ["628123456789", "@everyone"]
                  description: |
                    List of phone numbers to mention (ghost mentions - no @ required in caption).
                    `@phone` in the caption is also mentioned. Use special keyword "@everyone" to mention all group participants.
                    Send one `mentions` form field per entry.
                reply_message_id:
                  type: string
                  example: 3EB089B9D6ADD58153C561
                  description: Message ID that you want reply
                file:
                  type: string
                  format: binary
                  description: File to send
                file_url:
                  type: string
                  example: https://example.com/document.pdf
                  description: File URL to download and send
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/sticker:
    post:
      operationId: sendSticker
      tags:
        - send
      summary: Send Sticker
      description: Send sticker with automatic conversion to WebP format
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                sticker:
                  type: string
                  format: binary
                  description: Sticker image file (jpg/jpeg/png/webp/gif)
                sticker_url:
                  type: string
                  example: https://example.com/sticker.png
                  description: URL of sticker image to send
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
                reply_message_id:
                  type: string
                  example: 3EB089B9D6ADD58153C561
                  description: Message ID that you want reply
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded sticker
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/video:
    post:
      operationId: sendVideo
      tags:
        - send
      summary: Send Video
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                caption:
                  type: string
                  example: ini contoh caption video
                  description: Caption to send
                mentions:
                  type: array
                  items:
                    type: string
                  example: ["628123456789", "@everyone"]
                  description: |
                    List of phone numbers to mention (ghost mentions - no @ required in caption).
                    `@phone` in the caption is also mentioned. Use special keyword "@everyone" to mention all group participants.
                    Send one `mentions` form field per entry.
                reply_message_id:
                  type: string
                  example: 3EB089B9D6ADD58153C561
                  description: Message ID that you want reply
                view_once:
                  type: boolean
                  example: false
                  description: View once
                video:
                  type: string
                  format: binary
                  description: Video to send
                video_url:
                  type: string
                  example: https://example.com/sample.mp4
                  description: Video URL to send
                compress:
                  type: boolean
                  example: false
                  description: Compress video
                hd:
                  type: boolean
                  example: true
                  description: Send an H.264 8-bit YUV 4:2:0 high-definition video rendition at CRF 23, capped at 1280x1280 while preserving aspect ratio and avoiding upscaling. Overrides compress when true.
                gif_playback:
                  type: boolean
                  example: false
                  description: Display video as GIF (looping, silent, autoplay)
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                allow_reshare:
                  type: boolean
                  example: false
                  description: Show the reshare button to status viewers. Requires `phone` to be `status@broadcast`; GOWA rejects the field for any other recipient.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/contact:
    post:
      operationId: sendContact
      tags:
        - send
      summary: Send Contact
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                contact_name:
                  type: string
                  example: Aldino Kemal
                  description: Contact name
                contact_phone:
                  type: string
                  example: '6289685024992'
                  description: Contact phone number
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/link:
    post:
      operationId: sendLink
      tags:
        - send
      summary: Send Link
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                link:
                  type: string
                  example: "https://google.com"
                  description: Link to send
                caption:
                  type: string
                  example: 'Halo ini contoh caption'
                  description: Caption to send
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/location:
    post:
      operationId: sendLocation
      tags:
        - send
      summary: Send Location
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                latitude:
                  type: string
                  example: "-7.797068"
                  description: Latitude coordinate
                longitude:
                  type: string
                  example: '110.370529'
                  description: Longitude coordinate
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/poll:
    post:
      operationId: sendPoll
      tags:
        - send
      summary: Send Poll / Vote
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              properties:
                phone:
                  type: string
                  description: The WhatsApp phone number to send the poll to, including the '@s.whatsapp.net' suffix.
                  example: '[email protected]'
                question:
                  type: string
                  description: The question for the poll.
                  example: 'Siapa Nama Avatar The Last Air Bender?'
                options:
                  type: array
                  description: The options for the poll.
                  items:
                    type: string
                  example: [ 'Zuko', 'Aang', 'Katara' ]
                max_answer:
                  type: integer
                  description: The maximum number of answers allowed for the poll.
                  example: 2
                duration:
                  type: integer
                  example: 86400
                  description: "Disappearing message duration in seconds. Allowed values: 0 (no expiry), 86400 (24h), 604800 (7d), 7776000 (90d)."
              required:
                - phone
                - question
                - options
                - max_answer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/presence:
    post:
      operationId: sendPresence
      tags:
        - send
      summary: Send presence status
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The presence type to send
                  enum: [available, unavailable]
                  example: 'available'
                is_forwarded:
                  type: boolean
                  example: false
                  description: Whether this is a forwarded message
              required:
                - type
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/chat-presence:
    post:
      operationId: sendChatPresence
      tags:
        - send
      summary: Send chat presence (typing indicator)
      description: Send typing indicator to start or stop showing that you are composing a message. Presence cannot be scheduled; schedule fields (scheduled_at, timezone, recurrence, ...) are rejected with 400.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                action:
                  type: string
                  enum: [start, stop]
                  example: 'start'
                  description: Action to perform - "start" to begin typing indicator, "stop" to end typing indicator
              required:
                - phone
                - action
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/schedules:
    get:
      operationId: listScheduledSends
      tags:
        - send
      summary: List scheduled sends
      description: >-
        Lists the device's scheduled sends. Upcoming schedules come first
        (soonest next run first), followed by finished ones, newest first.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: status
          in: query
          schema:
            type: string
            enum: [active, running, paused, completed, failed, cancelled]
          description: Only schedules in this status
        - name: search
          in: query
          schema:
            type: string
          description: Match the recipient or the message text
        - name: message_type
          in: query
          schema:
            type: string
            enum: [text, image, file, video, audio, sticker, contact, link, location, poll, forward]
          description: Only this kind of scheduled send
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 100
          description: Maximum number of schedules to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Number of schedules to skip (for pagination)
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleListResponse'
        '400':
          description: Bad Request (e.g. unknown status or message_type, limit or offset out of range)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/schedules/{schedule_id}:
    get:
      operationId: getScheduledSend
      tags:
        - send
      summary: Get a scheduled send
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - $ref: '#/components/parameters/ScheduleIdPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleResponse'
        '404':
          description: Schedule not found for this device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/schedules/{schedule_id}/pause:
    post:
      operationId: pauseScheduledSend
      tags:
        - send
      summary: Pause a scheduled send
      description: Stops an active schedule from sending until it is resumed. Only an active schedule can be paused.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - $ref: '#/components/parameters/ScheduleIdPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request (the schedule is not active)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '404':
          description: Schedule not found for this device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/schedules/{schedule_id}/resume:
    post:
      operationId: resumeScheduledSend
      tags:
        - send
      summary: Resume a paused scheduled send
      description: >-
        Makes a paused schedule active again. Only a paused schedule can be
        resumed. A recurring schedule whose next run passed while paused
        continues at its next slot, or completes if none is left; an overdue
        one-time schedule sends right away.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - $ref: '#/components/parameters/ScheduleIdPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request (the schedule is not paused)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '404':
          description: Schedule not found for this device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /send/schedules/{schedule_id}/cancel:
    post:
      operationId: cancelScheduledSend
      tags:
        - send
      summary: Cancel a scheduled send
      description: >-
        Cancels an active, paused, or failed schedule so it never sends again.
        Its stored media is removed.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - $ref: '#/components/parameters/ScheduleIdPath'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request (the schedule is running, completed, or already cancelled)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '404':
          description: Schedule not found for this device
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/revoke:
    post:
      operationId: revokeMessage
      tags:
        - message
      summary: Revoke Message
      description: |
        Revoke (delete for everyone) a message. Revokes the bot's own message by default.
        If the target message was sent by another user and is present in chat storage,
        the original sender is resolved automatically so a group-admin bot can revoke
        other members' messages (anti-spam use case). The WhatsApp server rejects the
        request if the bot is not a group admin.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/delete:
    post:
      operationId: deleteMessage
      tags:
        - message
      summary: Delete Message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/reaction:
    post:
      operationId: reactMessage
      tags:
        - message
      summary: Send reaction to message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                emoji:
                  type: string
                  example: "🙏"
                  description: Emoji to react
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/update:
    post:
      operationId: updateMessage
      tags:
        - message
      summary: Edit message by message ID before 15 minutes
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
                message:
                  type: string
                  example: 'Hello World'
                  description: New message to send
                link:
                  type: string
                  example: 'https://example.com/page'
                  description: Optional URL. When set, the edit is sent with a rich link preview (title, description, thumbnail) like /send/link. Appended to the message if not already present.
              required:
                - phone
                - message
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/read:
    post:
      operationId: readMessage
      tags:
        - message
      summary: Mark as read message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
              required:
                - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/played:
    post:
      operationId: markMessagePlayed
      tags:
        - message
      summary: Mark an audio message as played
      description: >-
        Sends WhatsApp's played receipt for an incoming audio message or voice
        note. The message must exist in the active device's chat storage and
        belong to the supplied chat.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number or group JID containing the audio message
              required:
                - phone
      responses:
        '200':
          description: Played receipt sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/star:
    post:
      operationId: starMessage
      tags:
        - message
      summary: Star message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
              required:
                - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/unstar:
    post:
      operationId: unstarMessage
      tags:
        - message
      summary: Unstar message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Phone number with country code
              required:
                - phone
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/forward:
    post:
      operationId: forwardMessage
      tags:
        - message
      summary: Forward Message
      description: |
        Forward a message that exists in local chat storage to another chat by message ID.
        Text and standard media types (image, video, video note, audio, document, sticker) are supported.
        Media references are reused when possible; stale refs trigger an automatic re-upload fallback.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Source message ID from chat storage
          example: '3EB0123456789ABCDEF'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              allOf:
                - $ref: '#/components/schemas/ScheduleOptions'
              required:
                - phone
              properties:
                phone:
                  type: string
                  example: '[email protected]'
                  description: Destination phone number or group JID
                duration:
                  type: integer
                  example: 0
                  description: Optional disappearing message duration override (0, 86400, 604800, 7776000)
                force_reupload:
                  type: boolean
                  example: false
                  description: Skip media reference reuse and re-upload media before sending
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /message/{message_id}/download:
    get:
      operationId: downloadMessageMedia
      tags:
        - message
      summary: Download media from message
      description: Download media content (image, video, audio, document) from a message
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: message_id
          schema:
            type: string
          required: true
          description: Message ID
          example: '3EB0123456789ABCDEF'
        - in: query
          name: phone
          schema:
            type: string
          required: true
          description: Phone number with country code
          example: '[email protected]'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Media downloaded successfully
                  results:
                    type: object
                    properties:
                      status:
                        type: string
                        example: Media downloaded successfully
                      message_id:
                        type: string
                        example: 3EB0ABC123456789
                      media_type:
                        type: string
                        example: audio
                      filename:
                        type: string
                        example: audio.ogg
                      file_path:
                        type: string
                        description: Local server file path where the media was saved
                        example: statics/media/6289685028129/2026-06-09/audio.ogg
                      file_url:
                        type: string
                        description: Public URL for downloading the saved media when it is stored under the served statics directory
                        example: http://localhost:3000/statics/media/6289685028129/2026-06-09/audio.ogg
                      file_size:
                        type: integer
                        example: 524288
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '404':
          description: Message or media not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /call/reject:
    post:
      operationId: rejectCall
      tags:
        - call
      summary: Reject an incoming call
      description: |
        Programmatically reject a specific incoming call. This endpoint allows selective call rejection
        based on your application logic (e.g., time-of-day rules, caller whitelists, agent availability).

        The call must still be ringing — rejection will fail if the call has already ended or been answered.

        This is complementary to the auto-reject feature (`WHATSAPP_AUTO_REJECT_CALL=true`) which rejects
        all incoming calls globally. Use this API for fine-grained control.

        **Required fields from webhook:**
        - `caller_jid`: Use `payload.from` from the `call.offer` webhook event
        - `call_id`: Use `payload.call_id` from the `call.offer` webhook event
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - caller_jid
                - call_id
              properties:
                caller_jid:
                  type: string
                  example: '[email protected]'
                  description: JID of the caller (from webhook `payload.from`)
                call_id:
                  type: string
                  example: 'ABC123DEF456'
                  description: Unique call identifier (from webhook `payload.call_id`)
      responses:
        '200':
          description: Call rejected successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request (missing or invalid fields)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error (call already ended, not connected, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /chats:
    get:
      operationId: listChats
      tags:
        - chat
      summary: Get list of chats
      description: Retrieve a list of chat conversations with their basic information
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
            maximum: 100
          description: Maximum number of chats to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Number of chats to skip (for pagination)
        - name: search
          in: query
          schema:
            type: string
          description: Search chats by name
        - name: has_media
          in: query
          schema:
            type: boolean
            default: false
          description: Filter chats that contain media messages
        - name: archived
          in: query
          schema:
            type: boolean
          description: Filter by archived status. true = archived only, false = non-archived only. Omit to return all chats.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
  /chat/{chat_jid}/messages:
    get:
      operationId: getChatMessages
      tags:
        - chat
      summary: Get messages from a specific chat
      description: Retrieve messages from a specific chat conversation with filtering options
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: chat_jid
          schema:
            type: string
          required: true
          description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
          example: '[email protected]'
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Maximum number of messages to return
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Number of messages to skip (for pagination)
        - name: start_time
          in: query
          schema:
            type: string
            format: date-time
          description: Filter messages from this timestamp (ISO 8601 format)
        - name: end_time
          in: query
          schema:
            type: string
            format: date-time
          description: Filter messages until this timestamp (ISO 8601 format)
        - name: media_only
          in: query
          schema:
            type: boolean
            default: false
          description: Only return messages with media content
        - name: is_from_me
          in: query
          schema:
            type: boolean
          description: Filter messages by sender (true for messages sent by you, false for received messages). When both media_only=true and isFromMe=false are provided, media_only takes precedence and will return all media messages regardless of sender.
        - name: search
          in: query
          schema:
            type: string
          description: Search messages by content text
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessagesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Chat Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /chat/{chat_jid}/history:
    post:
      operationId: requestChatHistory
      tags:
        - chat
      summary: Request older chat history from the phone
      description: >-
        Asks the phone for older messages of a chat on demand (what WhatsApp
        Web does when you scroll up / "load older messages"). The request is
        anchored at the oldest message currently stored locally for that
        chat, so the chat must already have at least one stored message. The
        phone answers asynchronously with a history sync event that gets
        persisted into chat storage; this endpoint only confirms the request
        was sent, it does not return the older messages directly.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: chat_jid
          schema:
            type: string
          required: true
          description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
          example: '[email protected]'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                count:
                  type: integer
                  default: 50
                  minimum: 0
                  maximum: 500
                  example: 50
                  description: Number of older messages to request from the phone. Omit it, or send 0, to use the default of 50.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestChatHistoryResponse'
        '400':
          description: Bad Request (e.g. missing chat_jid, count out of range, or chat has no stored messages to anchor on)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /chat/{chat_jid}/pin:
    post:
      operationId: pinChat
      tags:
        - chat
      summary: Pin or unpin a chat
      description: Pin or unpin a chat conversation to the top of the chat list
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: chat_jid
          schema:
            type: string
          required: true
          description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
          example: '[email protected]'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                pinned:
                  type: boolean
                  example: true
                  description: Whether to pin (true) or unpin (false) the chat
              required:
                - pinned
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinChatResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Chat Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /chat/{chat_jid}/disappearing:
    post:
      operationId: setDisappearingTimer
      tags:
        - chat
      summary: Set disappearing messages timer
      description: Set or disable disappearing messages for a chat. Valid timer values are 0 (off), 86400 (24h), 604800 (7d), 7776000 (90d).
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: chat_jid
          schema:
            type: string
          required: true
          description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
          example: '[email protected]'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                timer_seconds:
                  type: integer
                  example: 86400
                  description: 'Timer in seconds: 0 (off), 86400 (24h), 604800 (7d), 7776000 (90d)'
              required:
                - timer_seconds
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetDisappearingTimerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /chat/{chat_jid}/archive:
    post:
      operationId: archiveChat
      tags:
        - chat
      summary: Archive or unarchive a chat
      description: Archive or unarchive a chat conversation. Archived chats are hidden from the main chat list.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - in: path
          name: chat_jid
          schema:
            type: string
          required: true
          description: Chat JID (e.g., [email protected] for individual or [email protected] for group). Percent-encoded values (e.g., groupid%40g.us) are accepted.
          example: '[email protected]'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                archived:
                  type: boolean
                  example: true
                  description: Whether to archive (true) or unarchive (false) the chat
              required:
                - archived
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveChatResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorUnauthorized'
        '404':
          description: Chat Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorNotFound'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /group/info:
    get:
      operationId: groupInfo
      tags:
        - group
      summary: Group Info
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: group_id
          in: query
          schema:
            type: string
          example: '[email protected]'
          description: WhatsApp Group ID
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group:
    post:
      operationId: createGroup
      tags:
        - group
      summary: Create group and add participant
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  example: 'Example Group Title'
                participants:
                  type: array
                  items:
                    type: string
                    example:
                      - '6819241294719274'
                      - '6829241294719274'
                      - '6839241294719274'
                  example:
                    - '6819241294719274'
                    - '6829241294719274'
                    - '6839241294719274'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGroupResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participants:
    get:
      operationId: getGroupParticipants
      tags:
        - group
      summary: Get list of participants in a group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: group_id
          in: query
          required: true
          schema:
            type: string
          example: '[email protected]'
          description: The group ID to fetch participants for
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupParticipantsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    post:
      operationId: addParticipantToGroup
      tags:
        - group
      summary: Adding more participants to group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageParticipantRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManageParticipantResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participants/export:
    get:
      operationId: exportGroupParticipants
      tags:
        - group
      summary: Export group participants as CSV
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: group_id
          in: query
          required: true
          schema:
            type: string
          example: '[email protected]'
          description: The group ID to export participants for
      responses:
        '200':
          description: CSV stream containing the participants list
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participants/remove:
    post:
      operationId: removeParticipantFromGroup
      tags:
        - group
      summary: Remove participants from group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageParticipantRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManageParticipantResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participants/promote:
    post:
      operationId: promoteParticipantToAdmin
      tags:
        - group
      summary: Promote participants to admin
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageParticipantRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManageParticipantResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participants/demote:
    post:
      operationId: demoteParticipantToMember
      tags:
        - group
      summary: Demote participants to member
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageParticipantRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManageParticipantResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/join-with-link:
    post:
      operationId: joinGroupWithLink
      tags:
        - group
      summary: Join group with link
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                link:
                  type: string
                  example: 'https://chat.whatsapp.com/whatsappKeyJoinGroup'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/info-from-link:
    get:
      operationId: getGroupInfoFromLink
      tags:
        - group
      summary: Get group information from invitation link
      description: Retrieve group information without joining the group using its invitation link
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: link
          in: query
          required: true
          schema:
            type: string
          example: 'https://chat.whatsapp.com/whatsappKeyJoinGroup'
          description: WhatsApp group invitation link
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupInfoFromLinkResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participant-requests:
    get:
      operationId: getGroupParticipantRequests
      tags:
        - group
      summary: Get list of participant requests to join group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: group_id
          in: query
          required: true
          schema:
            type: string
          example: '[email protected]'
          description: The group ID to get participant requests for
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupParticipantRequestListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participant-requests/approve:
    post:
      operationId: approveGroupParticipantRequest
      tags:
        - group
      summary: Approve participant request to join group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                participants:
                  type: array
                  items:
                    type: string
                  example: ['6281234567890']
                  description: Array of participant WhatsApp IDs to approve
              required:
                - group_id
                - participants
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/participant-requests/reject:
    post:
      operationId: rejectGroupParticipantRequest
      tags:
        - group
      summary: Reject participant request to join group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                participants:
                  type: array
                  items:
                    type: string
                  example: ['6281234567890']
                  description: Array of participant WhatsApp IDs to reject
              required:
                - group_id
                - participants
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/leave:
    post:
      operationId: leaveGroup
      tags:
        - group
      summary: Leave group
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/photo:
    post:
      operationId: setGroupPhoto
      tags:
        - group
      summary: Set group photo
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                photo:
                  type: string
                  format: binary
                  description: Group photo to upload (JPEG format recommended). Leave empty to remove photo.
              required:
                - group_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetGroupPhotoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/name:
    post:
      operationId: setGroupName
      tags:
        - group
      summary: Set group name
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                name:
                  type: string
                  example: 'New Group Name'
                  description: The new group name (max 25 characters)
                  maxLength: 25
              required:
                - group_id
                - name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/locked:
    post:
      operationId: setGroupLocked
      tags:
        - group
      summary: Set group locked status
      description: Lock/unlock group so only admins can modify group info
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                locked:
                  type: boolean
                  example: true
                  description: Whether to lock the group (true) or unlock it (false)
              required:
                - group_id
                - locked
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/announce:
    post:
      operationId: setGroupAnnounce
      tags:
        - group
      summary: Set group announce mode
      description: Enable/disable announce mode so only admins can send messages
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                announce:
                  type: boolean
                  example: true
                  description: Whether to enable announce mode (true) or disable it (false)
              required:
                - group_id
                - announce
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/topic:
    post:
      operationId: setGroupTopic
      tags:
        - group
      summary: Set group topic
      description: Set or remove group topic/description
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: string
                  example: '[email protected]'
                  description: The group ID
                topic:
                  type: string
                  example: 'Welcome to our group! Please follow the rules.'
                  description: The group topic/description. Leave empty to remove the topic.
              required:
                - group_id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /group/invite-link:
    get:
      operationId: groupInviteLink
      tags:
        - group
      summary: Group Invite Link
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: group_id
          in: query
          schema:
            type: string
          required: true
          description: WhatsApp Group ID
        - name: reset
          in: query
          schema:
            type: boolean
            default: false
          example: false
          description: Reset existing invite link
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetGroupInviteLinkResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /newsletter/follow:
    post:
      operationId: followNewsletter
      tags:
        - newsletter
      summary: Follow newsletter
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [newsletter_id]
              properties:
                newsletter_id:
                  type: string
                  example: '120363024512399999@newsletter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /newsletter/unfollow:
    post:
      operationId: unfollowNewsletter
      tags:
        - newsletter
      summary: Unfollow newsletter
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newsletter_id:
                  type: string
                  example: '120363024512399999@newsletter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /newsletter/info:
    get:
      operationId: getNewsletterInfo
      tags:
        - newsletter
      summary: Get newsletter (channel) metadata
      description: |
        Returns the channel metadata (name, description, subscribers count,
        verification, picture, invite code, state). Provide exactly one of
        `newsletter_id` or `invite`. Neither requires following the channel;
        `viewer_metadata` is null when WhatsApp does not return viewer-specific metadata.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: newsletter_id
          in: query
          required: false
          schema:
            type: string
          example: '120363024512399999@newsletter'
        - name: invite
          in: query
          required: false
          description: Channel invite link (https://whatsapp.com/channel/...) or just the code
          schema:
            type: string
          example: 'https://whatsapp.com/channel/0029Va4K0PZ5a245NkngBA2M'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterInfoResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /newsletter/directory:
    get:
      operationId: searchNewsletterDirectory
      tags:
        - newsletter
      summary: Browse or search the public channel directory
      description: |
        Mirrors the "Find channels" screen of the official clients. Without
        `search_text` it browses a `view` and requires at least one country
        code; with `search_text` it searches channels by name (country codes
        are not supported by the search). Paginate with `cursor` while
        `has_more` is true. Uses undocumented WhatsApp queries captured from
        WhatsApp Web, which may change without notice.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: view
          in: query
          required: false
          schema:
            type: string
            enum: [RECOMMENDED, TRENDING, POPULAR, NEW, FEATURED]
            default: RECOMMENDED
        - name: search_text
          in: query
          required: false
          schema:
            type: string
          example: news
        - name: country_codes
          in: query
          required: false
          description: ISO 3166-1 alpha-2 codes, repeated or comma separated. Required when browsing a view.
          schema:
            type: array
            items:
              type: string
          example: [ID]
        - name: categories
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum: [BUSINESS, ENTERTAINMENT, LIFESTYLE, NEWS, ORGANIZATIONS, PEOPLE, SPORTS]
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 50
        - name: cursor
          in: query
          required: false
          description: next_cursor from the previous page
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterDirectoryResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /newsletter/messages:
    get:
      operationId: getNewsletterMessages
      tags:
        - newsletter
      summary: Get latest newsletter (channel) messages
      description: |
        Fetches the latest messages posted in a newsletter (channel) directly
        from WhatsApp servers. Following the channel is not required. The
        server keeps roughly the last 30 days of posts; `views_count` is only
        reported to channel admins and is 0 otherwise.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: newsletter_id
          in: query
          required: true
          schema:
            type: string
          example: '120363024512399999@newsletter'
        - name: count
          in: query
          required: false
          description: Number of messages to return (default 50, max 100)
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: before
          in: query
          required: false
          description: Fetch messages older than this message server ID, used for pagination
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterMessagesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /newsletter/message-updates:
    get:
      operationId: getNewsletterMessageUpdates
      tags:
        - newsletter
      summary: Get newsletter message counters
      description: |
        Returns only the counters (forwards and reactions per emoji) of the
        messages after `after`, without message content. Cheaper than
        re-fetching messages to refresh engagement. Does not require following.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: newsletter_id
          in: query
          required: true
          schema:
            type: string
          example: '120363024512399999@newsletter'
        - name: after
          in: query
          required: true
          description: Return updates for messages with a server ID greater than this one
          schema:
            type: integer
            minimum: 1
        - name: count
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: since
          in: query
          required: false
          description: Unix timestamp (seconds); only messages updated after it
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterMessagesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
  /newsletter/live-updates:
    get:
      operationId: listNewsletterLiveUpdates
      tags:
        - newsletter
      summary: List live updates subscriptions of the device
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterLiveUpdatesListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    post:
      operationId: subscribeNewsletterLiveUpdates
      tags:
        - newsletter
      summary: Subscribe to newsletter live updates
      description: |
        Subscribes the device to live counter updates of a channel, delivered
        as `newsletter.message` webhooks. WhatsApp grants the subscription for
        a short duration (90 seconds observed); GOWA renews it before it
        expires and after reconnects until it is unsubscribed. Subscriptions
        are kept in memory and do not survive a restart.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [newsletter_id]
              properties:
                newsletter_id:
                  type: string
                  example: '120363024512399999@newsletter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterLiveUpdatesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'
    delete:
      operationId: unsubscribeNewsletterLiveUpdates
      tags:
        - newsletter
      summary: Stop renewing newsletter live updates
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: newsletter_id
          in: query
          required: true
          schema:
            type: string
          example: '120363024512399999@newsletter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /newsletter/messages/{server_id}/download:
    get:
      operationId: downloadNewsletterMessageMedia
      tags:
        - newsletter
      summary: Download media from a newsletter message
      description: |
        Fetches one newsletter message directly from WhatsApp by server ID,
        downloads its media to the server's statics directory, and returns the
        saved file metadata and public URL. Supported media types are images,
        videos, video notes, audio, documents, and stickers.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
        - name: server_id
          in: path
          required: true
          description: Newsletter message server ID returned by GET /newsletter/messages
          schema:
            type: integer
            minimum: 1
          example: 8872
        - name: newsletter_id
          in: query
          required: true
          description: Newsletter JID containing the message
          schema:
            type: string
          example: '120363024512399999@newsletter'
      responses:
        '200':
          description: Media downloaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterMediaDownloadResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Message lookup or media download failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

  /chatwoot/sync:
    post:
      operationId: chatwootSyncHistory
      tags:
        - chatwoot
      summary: Sync message history to Chatwoot
      description: |
        Initiates a background sync of WhatsApp message history to Chatwoot.
        Messages from the configured number of days will be imported.
        This endpoint requires CHATWOOT_ENABLED=true in configuration.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                device_id:
                  type: string
                  description: Device ID to sync (uses CHATWOOT_DEVICE_ID if not specified)
                days_limit:
                  type: integer
                  default: 3
                  description: Number of days of history to sync
                include_media:
                  type: boolean
                  default: true
                  description: Include media attachments in sync
                include_groups:
                  type: boolean
                  default: true
                  description: Include group chats in sync
      responses:
        '200':
          description: Sync initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatwootSyncResponse'
        '400':
          description: Bad Request (device not found or Chatwoot not configured)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '409':
          description: Sync already in progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 409
                  code:
                    type: string
                    example: SYNC_ALREADY_RUNNING
                  message:
                    type: string
                    example: A sync is already in progress for this device
                  results:
                    type: object
                    properties:
                      progress:
                        $ref: '#/components/schemas/ChatwootSyncStatusResponse/properties/results'

  /chatwoot/sync/status:
    get:
      operationId: chatwootSyncStatus
      tags:
        - chatwoot
      summary: Get Chatwoot sync progress
      description: Returns the current sync progress for a device
      parameters:
        - name: device_id
          in: query
          description: Device ID to check sync status for
          schema:
            type: string
      responses:
        '200':
          description: Sync status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatwootSyncStatusResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'

  /chatwoot/webhook:
    post:
      operationId: chatwootWebhook
      tags:
        - chatwoot
      summary: Chatwoot webhook endpoint
      description: |
        Receives webhook events from Chatwoot and sends messages to WhatsApp.
        Configure this URL in your Chatwoot inbox webhook settings.

        When CHATWOOT_WEBHOOK_SECRET is set the request must prove knowledge of
        it. Recommended: Chatwoot's own signature, sent by Chatwoot when the API
        channel has a webhook secret — `X-Chatwoot-Timestamp` (unix seconds) and
        `X-Chatwoot-Signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>">`.
        The timestamp must be within CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE (5m by
        default) of the server clock. Also accepted: `X-Hub-Signature-256`
        (HMAC-SHA256 of the raw body), the secret in `X-Chatwoot-Webhook-Secret`
        or `X-Gowa-Chatwoot-Secret`, or the `secret` query parameter (discouraged:
        the secret then appears in URLs and logs).

        The secret that applies is the secret of the device the payload is
        routed to: that device config's `webhook_secret` when it has one (the
        global secret is then not accepted for it), CHATWOOT_WEBHOOK_SECRET
        otherwise and when no device resolves. A Chatwoot-signed request that
        was already accepted (answered 2xx) inside the tolerance window is
        acknowledged with 200 and not acted on again. One that was answered
        with any other status is not remembered, so sending the identical
        request again is handled.
      parameters:
        - name: X-Chatwoot-Signature
          in: header
          description: 'Chatwoot signature: sha256=<hex HMAC-SHA256 of "<timestamp>.<raw body>" keyed with the webhook secret>'
          schema:
            type: string
        - name: X-Chatwoot-Timestamp
          in: header
          description: Unix time (seconds) the webhook was signed at
          schema:
            type: string
        - name: secret
          in: query
          description: The webhook secret. Discouraged; prefer the signature headers.
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Chatwoot webhook payload (see Chatwoot documentation)
      responses:
        '200':
          description: Webhook processed
        '401':
          description: Secret or signature missing or invalid for the device the request is routed to, or the signature timestamp is outside the tolerance window
        '503':
          description: Device not available, the routed device's config could not be read, or an identical signed request is still being handled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'

  /chatwoot/webhook/{device_id}:
    post:
      operationId: chatwootDeviceWebhook
      tags:
        - chatwoot
      summary: Per-device Chatwoot webhook endpoint
      description: |
        Per-device variant of the Chatwoot webhook: configure each device's Chatwoot
        inbox to POST here (the URL is returned as `webhook_url` by the device config
        endpoints) so agent replies route deterministically to that device.
        Route-by-config: in addition to the optional secret, the payload's
        account and inbox must match the device's stored config or the request is
        rejected with 401. Unknown device ids and non-message events are acknowledged
        with 200 and ignored.
        The request is authenticated like `/chatwoot/webhook`, with the device
        config's `webhook_secret` when it has one and CHATWOOT_WEBHOOK_SECRET
        otherwise.
      parameters:
        - name: device_id
          in: path
          required: true
          description: Device ID (or WhatsApp JID) the webhook is bound to
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Chatwoot webhook payload (see Chatwoot documentation)
      responses:
        '200':
          description: Webhook processed (or acknowledged and ignored)
        '401':
          description: Invalid secret or signature, or payload account/inbox does not match the device's config
        '503':
          description: The device's config could not be read, so the request could not be authenticated, or an identical signed request is still being handled

  /chatwoot/configs:
    get:
      operationId: chatwootListConfigs
      tags:
        - chatwoot
      summary: List per-device Chatwoot configs
      description: Returns every per-device Chatwoot routing config. API tokens are masked.
      responses:
        '200':
          description: Configs retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Chatwoot device configs
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatwootDeviceConfig'

  /devices/{device_id}/chatwoot/config:
    get:
      operationId: chatwootGetDeviceConfig
      tags:
        - chatwoot
      summary: Get a device's Chatwoot config
      description: Returns the per-device Chatwoot routing config (API token masked).
      parameters:
        - $ref: '#/components/parameters/ChatwootConfigDeviceId'
      responses:
        '200':
          description: Config retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Chatwoot device config
                  results:
                    $ref: '#/components/schemas/ChatwootDeviceConfig'
        '404':
          description: Device not found (DEVICE_NOT_FOUND) or no config for this device (CONFIG_NOT_FOUND)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
    put:
      operationId: chatwootUpsertDeviceConfig
      tags:
        - chatwoot
      summary: Create or update a device's Chatwoot config
      description: |
        Routes this device's messages to its own Chatwoot destination (URL + account +
        inbox + token) instead of the global CHATWOOT_* env config.
        The URL is canonicalized and validated (http/https only, no embedded
        credentials, hosts resolving to private/loopback/link-local/metadata addresses
        are rejected unless allowlisted via CHATWOOT_ALLOWED_HOSTS).
        On update, an empty `api_token` — or the masked value echoed back from a GET —
        keeps the stored token. Changing the routing identity (url/account/inbox) is
        rejected with 409 once the config has linked conversations; delete and
        recreate the config to rebind.
      parameters:
        - $ref: '#/components/parameters/ChatwootConfigDeviceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chatwoot_url
                - account_id
                - inbox_id
              properties:
                chatwoot_url:
                  type: string
                  example: 'https://chatwoot.example.com'
                account_id:
                  type: integer
                  example: 1
                inbox_id:
                  type: integer
                  example: 5
                api_token:
                  type: string
                  description: Chatwoot agent/bot API token. Required on create; empty (or the masked value) keeps the stored token on update.
                webhook_secret:
                  type: string
                  description: |
                    Webhook secret of this inbox's API channel. When set it protects every
                    webhook routed to this device (on `/chatwoot/webhook/{device_id}` and on
                    the shared `/chatwoot/webhook`) instead of
                    CHATWOOT_WEBHOOK_SECRET. Omit to keep the stored value; send an empty
                    string to remove it. Never returned by the API.
                enabled:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Config saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Chatwoot device config saved
                  results:
                    $ref: '#/components/schemas/ChatwootDeviceConfig'
        '400':
          description: Invalid request (INVALID_REQUEST) or rejected URL (INVALID_CHATWOOT_URL)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '409':
          description: Routing identity change rejected while linked conversations exist (CONFIG_HAS_LINKED_CONVERSATIONS)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
    delete:
      operationId: chatwootDeleteDeviceConfig
      tags:
        - chatwoot
      summary: Delete a device's Chatwoot config
      description: |
        Removes the device's Chatwoot routing config along with its stored message
        links (stale links would otherwise keep answering reverse lookups for the old
        destination after a rebind).
      parameters:
        - $ref: '#/components/parameters/ChatwootConfigDeviceId'
      responses:
        '200':
          description: Config deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: SUCCESS
                  message:
                    type: string
                    example: Chatwoot device config deleted
                  results:
                    type: object
                    properties:
                      device_id:
                        type: string
                        example: 'my-device-id'

  /send/interactive:
    post:
      operationId: sendInteractive
      tags: [send]
      summary: Send an experimental interactive message
      description: |
        Immediate-only REST send for native-flow buttons, selection lists,
        location requests, and carousels. Not supported by scheduled sends or MCP.
        Uses an unofficial protocol; API success does not guarantee recipient
        rendering or delivery. Accepts individual user or group recipients only.
        Provide either buttons or cards. Overall HTTP body limits also apply.
      parameters:
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InteractiveSendRequest'
            example:
              phone: '628123456789'
              body: Confirm your order?
              buttons:
                - name: quick_reply
                  params:
                    display_text: Confirm
                    id: confirm
      responses:
        '200':
          description: Accepted for send; recipient rendering is unverified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendResponse'
        '400':
          description: Invalid recipient, text, button parameters, or image limits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBadRequest'
        '500':
          description: Device, media upload, or WhatsApp send failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInternalServer'

components:
  parameters:
    DeviceIdHeader:
      name: X-Device-Id
      in: header
      required: false
      description: |
        Device identifier for multi-device support. Required when multiple devices are registered.
        If only one device is registered, it will be used as the default.
        Can also be provided as `device_id` query parameter.
      schema:
        type: string
        example: 'my-device-id'
    ScheduleIdPath:
      name: schedule_id
      in: path
      required: true
      schema:
        type: string
      description: Schedule ID returned as `schedule_id` by a scheduled send
    ChatwootConfigDeviceId:
      name: device_id
      in: path
      required: true
      description: Device ID (or WhatsApp JID) whose Chatwoot config is addressed
      schema:
        type: string
        example: 'my-device-id'

  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    ChatwootDeviceConfig:
      type: object
      description: Per-device Chatwoot routing config (API token masked on every read)
      properties:
        device_id:
          type: string
          example: 'my-device-id'
        device_jid:
          type: string
          description: WhatsApp JID of the device; stamped automatically at login (empty before pairing)
          example: '[email protected]'
        chatwoot_url:
          type: string
          example: 'https://chatwoot.example.com'
        account_id:
          type: integer
          example: 1
        inbox_id:
          type: integer
          example: 5
        api_token:
          type: string
          description: Masked; only the last 4 characters are revealed
          example: '****1234'
        enabled:
          type: boolean
          example: true
        webhook_url:
          type: string
          description: URL to set on this device's Chatwoot inbox so agent replies route back to this device
          example: 'https://gowa.example.com/chatwoot/webhook/my-device-id'
        webhook_secret_set:
          type: boolean
          description: Whether this device has its own webhook secret (the secret itself is never returned)
          example: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateGroupResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get list groups
        results:
          type: object
          properties:
            group_id:
              type: string
              example: [email protected]
    GroupInfoFromLinkResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get group info from link
        results:
          type: object
          properties:
            group_id:
              type: string
              example: '[email protected]'
              description: The group ID
            name:
              type: string
              example: 'Example Group Name'
              description: The group name
            topic:
              type: string
              example: 'Welcome to our group! Please follow the rules.'
              description: The group topic/description
            created_at:
              type: string
              format: date-time
              example: '2024-01-15T10:30:00Z'
              description: When the group was created
            participant_count:
              type: integer
              example: 25
              description: Number of participants in the group
            is_locked:
              type: boolean
              example: false
              description: Whether the group is locked (only admins can modify group info)
            is_announce:
              type: boolean
              example: false
              description: Whether the group is in announce mode (only admins can send messages)
            is_ephemeral:
              type: boolean
              example: false
              description: Whether the group has disappearing messages enabled
            description:
              type: string
              example: 'This group is for discussing project updates'
              description: Additional description of the group
    ManageParticipantRequest:
      type: object
      properties:
        group_id:
          type: string
          example: [email protected]
        participants:
          type: array
          items:
            type: string
          example:
            - '6819241294719274'
            - '6829241294719274'
            - '6839241294719274'
    ManageParticipantResponse:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get list groups
        results:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              participant:
                type: string
                example: '[email protected]'
              status:
                type: string
                example: success
              message:
                type: string
                example: Participant added
    GroupParticipantsResponse:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success getting group participants
        results:
          $ref: '#/components/schemas/GroupParticipantsResult'
    GroupParticipantsResult:
      type: object
      additionalProperties: false
      properties:
        group_id:
          type: string
          example: '[email protected]'
        name:
          type: string
          example: My Awesome Group
        participants:
          type: array
          items:
            $ref: '#/components/schemas/GroupParticipantItem'
    GroupParticipantItem:
      type: object
      additionalProperties: false
      properties:
        jid:
          type: string
          example: '[email protected]'
        phone_number:
          type: string
          example: '[email protected]'
        lid:
          type: string
          nullable: true
          example: '12345@lid'
        display_name:
          type: string
          nullable: true
          example: Anonymous Member
        is_admin:
          type: boolean
          example: true
        is_super_admin:
          type: boolean
          example: false
    SetGroupPhotoResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success update group photo
        results:
          type: object
          properties:
            picture_id:
              type: string
              example: "1647874123"
              description: The ID of the uploaded picture, or 'remove' if photo was removed
            message:
              type: string
              example: Success update group photo

    UserMyGroupItem:
      type: object
      description: |
        One joined group as serialized `whatsmeow/types.GroupInfo`. Embedded structs are flattened; field names stay PascalCase (Go default JSON).
      properties:
        JID:
          type: string
          example: "[email protected]"
        OwnerJID:
          type: string
        OwnerPN:
          type: string
        Name:
          type: string
        NameSetAt:
          type: string
          format: date-time
        NameSetBy:
          type: string
        NameSetByPN:
          type: string
        GroupCreated:
          type: string
          format: date-time
        CreatorCountryCode:
          type: string
        ParticipantVersionID:
          type: string
        ParticipantCount:
          type: integer
        Participants:
          type: array
          items:
            $ref: '#/components/schemas/JoinedGroupParticipant'
        MemberAddMode:
          type: string
          example: "admin_add"
        Suspended:
          type: boolean
        AddressingMode:
          type: string
        IsLocked:
          type: boolean
        IsAnnounce:
          type: boolean
        AnnounceVersionID:
          type: string
        IsEphemeral:
          type: boolean
        DisappearingTimer:
          type: integer
        IsIncognito:
          type: boolean
        IsJoinApprovalRequired:
          type: boolean
        DefaultMembershipApprovalMode:
          type: string
        IsParent:
          type: boolean
        LinkedParentJID:
          type: string
        IsDefaultSubGroup:
          type: boolean
        Topic:
          type: string
        TopicID:
          type: string
        TopicDeleted:
          type: boolean
        TopicSetAt:
          type: string
          format: date-time
        TopicSetBy:
          type: string
        TopicSetByPN:
          type: string

    JoinedGroupParticipant:
      type: object
      description: Serialized `whatsmeow/types.GroupParticipant` in joined-group list payloads.
      properties:
        JID:
          type: string
          description: Primary ID for the member (often `@lid`).
        PhoneNumber:
          type: string
          description: User JID string when known (e.g. `[email protected]`); may be empty in edge cases.
        LID:
          type: string
        IsAdmin:
          type: boolean
        IsSuperAdmin:
          type: boolean
        DisplayName:
          type: string
          description: Set for some anonymous / announcement cases; often empty.
        Error:
          type: integer
        AddRequest:
          type: object
          nullable: true

    UserGroupResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get list groups
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/UserMyGroupItem'

    UserInfoResponse:
      type: object
      required:
        - code
        - message
        - results
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success
        results:
          type: object
          properties:
            verified_name:
              type: string
              example: Aldino Kemal
            status:
              type: string
              example: Hello World
            picture_id:
              type: string
              example: 1651459152
            devices:
              type: array
              items:
                type: object
                properties:
                  User:
                    type: string
                    example: 6289685021291
                  Agent:
                    type: integer
                    example: 0
                  Device:
                    type: string
                    example: UNKNOWN
                  Server:
                    type: string
                    example: s.whatsapp.net
                  AD:
                    type: boolean
                    example: true
    UserAvatarResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success
        results:
          type: object
          properties:
            url:
              type: string
              example: 'https://pps.whatsapp.net/v/t61.24694-24/181358562_385581386633509_6230178822944778044_n.jpg?ccb=11-4&oh=df36c5b990497b8a5758a0f1ad8118a8&oe=620AA726'
            id:
              type: string
              example: '1635239861'
            type:
              type: string
              example: 'image'
    UserPrivacyResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get privacy
        results:
          type: object
          properties:
            group_add:
              type: string
              example: all
            last_seen:
              type: string
              example: null
            status:
              type: string
              example: all
            profile:
              type: string
              example: all
            read_receipts:
              type: string
              example: all
    SendResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success
        results:
          type: object
          properties:
            message_id:
              type: string
              example: '3EB0B430B6F8F1D0E053AC120E0A9E5C'
              description: Omitted for scheduled sends
            status:
              type: string
              example: '<feature> success ....'
            schedule_id:
              type: string
              example: '0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10'
              description: Scheduled sends only. Use it with the /send/schedules routes.
            scheduled_at:
              type: string
              format: date-time
              example: '2026-10-01T02:00:00Z'
              description: Scheduled sends only. The first send time.
            next_run_at:
              type: string
              format: date-time
              example: '2026-10-01T02:00:00Z'
              description: Scheduled sends only. When the worker sends next.
    ScheduleOptions:
      type: object
      description: |
        Optional fields that schedule the message instead of sending it now. Set
        `scheduled_at` to schedule; without it the message is sent immediately.
        A background worker sends it at the scheduled time, retrying while the
        device is offline or not logged in. Uploaded media is stored on the
        server until the schedule finishes.
        In multipart/form-data bodies, send `weekdays` as a repeated field
        (`weekdays=1`, `weekdays=3`).
      properties:
        scheduled_at:
          type: string
          format: date-time
          example: '2026-10-01T09:00:00+07:00'
          description: RFC3339 time of the first send. Must be in the future. The first send always happens at this time, even if it falls outside `weekdays` or `day_of_month`; those set the repeats that follow.
        timezone:
          type: string
          example: Asia/Jakarta
          description: IANA timezone used to compute recurring runs. Required when scheduled_at is set.
        recurrence:
          type: string
          enum: [once, daily, weekly, monthly]
          default: once
          description: How often to repeat the send
        weekdays:
          type: array
          items:
            type: integer
            minimum: 0
            maximum: 6
          uniqueItems: true
          example: [1, 3, 5]
          description: Days to send on, 0=Sunday through 6=Saturday. Required when recurrence is weekly.
        day_of_month:
          type: integer
          minimum: 1
          maximum: 31
          example: 15
          description: Day of the month to send on, clamped to the month's last day. Required when recurrence is monthly.
        end_at:
          type: string
          format: date-time
          example: '2026-12-31T23:59:59+07:00'
          description: Recurring only. No sends happen after this time; must be after scheduled_at.
        occurrence_limit:
          type: integer
          minimum: 1
          example: 10
          description: Recurring only. Stop after this many sends.
    Schedule:
      type: object
      properties:
        id:
          type: string
          example: '0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10'
        message_type:
          type: string
          enum: [text, image, file, video, audio, sticker, contact, link, location, poll, forward]
          example: text
        phone:
          type: string
          example: '[email protected]'
        summary:
          type: string
          example: selamat pagi
          description: Short preview of the message
        status:
          type: string
          enum: [active, running, paused, completed, failed, cancelled]
          example: active
          description: |
            - `active`: waiting for its next run
            - `running`: claimed by the worker and sending
            - `paused`: held until resumed
            - `completed`: no runs left
            - `failed`: gave up after retries or a validation error
            - `cancelled`: cancelled by the user
        scheduled_at:
          type: string
          format: date-time
          example: '2026-10-01T02:00:00Z'
        next_run_at:
          type: string
          format: date-time
          example: '2026-10-01T02:00:00Z'
          description: Omitted when no run is left
        timezone:
          type: string
          example: Asia/Jakarta
        recurrence:
          type: string
          enum: [once, daily, weekly, monthly]
          example: once
        weekdays:
          type: array
          items:
            type: integer
          example: [1, 3, 5]
        day_of_month:
          type: integer
          example: 15
        end_at:
          type: string
          format: date-time
        occurrence_limit:
          type: integer
          example: 10
        occurrence_count:
          type: integer
          example: 0
          description: Number of successful sends so far
        attempts:
          type: integer
          example: 0
          description: Failed attempts for the current run
        last_run_at:
          type: string
          format: date-time
        last_message_id:
          type: string
          example: '3EB0B430B6F8F1D0E053AC120E0A9E5C'
        last_error:
          type: string
        created_at:
          type: string
          format: date-time
          example: '2026-09-25T08:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-09-25T08:00:00Z'
    ScheduleResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Schedule fetched
        results:
          $ref: '#/components/schemas/Schedule'
    ScheduleListResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Schedules fetched
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Schedule'
            pagination:
              type: object
              properties:
                limit:
                  type: integer
                  example: 25
                offset:
                  type: integer
                  example: 0
                total:
                  type: integer
                  example: 3
    DeviceResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Fetch device success
        results:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: 'Aldino Kemal'
              device:
                type: string
                description: Session ID registered via POST /devices (stable across restarts)
                example: 'org_2'
              jid:
                type: string
                description: WhatsApp JID of the logged-in account (empty until login)
                example: '[email protected]'

    # Device Management Schemas (v8)
    DeviceListResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: List devices
        status:
          type: integer
          example: 200
        results:
          type: array
          items:
            $ref: '#/components/schemas/DeviceInfo'
    DeviceAddResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Device added
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            id:
              type: string
              example: 'my-device-id'
            display_name:
              type: string
              example: 'John Doe'
            state:
              type: string
              enum: [disconnected, connecting, connected, logged_in]
              example: 'disconnected'
            jid:
              type: string
              example: '[email protected]'
            created_at:
              type: string
              format: date-time
              example: '2024-01-01T00:00:00Z'
            webhook_url:
              type: string
              description: Device-specific webhook URL echoed when provided on create
              example: 'https://device-webhook.example.com/handler'
            webhook_secret:
              type: string
              description: Device-specific webhook secret echoed when provided on create
              example: 'super-secret-key'
            webhook_events:
              type: string
              description: Device-specific event whitelist echoed when provided on create
              example: 'message,message.ack'
            webhook_insecure_skip_verify:
              type: boolean
              description: Device-specific TLS verification setting echoed when provided on create
              example: false
    DeviceInfoResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Device info
        status:
          type: integer
          example: 200
        results:
          $ref: '#/components/schemas/DeviceInfo'
    DeviceStatusResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Device status
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            device_id:
              type: string
              example: 'my-device-id'
            is_connected:
              type: boolean
              example: true
            is_logged_in:
              type: boolean
              example: true
    DeviceLoginResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Login success
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            device_id:
              type: string
              example: 'my-device-id'
            qr_link:
              type: string
              example: 'http://localhost:3000/statics/images/qrcode/scan-qr-b0b7bb43-9a22-455a-814f-5a225c743310.png'
            qr_duration:
              type: integer
              example: 30
    DeviceLoginWithCodeResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Login with code started
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            device_id:
              type: string
              example: 'my-device-id'
            pair_code:
              type: string
              example: ABCD-1234
    DeviceInfo:
      type: object
      properties:
        id:
          type: string
          example: 'my-device-id'
        phone_number:
          type: string
          example: '628123456789'
        display_name:
          type: string
          example: 'John Doe'
        state:
          type: string
          enum: [disconnected, connecting, connected, logged_in]
          example: 'logged_in'
        jid:
          type: string
          example: '[email protected]'
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00Z'

    LoginWithCodeResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success
        results:
          type: object
          properties:
            pair_code:
              type: string
              example: ABCD-1234
    LoginResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success
        results:
          type: object
          properties:
            qr_duration:
              type: integer
              example: 30
            qr_link:
              type: string
              example: 'http://localhost:3000/statics/images/qrcode/scan-qr-b0b7bb43-9a22-455a-814f-5a225c743310.png'
    PasskeyStatusResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Passkey pairing status
        results:
          type: object
          properties:
            device_id:
              type: string
              example: device-1
            status:
              type: string
              enum: [none, awaiting_response, awaiting_confirmation]
              example: awaiting_response
            challenge:
              type: object
              nullable: true
              description: WebAuthn assertion request options (PublicKeyCredentialRequestOptions JSON, base64url-encoded binary fields)
              properties:
                challenge:
                  type: string
                  example: dGVzdC1jaGFsbGVuZ2U
                timeout:
                  type: integer
                  example: 60000
                rpId:
                  type: string
                  example: whatsapp.com
                allowCredentials:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        type: string
                        example: public-key
                      transports:
                        type: array
                        items:
                          type: string
                userVerification:
                  type: string
                  example: required
            code:
              type: string
              description: Pairing confirmation code (set while awaiting confirmation)
              example: ABCD-EFGH
            skip_handoff_ux:
              type: boolean
              example: false
    WebAuthnAssertion:
      type: object
      description: WebAuthn assertion in PublicKeyCredential.toJSON() format (binary fields base64url-encoded without padding)
      required: [id, rawId, type, response]
      properties:
        id:
          type: string
          example: XcnXe2W9me1XZTGii6JI9A
        rawId:
          type: string
          example: XcnXe2W9me1XZTGii6JI9A
        type:
          type: string
          example: public-key
        response:
          type: object
          required: [clientDataJSON, authenticatorData, signature]
          properties:
            clientDataJSON:
              type: string
            authenticatorData:
              type: string
            signature:
              type: string
            userHandle:
              type: string
              nullable: true
    GenericResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success
        results:
          type: string
          example: null
    ErrorInternalServer:
      type: object
      properties:
        code:
          type: string
          example: INTERNAL_SERVER_ERROR
          description: 'SYSTEM_CODE_ERROR'
        message:
          type: string
          example: you are not loggin
          description: 'Detail error message'
        results:
          type: object
          example: null
          description: 'additional data'
    ErrorBadRequest:
      type: object
      properties:
        code:
          type: string
          example: 400
          description: 'HTTP Status Code'
        message:
          type: string
          example: field cannot be blank
          description: 'Detail error message'
        results:
          type: object
          example: null
          description: 'additional data'
    ErrorUnauthorized:
      type: object
      properties:
        code:
          type: string
          example: 401
          description: 'HTTP Status Code'
        message:
          type: string
          example: Unauthorized access
          description: 'Detail error message'
        results:
          type: object
          example: null
          description: 'additional data'
    ErrorForbidden:
      type: object
      properties:
        code:
          type: string
          example: AVATAR_HIDDEN
          description: 'SYSTEM_CODE_ERROR'
        message:
          type: string
          example: the user has hidden their profile picture from you
          description: 'Detail error message'
        results:
          type: object
          description: 'additional data'
    ErrorNotFound:
      type: object
      properties:
        code:
          type: string
          example: 404
          description: 'HTTP Status Code'
        message:
          type: string
          example: Chat not found
          description: 'Detail error message'
        results:
          type: object
          example: null
          description: 'additional data'
    NewsletterResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success get list newsletter"
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Newsletter'
    Newsletter:
      type: object
      properties:
        id:
          type: string
          example: "120363144038483540@newsletter"
        state:
          type: object
          properties:
            type:
              type: string
              example: "active"
        thread_metadata:
          type: object
          properties:
            creation_time:
              type: string
              example: "1688746895"
            invite:
              type: string
              example: "0029Va4K0PZ5a245NkngBA2M"
            name:
              type: object
              properties:
                text:
                  type: string
                  example: "WhatsApp"
                id:
                  type: string
                  example: "1688746895480511"
                update_time:
                  type: string
                  example: "1688746895480511"
            description:
              type: object
              properties:
                text:
                  type: string
                  example: "WhatsApp's official channel. Follow for our latest feature launches, updates, exclusive drops and more."
                id:
                  type: string
                  example: "1689653839450668"
                update_time:
                  type: string
                  example: "1689653839450668"
            subscribers_count:
              type: string
              example: "0"
            verification:
              type: string
              example: "verified"
            picture:
              type: object
              properties:
                url:
                  type: string
                  example: ""
                id:
                  type: string
                  example: "1707950960975554"
                type:
                  type: string
                  example: "IMAGE"
                direct_path:
                  type: string
                  example: "/v/t61.24694-24/416962407_970228831134395_8869146381947923973_n.jpg?ccb=11-4&oh=01_Q5AaIIvOIeu3l0HCZWILrmr-dGR_vXFqnhUeytw0-ojPc4hL&oe=670D95B1&_nc_sid=5e03e0&_nc_cat=110"
            preview:
              type: object
              properties:
                url:
                  type: string
                  example: ""
                id:
                  type: string
                  example: "1707950960975554"
                type:
                  type: string
                  example: "PREVIEW"
                direct_path:
                  type: string
                  example: "/v/t61.24694-24/416962407_970228831134395_8869146381947923973_n.jpg?stp=dst-jpg_s192x192&ccb=11-4&oh=01_Q5AaIHO-DQklqm3q3awF7xwji_WAn9DkgZASQA0B2Ct0qbSa&oe=670D95B1&_nc_sid=5e03e0&_nc_cat=110"
            settings:
              type: object
              properties:
                reaction_codes:
                  type: object
                  properties:
                    value:
                      type: string
                      example: "ALL"
        viewer_metadata:
          type: object
          nullable: true
          description: Null when viewer-specific metadata is unavailable.
          properties:
            mute:
              type: string
              example: "off"
            role:
              type: string
              example: "subscriber"
    NewsletterInfoResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success get newsletter info"
        results:
          $ref: '#/components/schemas/Newsletter'
    NewsletterDirectoryResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success search newsletter directory"
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Newsletter'
            next_cursor:
              type: string
              example: "GTby6Oiy0/jOqwPYxYXQtvjOqwPC0uaVue3OqwMZ"
            has_more:
              type: boolean
              example: true
    NewsletterLiveUpdatesSubscription:
      type: object
      properties:
        newsletter_id:
          type: string
          example: '120363024512399999@newsletter'
        duration_seconds:
          type: integer
          example: 90
        expires_at:
          type: string
          example: "2026-10-28T17:37:28Z"
        renewed_at:
          type: string
          example: "2026-10-28T17:35:58Z"
        last_error:
          type: string
          description: Last renewal error, cleared after a successful renewal
    NewsletterLiveUpdatesResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success subscribe newsletter live updates"
        results:
          $ref: '#/components/schemas/NewsletterLiveUpdatesSubscription'
    NewsletterLiveUpdatesListResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success list newsletter live updates"
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/NewsletterLiveUpdatesSubscription'
    NewsletterMessagesResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success get newsletter messages"
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/NewsletterMessage'
    NewsletterMessage:
      type: object
      properties:
        server_id:
          type: integer
          example: 123
        message_id:
          type: string
          example: "3EB0XXXXXXXXXXXXXXXX"
        type:
          type: string
          example: "text"
        timestamp:
          type: string
          example: "2026-06-30T10:00:00Z"
        views_count:
          type: integer
          description: Only reported to channel admins; 0 otherwise
          example: 42
        forwards_count:
          type: integer
          example: 7
        reaction_counts:
          type: object
          additionalProperties:
            type: integer
          example: { "😀": 3, "👍": 5 }
        text:
          type: string
          example: "Hello from the channel!"
    NewsletterMediaDownloadResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Media downloaded successfully
        results:
          type: object
          properties:
            server_id:
              type: integer
              example: 8872
            message_id:
              type: string
              example: ACBD7F85529AAD63FAF376F622351D14
            status:
              type: string
              example: Media downloaded successfully to statics/media/120363024512399999/2026-08-28/image.jpg
            media_type:
              type: string
              enum: [image, video, video_note, audio, document, sticker]
              example: image
            mime_type:
              type: string
              example: image/jpeg
            filename:
              type: string
              example: image.jpg
            file_path:
              type: string
              description: Local server path where the downloaded media was saved
              example: statics/media/120363024512399999/2026-08-28/image.jpg
            file_url:
              type: string
              description: Public URL for the saved media file
              example: http://localhost:3000/statics/media/120363024512399999/2026-08-28/image.jpg
            file_size:
              type: integer
              format: int64
              example: 524288
    MyListContactsResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success get list contacts"
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/MyListContacts'
    MyListContacts:
      type: object
      properties:
        jid:
          type: string
          example: "[email protected]"
        name:
          type: string
          example: "Aldino Kemal"


    GroupParticipantRequestItem:
      type: object
      properties:
        jid:
          type: string
          description: Requester's JID; often `@lid` until a phone mapping exists locally.
          example: "84198740205822@lid"
        phone_number:
          type: string
          description: |
            Digits from the resolved `@s.whatsapp.net` JID when LID→PN mapping is available.
            Empty when only `@lid` is known — the LID user part is not a phone number and must not be shown here.
          example: "6289685024091"
        display_name:
          type: string
          description: From saved contact, verified business name, or WhatsApp-supplied display (may be omitted when empty).
          example: "John Doe"
        requested_at:
          type: string
          format: date-time
          example: "2026-03-27T23:18:47Z"

    GroupParticipantRequestListResponse:
      type: object
      properties:
        code:
          type: string
          example: "SUCCESS"
        message:
          type: string
          example: "Success getting list requested participants"
        results:
          type: array
          description: Pending join requests for the group (not wrapped in `data`).
          items:
            $ref: '#/components/schemas/GroupParticipantRequestItem'
    UserCheckResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success check user
        results:
          type: object
          properties:
            is_on_whatsapp:
              type: boolean
              example: true
    BusinessProfileResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get business profile
        results:
          type: object
          properties:
            jid:
              type: string
              example: '[email protected]'
              description: Business account JID
            email:
              type: string
              example: '[email protected]'
              description: Business email address
            address:
              type: string
              example: '123 Business Street, City, Country'
              description: Business physical address
            categories:
              type: array
              description: Business categories
              items:
                type: object
                properties:
                  id:
                    type: string
                    example: 'retail'
                  name:
                    type: string
                    example: 'Retail Store'
            profile_options:
              type: object
              description: Additional profile options
              example:
                website: 'https://example.com'
                description: 'Business description'
            business_hours_timezone:
              type: string
              example: 'Asia/Jakarta'
              description: Business hours timezone
            business_hours:
              type: array
              description: Business operating hours
              items:
                type: object
                properties:
                  day_of_week:
                    type: string
                    example: 'monday'
                  mode:
                    type: string
                    example: 'open'
                  open_time:
                    type: string
                    example: '09:00'
                  close_time:
                    type: string
                    example: '18:00'

    ChatListResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get chat list
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Chat'
            pagination:
              type: object
              properties:
                limit:
                  type: integer
                  example: 25
                offset:
                  type: integer
                  example: 0
                total:
                  type: integer
                  example: 150

    Chat:
      type: object
      properties:
        jid:
          type: string
          example: '[email protected]'
          description: Chat JID identifier
        name:
          type: string
          example: 'John Doe'
          description: Chat display name
        last_message_time:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
          description: Timestamp of the last message
        ephemeral_expiration:
          type: integer
          example: 0
          description: Ephemeral message expiration time in seconds (0 = disabled)
        created_at:
          type: string
          format: date-time
          example: '2024-01-10T08:00:00Z'
          description: Chat creation timestamp
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
          description: Chat last update timestamp
        archived:
          type: boolean
          example: false
          description: Whether the chat is archived

    ChatMessagesResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get chat messages
        results:
          type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/ChatMessage'
            pagination:
              type: object
              properties:
                limit:
                  type: integer
                  example: 50
                offset:
                  type: integer
                  example: 0
                total:
                  type: integer
                  example: 1250
            chat_info:
              $ref: '#/components/schemas/Chat'

    ChatMessage:
      type: object
      properties:
        id:
          type: string
          example: '3EB0B430B6F8F1D0E053AC120E0A9E5C'
          description: Message ID
        chat_jid:
          type: string
          example: '[email protected]'
          description: Chat JID this message belongs to
        sender_jid:
          type: string
          example: '[email protected]'
          description: Sender JID
        sender_display_name:
          type: string
          example: 'Saved Contact'
          description: >-
            Human-readable sender label resolved dynamically when this response is produced, not stored with the message.
            For other senders, it prefers the saved contact full name, then the stored contact push name, business name,
            JID user part, and raw JID. For the active account, it prefers the device display name (falling back to the
            stored account push name), account JID user part, account JID, sender JID user part, and raw sender JID.
            A contact rename can therefore change the label returned for historical messages. `sender_jid` remains the
            stable sender identifier.
        content:
          type: string
          example: 'Hello, how are you?'
          description: Message text content
        timestamp:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
          description: Message timestamp
        is_from_me:
          type: boolean
          example: false
          description: Whether this message was sent by the current user
        media_type:
          type: string
          example: 'image'
          nullable: true
          description: Type of media (image, video, audio, document, etc.). Value `call` indicates a stored incoming call log.
        reactions:
          type: array
          description: Emoji reactions attached to this message
          items:
            $ref: '#/components/schemas/ChatReaction'
        call_metadata:
          type: string
          example: '{"call_id":"ABC","auto_rejected":false}'
          description: JSON string with call details when media_type is `call`. Omitted when not applicable (matches Go json omitempty).
        referral_metadata:
          type: string
          example: '{"ctwa_clid":"clid_123","source_app":"whatsapp"}'
          description: JSON string with Meta Ads referral/attribution details when the message originated from a Click-to-WhatsApp ad. Omitted when not applicable (matches Go json omitempty).
        context_metadata:
          type: string
          example: '{"replied_to_id":"AC625C65EA7143E71D784176C4A90A93"}'
          description: JSON string containing the replied-to message ID when reply context is known. Captured from live, sent, and history-sync messages. Omitted when no reply context is available, including older stored rows until they are reingested with context.
        filename:
          type: string
          example: 'photo.jpg'
          nullable: true
          description: Original filename for media messages
        url:
          type: string
          example: 'https://media.example.com/file.jpg'
          nullable: true
          description: Media file URL
        file_length:
          type: integer
          example: 1024768
          nullable: true
          description: File size in bytes for media messages
        created_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
          description: Record creation timestamp
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T10:30:00Z'
          description: Record last update timestamp

    ChatReaction:
      type: object
      properties:
        emoji:
          type: string
          example: '👍'
          description: Emoji used in the reaction
        sender_jid:
          type: string
          example: '[email protected]'
          description: JID of the user who reacted
        sender_display_name:
          type: string
          example: 'Saved Contact'
          description: >-
            Human-readable sender label resolved dynamically when this response is produced, not stored with the reaction.
            For other senders, it prefers the saved contact full name, then the stored contact push name, business name,
            JID user part, and raw JID. For the active account, it prefers the device display name (falling back to the
            stored account push name), account JID user part, account JID, sender JID user part, and raw sender JID.
            A contact rename can therefore change the label returned for historical reactions. `sender_jid` remains the
            stable sender identifier.
        is_from_me:
          type: boolean
          example: false
          description: Whether the reaction was made by the current user
        timestamp:
          type: string
          format: date-time
          example: '2024-01-15T10:31:00Z'
          description: When the reaction was received

    RequestChatHistoryResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: History sync requested successfully
        results:
          type: object
          properties:
            status:
              type: string
              example: requested
            chat_jid:
              type: string
              example: '[email protected]'
            requested_count:
              type: integer
              example: 50
            anchor_message_id:
              type: string
              example: '3EB0C767D82B0A0D1234'
            anchor_timestamp:
              type: string
              format: date-time
              example: '2026-05-16T08:00:00Z'
    PinChatResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Chat pinned successfully
        results:
          type: object
          properties:
            status:
              type: string
              example: success
            message:
              type: string
              example: Chat pinned successfully
            chat_jid:
              type: string
              example: '[email protected]'
            pinned:
              type: boolean
              example: true
    SetDisappearingTimerResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Disappearing messages set to 86400 seconds
        results:
          type: object
          properties:
            status:
              type: string
              example: success
            message:
              type: string
              example: Disappearing messages set to 86400 seconds
            chat_jid:
              type: string
              example: '[email protected]'
            timer_seconds:
              type: integer
              example: 86400
    ArchiveChatResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Chat archived successfully
        results:
          type: object
          properties:
            status:
              type: string
              example: success
            message:
              type: string
              example: Chat archived successfully
            chat_jid:
              type: string
              example: '[email protected]'
            archived:
              type: boolean
              example: true
    GroupInfoResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get group info
        results:
          type: object
          description: Group information object (structure may vary)
          additionalProperties: true

    GetGroupInviteLinkResponse:
      type: object
      properties:
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Success get group invite link
        results:
          type: object
          properties:
            invite_link:
              type: string
              example: 'https://chat.whatsapp.com/ABC123...'
              description: The group invite link
            group_id:
              type: string
              example: '[email protected]'
              description: The group ID

    ChatwootSyncResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SYNC_STARTED
        message:
          type: string
          example: History sync initiated in background
        results:
          type: object
          properties:
            device_id:
              type: string
              example: my-device-id
            days_limit:
              type: integer
              example: 3
            include_media:
              type: boolean
              example: true
            include_groups:
              type: boolean
              example: true
    ChatwootSyncStatusResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        code:
          type: string
          example: SUCCESS
        message:
          type: string
          example: Sync status retrieved
        results:
          type: object
          properties:
            device_id:
              type: string
              example: my-device-id
            status:
              type: string
              enum: [idle, running, completed, failed]
              example: running
            total_chats:
              type: integer
              example: 10
            synced_chats:
              type: integer
              example: 5
            total_messages:
              type: integer
              example: 100
            synced_messages:
              type: integer
              example: 50
            failed_messages:
              type: integer
              example: 2
            current_chat:
              type: string
              example: "[email protected]"
            started_at:
              type: string
              format: date-time
            completed_at:
              type: string
              format: date-time
            error:
              type: string

    InteractiveNativeFlowButton:
      type: object
      required: [name, params]
      properties:
        name:
          type: string
          enum: [quick_reply, cta_url, cta_copy, cta_call, single_select, send_location]
        params:
          type: object
          additionalProperties: true
          description: |
            Maximum 16384 JSON bytes. quick_reply requires display_text and id;
            cta_url requires display_text and an absolute HTTP(S) url;
            cta_copy requires display_text and copy_code;
            cta_call requires display_text and phone_number.
            single_select requires title and nonempty sections, each with
            nonempty rows whose id and title are nonempty strings.
            send_location accepts an object such as {} and must be the sole
            button in a non-carousel message. All named text parameters must
            be nonempty strings.
    InteractiveCarouselCard:
      type: object
      required: [body, buttons]
      properties:
        title:
          type: string
          description: Maximum 256 bytes.
        body:
          type: string
          description: Required nonblank text, maximum 4096 bytes.
        footer:
          type: string
          description: Maximum 256 bytes.
        image_base64:
          type: string
          description: |
            Optional raw standard base64 JPEG or PNG, without a data URL prefix.
            Maximum 2800000 encoded characters and 2000000 decoded bytes, also
            subject to the configured image limit. Maximum 4096 pixels per side.
            Resized, JPEG-encoded, thumbnailed, and uploaded before sending.
        buttons:
          type: array
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/InteractiveNativeFlowButton'
    InteractiveSendRequest:
      type: object
      required: [phone, body]
      properties:
        phone:
          type: string
          description: Phone number or full individual user or group JID.
        body:
          type: string
          description: Required nonblank text, maximum 4096 bytes.
        footer:
          type: string
          description: Maximum 256 bytes.
        buttons:
          type: array
          minItems: 1
          maxItems: 10
          items:
            $ref: '#/components/schemas/InteractiveNativeFlowButton'
        cards:
          type: array
          minItems: 2
          maxItems: 10
          items:
            $ref: '#/components/schemas/InteractiveCarouselCard'
      oneOf:
        - required: [buttons]
          not:
            required: [cards]
        - required: [cards]
          not:
            required: [buttons]