components:
  parameters:
    InstanceId:
      description: Unique instance identifier.
      in: path
      name: instanceId
      required: true
      schema:
        format: uuid
        type: string
    InstanceToken:
      description: Token returned during provisioning.
      in: path
      name: instanceToken
      required: true
      schema:
        type: string
  schemas:
    ActionButton:
      additionalProperties: false
      description: |
        Action button for interactive messages (CTA buttons).

        **Supported Actions:**
        - Open URL (`cta_url`)
        - Make call (`cta_call`)
        - Copy text (`cta_copy`)
        - Quick reply (`quick_reply`)
      properties:
        copyCode:
          description: Text to copy (required for cta_copy)
          example: CODE123
          type: string
        id:
          description: Unique button identifier (max 256 chars)
          example: btn_1
          maxLength: 256
          type: string
        label:
          description: Button display text (max 25 chars, 20 for quick_reply)
          example: View Details
          maxLength: 25
          type: string
        phone:
          description: Phone number to call (required for cta_call)
          example: "+5511999999999"
          type: string
        type:
          $ref: '#/components/schemas/ButtonType'
        url:
          description: URL to open (required for cta_url)
          example: https://httpbin.org/anything/details
          format: uri
          type: string
      required:
      - id
      - type
      - label
      type: object
    AddContactRequest:
      additionalProperties: false
      description: Request to add a contact to the address book.
      properties:
        fullName:
          description: Full name to save for the contact.
          example: John Doe
          type: string
        phone:
          description: Phone number in international format.
          example: "5511999999999"
          type: string
      required:
      - phone
      - fullName
      type: object
    AddContactResponse:
      additionalProperties: false
      description: Response after adding a contact.
      properties:
        fullName:
          description: The full name saved.
          type: string
        message:
          description: Status message.
          type: string
        phone:
          description: The phone number of the contact.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - phone
      - fullName
      - message
      type: object
    BoolValueRequest:
      additionalProperties: false
      properties:
        value:
          description: Boolean value for the setting.
          type: boolean
      required:
      - value
      type: object
    BooleanStatusResponse:
      additionalProperties: false
      description: acknowledgement payload using a boolean `value`.
      properties:
        value:
          description: Indicates whether the operation succeeded (`true`) or failed
            (`false`).
          type: boolean
      required:
      - value
      type: object
    BooleanSuccessResponse:
      additionalProperties: false
      description: acknowledgement payload using a boolean `success`.
      properties:
        success:
          description: Indicates whether the operation succeeded (`true`) or failed
            (`false`).
          type: boolean
      required:
      - success
      type: object
    Button:
      additionalProperties: false
      description: |
        Simple reply button for button-list messages.

        **Limits:**
        - ID: max 256 characters
        - Title: max 20 characters
      properties:
        id:
          description: Unique button identifier (returned in selection callback)
          example: btn_yes
          maxLength: 256
          type: string
        title:
          description: Button display text
          example: "Yes"
          maxLength: 20
          type: string
      required:
      - id
      - title
      type: object
    ButtonType:
      description: |
        Type of button for interactive messages.

        **Button Types:**
        - `quick_reply` - Simple reply button (max 20 chars label)
        - `cta_url` - Opens a URL in browser
        - `cta_call` - Initiates a phone call
        - `cta_copy` - Copies text to clipboard
        - `payment_info` - Shows payment information
        - `review_and_pay` - Review and pay action
      enum:
      - quick_reply
      - cta_url
      - cta_call
      - cta_copy
      - payment_info
      - review_and_pay
      example: cta_url
      type: string
    CarouselCard:
      additionalProperties: false
      description: |
        Card in a carousel message.

        **Structure:**
        - mediaUrl: URL for card image/video (required)
        - body: Text content (required, max 1024 chars)
        - buttons: Action buttons (required, 1-3 per card)
        - header: Optional header text (max 60 chars)
        - footer: Optional footer text (max 60 chars)

        **Limits:**
        - Body text: max 1024 characters
        - Buttons per card: 1-3
        - Header text: max 60 characters
        - Footer text: max 60 characters
      properties:
        body:
          description: Card body text content (required)
          example: Product description here
          maxLength: 1024
          type: string
        buttons:
          description: Action buttons for this card (1-3 buttons required)
          items:
            $ref: '#/components/schemas/ActionButton'
          maxItems: 3
          minItems: 1
          type: array
        footer:
          description: Optional card footer text
          example: $99.99
          maxLength: 60
          type: string
        header:
          description: Optional card header text
          example: Product Name
          maxLength: 60
          type: string
        mediaUrl:
          description: URL for card image or video (required)
          example: https://picsum.photos/600/400.jpg
          format: uri
          type: string
      required:
      - mediaUrl
      - body
      - buttons
      type: object
    Chat:
      additionalProperties: false
      description: |
        WhatsApp chat information.

        **Chat Types**:
        - Individual chats (person-to-person)
        - Group chats (multiple participants)
        - Community announcement channels

        **Data Sources**:
        - WhatsApp chat metadata (from store)
        - Message history (last message timestamp)
        - Chat settings (mute, archive, pin, spam status)

        **Ordering**: By default, chats are ordered by lastMessageTime descending (most recent first).

        **Unread Counts**: Both `unread` and `messagesUnread` represent the same count.
      properties:
        archived:
          description: Whether this chat is archived (hidden from main chat list)
          example: false
          type: boolean
        isGroup:
          description: |
            Whether this is a group chat (true) or individual chat (false).
            Communities are treated as groups.
          example: false
          type: boolean
        isMarkedSpam:
          description: Whether this chat is marked as spam by the user
          example: false
          type: boolean
        isMuted:
          description: Whether notifications are muted for this chat
          example: false
          type: boolean
        lastMessageTime:
          description: |
            ISO 8601 timestamp of the last message received in this chat.
            Used for sorting chats by recency.
          example: "2025-01-11T14:30:00Z"
          format: date-time
          type: string
        messagesUnread:
          description: |
            Alternative unread count field.
            Contains the same value as `unread`.
          example: 5
          minimum: 0
          type: integer
        muteEndTime:
          description: |
            ISO 8601 timestamp when mute expires (if chat is muted).
            Zero value if not muted or muted indefinitely.
          example: "2025-01-12T14:30:00Z"
          format: date-time
          type: string
        name:
          description: |
            Chat display name.

            **For Individuals**: Contact name (from address book) or WhatsApp push name
            **For Groups**: Group subject/title
            **For Communities**: Community name
          example: João Silva
          type: string
        phone:
          description: |
            WhatsApp JID (Java ID) for the chat.

            **Formats**:
            - Individual: `5511999999999@s.whatsapp.net`
            - Group: `120363047204807488@g.us`
            - Newsletter: `123456789@newsletter`
          example: 5511999999999@s.whatsapp.net
          type: string
        pinned:
          description: Whether this chat is pinned to the top of the chat list
          example: false
          type: boolean
        unread:
          description: Count of unread messages in this chat
          example: 5
          minimum: 0
          type: integer
      required:
      - phone
      - name
      - unread
      - lastMessageTime
      - isMuted
      - muteEndTime
      - isMarkedSpam
      - archived
      - pinned
      - messagesUnread
      - isGroup
      type: object
    ClientTokenDeleteResponse:
      additionalProperties: false
      description: Confirmation that the per-instance Client-Token was removed.
      properties:
        clientAuthToken:
          description: Always `null` after deletion.
          type: "null"
        updated:
          description: Always `true` on success.
          example: true
          type: boolean
      required:
      - clientAuthToken
      - updated
      type: object
    ClientTokenUpdateRequest:
      additionalProperties: false
      description: Request body for setting or updating a per-instance Client-Token.
      properties:
        clientAuthToken:
          description: |
            The token value to assign to this instance. Subscribers will use this value in
            the `Client-Token` header when making instance-scoped API calls.
            Must be a non-empty string. UUIDs are recommended for uniqueness.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
      required:
      - clientAuthToken
      type: object
    ClientTokenUpdateResponse:
      additionalProperties: false
      description: Confirmation that the per-instance Client-Token was set or updated.
      properties:
        clientAuthToken:
          description: The Client-Token value that was stored for this instance.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        updated:
          description: Always `true` on success.
          example: true
          type: boolean
      required:
      - clientAuthToken
      - updated
      type: object
    CommunityAddParticipantsRequest:
      additionalProperties: false
      description: Request body for adding participants to a community announcements
        group.
      properties:
        autoInvite:
          description: Sends private invites for contacts that could not be added
            automatically.
          type: boolean
        communityId:
          description: Community identifier.
          type: string
        phones:
          description: Array of participant phone numbers (E.164) to add.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - autoInvite
      - communityId
      - phones
      type: object
    CommunityAdminMutationRequest:
      additionalProperties: false
      description: Request body for promoting or demoting community administrators.
      properties:
        communityId:
          description: Community identifier.
          type: string
        phones:
          description: Array of participant phone numbers (E.164) targeted by the
            operation.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - communityId
      - phones
      type: object
    CommunityCreateRequest:
      additionalProperties: false
      description: Request body for creating a new community.
      properties:
        description:
          description: Optional description for the community.
          type:
          - string
          - "null"
        name:
          description: Name of the community.
          type: string
      required:
      - name
      type: object
    CommunityCreateResponse:
      additionalProperties: false
      description: Response returned after creating a community.
      properties:
        id:
          description: Community identifier assigned by WhatsApp.
          type: string
        subGroups:
          description: Groups automatically linked to the community (includes the
            announcements group).
          items:
            $ref: '#/components/schemas/CommunitySubGroup'
          type: array
      required:
      - id
      - subGroups
      type: object
    CommunityDescriptionRequest:
      additionalProperties: false
      description: Request body for updating the community description.
      properties:
        communityDescription:
          description: New community description text.
          minLength: 1
          type: string
        communityId:
          description: Community identifier.
          type: string
      required:
      - communityId
      - communityDescription
      type: object
    CommunityLinkRequest:
      additionalProperties: false
      description: Request body for linking groups to a community.
      properties:
        communityId:
          description: Community identifier.
          type: string
        groupsPhones:
          description: Array of group JIDs to link to the community.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - communityId
      - groupsPhones
      type: object
    CommunityListItem:
      additionalProperties: false
      description: Community summary returned by the listing endpoint.
      properties:
        id:
          description: Community identifier.
          type: string
        name:
          description: Community display name.
          type: string
      required:
      - name
      - id
      type: object
    CommunityMetadataResponse:
      additionalProperties: false
      description: Metadata returned for a community.
      properties:
        description:
          description: Community description text.
          type:
          - string
          - "null"
        id:
          description: Community identifier.
          type: string
        name:
          description: Community display name.
          type: string
        subGroups:
          description: Linked groups.
          items:
            $ref: '#/components/schemas/CommunitySubGroup'
          type: array
      required:
      - name
      - id
      - subGroups
      type: object
    CommunityParticipantListRequest:
      additionalProperties: false
      description: Request body for removing participants from a community announcements
        group.
      properties:
        communityId:
          description: Community identifier.
          type: string
        phones:
          description: Array of participant phone numbers (E.164) targeted by the
            operation.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - communityId
      - phones
      type: object
    CommunitySettingsRequest:
      additionalProperties: false
      description: Request body for updating community settings.
      properties:
        communityId:
          description: Community identifier.
          type: string
        whoCanAddNewGroups:
          description: Defines who can add new groups to the community (`admins` or
            `all`).
          enum:
          - admins
          - all
          type: string
      required:
      - communityId
      - whoCanAddNewGroups
      type: object
    CommunitySubGroup:
      additionalProperties: false
      description: Representation of a subgroup linked to a community.
      properties:
        isGroupAnnouncement:
          description: Indicates whether the subgroup is an announcements-only group.
          type: boolean
        name:
          description: Group display name.
          type: string
        phone:
          description: Group JID (suffix `-group`).
          type: string
      required:
      - name
      - phone
      - isGroupAnnouncement
      type: object
    Contact:
      additionalProperties: false
      description: |
        WhatsApp contact information.

        **Data Sources**:
        - Device contacts (if contact is in user's address book)
        - WhatsApp profile data (notify field from push name)
        - VCard information (if contact shared via vcard)

        **Field Availability**:
        - `phone`: Always present
        - `name`, `short`, `vname`: Only if contact is in address book
        - `notify`: Only if user has interacted with contact

        **Privacy Notes**: Contact data respects WhatsApp privacy settings.
        Users who hide their profile will only show notify field.
      properties:
        lid:
          description: |
            LID JID string if the contact is stored as a Linked ID (LID).
            Present only for contacts that were stored with @lid JIDs after
            WhatsApp's LID migration.
          example: 102473725436019:0@lid
          type: string
        name:
          description: |
            Full contact name from device address book.
            Only present if contact exists in user's phone contacts.
          example: João Silva Santos
          type:
          - string
          - "null"
        notify:
          description: |
            Name from WhatsApp settings (push name).
            This is how the user identifies themselves on WhatsApp.
            Present if user has ever interacted with the contact.
          example: João S.
          type:
          - string
          - "null"
        phone:
          description: |
            WhatsApp phone number in international format (without + prefix).
            This is the WhatsApp JID user part.
          example: "5511999999999"
          type: string
        resolvedPhone:
          description: |
            Resolved phone number from the LID mapping store.
            Present only for LID contacts where a phone number mapping was found.
          example: "5511999999999"
          type: string
        short:
          description: |
            First name or nickname from device address book.
            Only present if contact exists in user's phone contacts.
          example: João
          type:
          - string
          - "null"
        vname:
          description: |
            Full name from VCard if contact was shared via contact card.
            Only present if contact was received through VCard sharing.
          example: João Silva Santos
          type:
          - string
          - "null"
      required:
      - phone
      type: object
    ContactAddress:
      additionalProperties: false
      description: Structured address details included in contact vCards
      properties:
        city:
          description: City or locality
          example: São Paulo
          type:
          - string
          - "null"
        country:
          description: Country name
          example: Brasil
          type:
          - string
          - "null"
        extended:
          description: Extended address information such as apartment or suite
          example: Suite 1203
          type:
          - string
          - "null"
        postBox:
          description: Post office box number
          example: "1234"
          type:
          - string
          - "null"
        postalCode:
          description: Postal or ZIP code
          example: 01310-200
          type:
          - string
          - "null"
        region:
          description: State, province or region
          example: SP
          type:
          - string
          - "null"
        street:
          description: Street address
          example: Av. Paulista, 1578
          type:
          - string
          - "null"
        type:
          description: Address type (e.g. HOME, WORK)
          example: WORK
          type:
          - string
          - "null"
      type: object
    ContactInfo:
      additionalProperties: false
      description: Contact information for multiple contacts
      properties:
        address:
          allOf:
          - $ref: '#/components/schemas/ContactAddress'
          description: Structured address details for the vCard
        birthday:
          description: Birthday in YYYY-MM-DD format
          format: date
          type:
          - string
          - "null"
        contactBusinessDescription:
          description: Optional business description of the contact
          example: Sales Manager
          type:
          - string
          - "null"
        contactName:
          description: Full name of the contact
          example: John Doe
          type: string
        contactPhone:
          description: Phone number of the contact in international format
          example: "5511999999999"
          type: string
        email:
          description: Email address associated with the contact
          format: email
          type:
          - string
          - "null"
        firstName:
          description: Given name component for the vCard
          type:
          - string
          - "null"
        jobTitle:
          description: Job title or position
          type:
          - string
          - "null"
        lastName:
          description: Family name component for the vCard
          type:
          - string
          - "null"
        middleName:
          description: Middle name or additional names
          type:
          - string
          - "null"
        namePrefix:
          description: Honorific prefix (e.g. Dr., Mr., Ms.)
          type:
          - string
          - "null"
        nameSuffix:
          description: Honorific suffix (e.g. Jr., Sr.)
          type:
          - string
          - "null"
        nickname:
          description: Nickname or alias for the contact
          type:
          - string
          - "null"
        note:
          description: Additional notes or comments to include in the vCard
          type:
          - string
          - "null"
        organization:
          description: Organization or company name
          type:
          - string
          - "null"
        url:
          description: Website or social media URL for the contact
          format: uri
          type:
          - string
          - "null"
      required:
      - contactName
      - contactPhone
      type: object
    ContactMetadataResponse:
      additionalProperties: false
      description: Metadata about a contact.
      properties:
        about:
          description: Contact status/about text.
          example: Hey there! I am using WhatsApp.
          type: string
        imgUrl:
          description: Full-quality profile picture URL (expires after 48h).
          example: https://pps.whatsapp.net/v/...
          format: uri
          type: string
        name:
          description: Full name of the contact (only returned if the number is saved
            in your contacts).
          example: John Doe
          type: string
        notify:
          description: Display name configured in WhatsApp settings.
          example: John
          type: string
        phone:
          description: Phone number.
          example: "5511999999999"
          type: string
        short:
          description: First name of the contact (only returned if the number is saved
            in your contacts).
          example: John
          type: string
      required:
      - phone
      type: object
    DLQEventResponse:
      properties:
        created_at:
          format: date-time
          type: string
        event_id:
          format: uuid
          type: string
        event_type:
          example: message
          type: string
        failure_reason:
          type: string
        first_attempt_at:
          format: date-time
          type: string
        instance_id:
          format: uuid
          type: string
        last_attempt_at:
          format: date-time
          type: string
        last_error:
          type: string
        moved_to_dlq_at:
          format: date-time
          type: string
        original_metadata:
          description: Original event metadata (only included in single-event detail)
        original_payload:
          description: Original event payload (only included in single-event detail)
        reprocess_attempts:
          type: integer
        reprocess_status:
          enum:
          - pending
          - processing
          - success
          - failed
          - discarded
          type: string
        source_lib:
          example: whatsmeow
          type: string
        total_attempts:
          type: integer
      type: object
    DLQListResponse:
      properties:
        events:
          items:
            $ref: '#/components/schemas/DLQEventResponse'
          type: array
        page:
          description: Current page number
          type: integer
        page_size:
          description: Number of events per page
          type: integer
        total:
          description: Total number of matching events
          type: integer
      type: object
    DLQPurgeResponse:
      properties:
        deleted_count:
          description: Number of resolved events deleted
          format: int64
          type: integer
        success:
          type: boolean
      type: object
    DLQRetryAllResponse:
      properties:
        failed_count:
          description: Number of events that failed to re-enqueue
          type: integer
        retried_count:
          description: Number of events successfully re-enqueued
          type: integer
        success:
          type: boolean
      type: object
    DLQRetryResponse:
      properties:
        event_id:
          format: uuid
          type: string
        message:
          type: string
        success:
          type: boolean
      type: object
    DLQStatsResponse:
      properties:
        by_event_type:
          additionalProperties:
            type: integer
          description: Event counts grouped by event type
          example:
            message: 35
            receipt: 7
          type: object
        by_failure_reason:
          additionalProperties:
            type: integer
          description: Event counts grouped by failure reason
          example:
            HTTP 500: 20
            connection refused: 15
            timeout: 7
          type: object
        by_status:
          additionalProperties:
            type: integer
          description: Event counts grouped by reprocess status
          example:
            discarded: 2
            failed: 3
            pending: 30
            processing: 2
            success: 5
          type: object
        nats_stream:
          description: NATS JetStream DLQ stream stats (only present when NATS is
            enabled)
          nullable: true
          properties:
            bytes:
              format: uint64
              type: integer
            messages:
              format: uint64
              type: integer
            subjects:
              format: uint64
              type: integer
          type: object
        total_events:
          description: Total number of DLQ events for the instance
          example: 42
          type: integer
      type: object
    DeleteMessageResponse:
      additionalProperties: false
      description: Response for delete message operations
      properties:
        message:
          description: Status message
          example: Message deleted successfully
          type: string
        messageId:
          description: ID of the deleted message
          example: 3EB047ED70306656281B34
          type: string
        phone:
          description: Phone number/chat where message was deleted
          example: "554499999999"
          type: string
        success:
          description: Whether the message was deleted successfully
          example: true
          type: boolean
      required:
      - success
      - phone
      - messageId
      type: object
    ErrorResponse:
      properties:
        error:
          type: string
      required:
      - error
      type: object
    EventLocation:
      additionalProperties: false
      description: Event location information
      properties:
        degreesLatitude:
          description: Latitude coordinate
          format: double
          type:
          - number
          - "null"
        degreesLongitude:
          description: Longitude coordinate
          format: double
          type:
          - number
          - "null"
        name:
          description: Location name
          example: Nome do lugar
          type: string
      type: object
    EventPayload:
      additionalProperties: false
      description: Nested event object
      properties:
        callLinkType:
          description: Type of call link for the event
          enum:
          - voice
          - video
          example: voice
          type: string
        canceled:
          default: false
          description: Whether the event is canceled
          example: false
          type: boolean
        dateTime:
          description: Event date and time in ISO 8601 format
          example: "2024-04-29T09:30:53.309Z"
          format: date-time
          type: string
        description:
          description: Event description
          example: Descricao do evento
          type: string
        location:
          $ref: '#/components/schemas/EventLocation'
        name:
          description: Event name/title
          example: Nome do evento
          type: string
      required:
      - name
      - dateTime
      type: object
    ForwardMessageRequest:
      additionalProperties: false
      description: Request to forward a message.
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type: integer
        delayTyping:
          description: Optional typing indicator duration.
          maximum: 15
          minimum: 1
          type: integer
        fromPhone:
          description: Source chat phone number or JID.
          example: "5511888888888"
          type: string
        isGroup:
          default: false
          description: Whether the source chat is a group.
          type: boolean
        messageId:
          description: ID of the message to forward.
          example: 3EB0796DC18B7F954D54
          type: string
        phone:
          description: Destination phone number or JID.
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - messageId
      - fromPhone
      type: object
    ForwardMessageResponse:
      additionalProperties: false
      description: Response after forwarding a message.
      properties:
        messageId:
          description: New message ID.
          type: string
        phone:
          description: Destination phone.
          type: string
        status:
          description: Queue status.
          enum:
          - QUEUE
          - QUEUED
          type: string
        zapiId:
          description: Queue tracking ID.
          type: string
      required:
      - zapiId
      - messageId
      - phone
      - status
      type: object
    GroupAddParticipantsRequest:
      additionalProperties: false
      description: Request body for adding participants to a group.
      properties:
        autoInvite:
          description: Sends private invites for contacts that could not be added
            automatically.
          type: boolean
        groupId:
          description: Group JID (suffix `-group`).
          type: string
        phones:
          description: Array of participant phone numbers (E.164) to add.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - autoInvite
      - groupId
      - phones
      type: object
    GroupCreateRequest:
      additionalProperties: false
      description: Request body for creating a new WhatsApp group.
      properties:
        autoInvite:
          description: When true, sends private invites to contacts that cannot be
            added immediately.
          type: boolean
        groupName:
          description: Display name for the newly created group.
          type: string
        phones:
          description: Array of participant phone numbers (E.164) to add to the group.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - autoInvite
      - groupName
      - phones
      type: object
    GroupCreateResponse:
      additionalProperties: false
      description: Response returned after creating a group.
      properties:
        invitationLink:
          description: Invitation link returned by WhatsApp for the new group.
          format: uri
          type: string
        phone:
          description: Group JID generated by WhatsApp.
          type: string
      required:
      - phone
      - invitationLink
      type: object
    GroupDescriptionRequest:
      additionalProperties: false
      description: Request body for updating a group description.
      properties:
        groupDescription:
          description: New group description text.
          type: string
        groupId:
          description: Group JID (suffix `-group`).
          type: string
      required:
      - groupId
      - groupDescription
      type: object
    GroupInvitationLinkResponse:
      additionalProperties: false
      description: Response containing the current invitation link for a specific
        group.
      properties:
        invitationLink:
          description: Invitation link generated by WhatsApp.
          format: uri
          type: string
        phone:
          description: Group JID that owns the invitation link (suffix `-group`).
          type: string
      required:
      - phone
      - invitationLink
      type: object
    GroupInvitationMetadataResponse:
      additionalProperties: false
      description: Metadata returned when resolving a group invitation link.
      properties:
        contactsCount:
          description: Total number of contacts in the group.
          type: integer
        creation:
          description: Creation timestamp in milliseconds since epoch.
          format: int64
          type: integer
        description:
          description: Group description text.
          type:
          - string
          - "null"
        invitationLink:
          description: Invitation link used in the lookup.
          format: uri
          type: string
        owner:
          description: Phone number of the group creator.
          type: string
        participants:
          description: Array of group participants.
          items:
            $ref: '#/components/schemas/GroupParticipant'
          type: array
        participantsCount:
          description: Total number of participants in the group.
          type: integer
        phone:
          description: Group JID (suffix `-group`).
          type: string
        subject:
          description: Group subject (name).
          type: string
        subjectOwner:
          description: Phone number that owns the invitation subject.
          type:
          - string
          - "null"
        subjectTime:
          description: Timestamp of the last subject change.
          format: int64
          type:
          - integer
          - "null"
      required:
      - phone
      - owner
      - subject
      - creation
      - invitationLink
      - contactsCount
      - participantsCount
      - participants
      type: object
    GroupLeaveRequest:
      additionalProperties: false
      description: Request body for leaving a group.
      properties:
        groupId:
          description: Group JID (suffix `-group`).
          type: string
      required:
      - groupId
      type: object
    GroupListItem:
      additionalProperties: false
      description: summary entry returned by `/groups`.
      properties:
        archived:
          description: Indicates whether the chat is archived.
          type: boolean
        communityId:
          description: JID of the parent community this group belongs to. Null if
            the group is not part of any community.
          type:
          - string
          - "null"
        isCommunity:
          description: Indicates whether the entry is a WhatsApp Community (parent
            group). Communities contain linked sub-groups.
          type: boolean
        isGroup:
          description: Always `true` for group listings.
          type: boolean
        isGroupAnnouncement:
          description: Indicates whether the group is an announcement-only group (only
            admins can send messages).
          type: boolean
        isMarkedSpam:
          description: Indicates whether the chat is marked as spam.
          type: boolean
        isMuted:
          description: '`"0"` when notifications are enabled and `"1"` when muted.'
          type: string
        lastMessageTime:
          description: Millisecond timestamp of the last interaction represented as
            string. May be null if no messages have been exchanged.
          type:
          - string
          - "null"
        messagesUnread:
          description: Deprecated unread counter kept for compatibility.
          type: string
        muteEndTime:
          description: Millisecond timestamp when mute expires (`null` or `-1` for
            indefinitely muted).
          type:
          - string
          - "null"
        name:
          description: Group name.
          type: string
        phone:
          description: Group JID identifier (`{id}-group`).
          type: string
        pinned:
          description: Indicates whether the chat is pinned.
          type: boolean
        unread:
          description: Number of unread messages represented as string for Zé da API
            parity.
          type: string
      required:
      - archived
      - pinned
      - phone
      - unread
      - name
      - lastMessageTime
      - isMuted
      - isMarkedSpam
      - isGroup
      - messagesUnread
      - isGroupAnnouncement
      - isCommunity
      - communityId
      type: object
    GroupMention:
      description: Group mention in WhatsApp communities
      properties:
        phone:
          description: Group JID
          example: 120363XXXXX@g.us
          type: string
        subject:
          description: Group name
          example: Zé da API Community
          type: string
      required:
      - phone
      - subject
      type: object
    GroupMetadataResponse:
      additionalProperties: false
      description: Full metadata payload for a WhatsApp group, including participants
        and invitation link.
      properties:
        adminOnlyMessage:
          description: Indicates whether only admins may send messages.
          type: boolean
        adminOnlySettings:
          description: Indicates whether only admins may change group settings.
          type: boolean
        communityId:
          description: Community identifier when the group belongs to a community.
          type:
          - string
          - "null"
        creation:
          description: Creation timestamp in milliseconds since epoch.
          format: int64
          type: integer
        description:
          description: Group description text.
          type:
          - string
          - "null"
        invitationLink:
          description: Invitation link for the group (available to admins).
          format: uri
          type:
          - string
          - "null"
        invitationLinkError:
          description: Error returned when the invitation link cannot be retrieved.
          type:
          - string
          - "null"
        isGroupAnnouncement:
          description: Indicates whether the group is configured as an announcements
            group.
          type: boolean
        owner:
          description: Phone number of the group creator.
          type: string
        participants:
          description: Array of group participants.
          items:
            $ref: '#/components/schemas/GroupParticipant'
          type: array
        phone:
          description: Group JID (suffix `-group`).
          type: string
        requireAdminApproval:
          description: Indicates whether new participants require admin approval.
          type: boolean
        subject:
          description: Current group subject (name).
          type: string
        subjectOwner:
          description: Phone number of the participant who last changed the subject.
          type:
          - string
          - "null"
        subjectTime:
          description: Timestamp of the last subject change.
          format: int64
          type:
          - integer
          - "null"
      required:
      - phone
      - owner
      - subject
      - creation
      - adminOnlyMessage
      - adminOnlySettings
      - requireAdminApproval
      - isGroupAnnouncement
      - participants
      type: object
    GroupParticipant:
      additionalProperties: false
      description: Participant metadata within a WhatsApp group.
      properties:
        isAdmin:
          description: Indicates whether the participant is an administrator.
          type: boolean
        isSuperAdmin:
          description: Indicates whether the participant is the group owner.
          type: boolean
        lid:
          description: LID value returned by WhatsApp (when available).
          type:
          - string
          - "null"
        name:
          description: Display name for the participant (when available).
          type:
          - string
          - "null"
        phone:
          description: Participant phone number or JID.
          type: string
        short:
          description: Short name provided by WhatsApp (when available).
          type:
          - string
          - "null"
      required:
      - phone
      - isAdmin
      - isSuperAdmin
      type: object
    GroupParticipantListRequest:
      additionalProperties: false
      description: Request body for removing, approving or rejecting group participants.
      properties:
        groupId:
          description: Group JID (suffix `-group`).
          type: string
        phones:
          description: Array of participant phone numbers (E.164) targeted by the
            operation.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - groupId
      - phones
      type: object
    GroupSettingsRequest:
      additionalProperties: false
      description: Request body for updating group settings.
      properties:
        adminOnlyAddMember:
          description: When true, only admins can add members.
          type: boolean
        adminOnlyMessage:
          description: When true, only admins can send messages.
          type: boolean
        adminOnlySettings:
          description: When true, only admins can change group settings.
          type: boolean
        phone:
          description: Group JID (suffix `-group`).
          type: string
        requireAdminApproval:
          description: When true, new participants must be approved by an admin.
          type: boolean
      required:
      - phone
      - adminOnlyMessage
      - adminOnlySettings
      - requireAdminApproval
      - adminOnlyAddMember
      type: object
    GroupUpdateNameRequest:
      additionalProperties: false
      description: Request body for updating an existing group name.
      properties:
        groupId:
          description: Group JID (suffix `-group`).
          type: string
        groupName:
          description: New group name.
          type: string
      required:
      - groupId
      - groupName
      type: object
    GroupUpdatePhotoRequest:
      additionalProperties: false
      description: Request body for updating a group picture.
      properties:
        groupId:
          description: Group JID (suffix `-group`).
          type: string
        groupPhoto:
          description: URL or base64 data URL representing the group picture.
          type: string
      required:
      - groupId
      - groupPhoto
      type: object
    HealthStatusResponse:
      additionalProperties: false
      description: Liveness probe response.
      properties:
        service:
          example: funnelchat
          type: string
        status:
          example: ok
          type: string
      required:
      - status
      - service
      type: object
    InstanceDeviceDetails:
      additionalProperties: false
      properties:
        device_manufacturer:
          type: string
        device_model:
          type: string
        mcc:
          type: string
        mnc:
          type: string
        os_version:
          type: string
        osbuildnumber:
          type: string
        platform:
          type: string
        sessionName:
          type: string
        wa_version:
          type: string
      type: object
    InstanceDeviceResponse:
      additionalProperties: false
      properties:
        device:
          $ref: '#/components/schemas/InstanceDeviceDetails'
        imgUrl:
          description: Direct URL to the current profile picture (null when unavailable).
          type:
          - string
          - "null"
        isBusiness:
          description: Indicates if the paired account is a business profile.
          type: boolean
        name:
          description: Latest push name associated with the instance.
          type: string
        originalDevice:
          description: Raw device/platform identifier reported by WhatsApp (e.g. `smba`,
            `smbi`).
          type: string
        phone:
          description: WhatsApp number linked to the instance.
          type: string
        sessionId:
          description: Device identifier assigned by WhatsApp (0 for the primary phone).
          format: int64
          type: integer
      required:
      - phone
      - imgUrl
      - name
      - device
      - sessionId
      - isBusiness
      type: object
    InstanceListItem:
      additionalProperties: false
      description: instance summary enriched with internal credentials.
      properties:
        autoReadMessage:
          type: boolean
        callRejectAuto:
          type: boolean
        callRejectMessage:
          type:
          - string
          - "null"
        clientAuthToken:
          description: Per-instance Client-Token assigned to this instance, or null
            if only the global token is accepted.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type:
          - string
          - "null"
        connectedCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        created:
          description: ISO-8601 creation timestamp.
          format: date-time
          type: string
        deliveryCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        disconnectedCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        due:
          description: Millisecond timestamp used by Zé da API tooling.
          format: int64
          type: integer
        historySyncCallbackUrl:
          description: Dedicated webhook endpoint for WhatsApp history sync events.
          format: uri
          type:
          - string
          - "null"
        id:
          description: Instance identifier (Zé da API field).
          format: uuid
          type: string
        instanceId:
          description: Internal instance identifier (duplicate of `id` for compatibility).
          format: uuid
          type: string
        instanceToken:
          description: Token required on instance scoped requests.
          type: string
        messageStatusCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        middleware:
          description: Middleware flag returned.
          enum:
          - web
          - mobile
          type: string
        name:
          description: Human friendly name for the instance.
          type: string
        notifySentByMe:
          description: When true, webhook will include sent-by-me events.
          type: boolean
        phoneConnected:
          description: True when a phone is connected (derived from registry snapshot).
          type: boolean
        presenceChatCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        receivedAndDeliveryCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        receivedCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        sessionName:
          description: Underlying WhatsApp session display name.
          type: string
        subscriptionActive:
          type: boolean
        token:
          description: Instance token used by Zé da API clients.
          type: string
        whatsappConnected:
          description: True when the WhatsApp session is connected.
          type: boolean
      required:
      - id
      - token
      - due
      - name
      - created
      - phoneConnected
      - whatsappConnected
      - middleware
      - sessionName
      - callRejectAuto
      - autoReadMessage
      - subscriptionActive
      - notifySentByMe
      - instanceId
      - instanceToken
      type: object
    InstanceListResponse:
      additionalProperties: false
      description: pagination envelope for partner instances.
      properties:
        content:
          items:
            $ref: '#/components/schemas/InstanceListItem'
          type: array
        page:
          minimum: 1
          type: integer
        pageSize:
          minimum: 1
          type: integer
        total:
          minimum: 0
          type: integer
        totalPage:
          minimum: 0
          type: integer
      required:
      - total
      - totalPage
      - pageSize
      - page
      - content
      type: object
    InstanceStatusResponse:
      additionalProperties: false
      description: payload returned by `/instances/{instanceId}/token/{instanceToken}/status`.
      properties:
        connected:
          description: Mirrors Zé da API `connected`, indicating if the instance is
            linked to WhatsApp.
          type: boolean
        error:
          description: Same semantics as Zé da API, detailing why the instance is
            not connected (empty string when everything is ok).
          type:
          - string
          - "null"
        smartphoneConnected:
          description: Matches Zé da API `smartphoneConnected`, signalling if the
            paired device has internet access.
          type: boolean
      required:
      - connected
      - error
      - smartphoneConnected
      type: object
    InteractiveButton:
      additionalProperties: false
      description: |
        Button definition for interactive messages.

        **Usage:**
        - For `quick_reply`: Only `id` and `label` required
        - For `cta_url`: Requires `url` field
        - For `cta_call`: Requires `phone` field
        - For `cta_copy`: Requires `copyCode` field

        **Label Limits:**
        - `quick_reply`: max 20 characters
        - Other types: max 25 characters
      properties:
        copyCode:
          description: Text to copy for cta_copy button type
          example: DISCOUNT10
          type: string
        id:
          description: Unique identifier for the button (used in callbacks)
          example: btn_1
          type: string
        label:
          description: Button display text
          example: Click here
          maxLength: 25
          type: string
        phone:
          description: Phone number for cta_call button type (international format)
          example: "+5511999999999"
          type: string
        type:
          $ref: '#/components/schemas/ButtonType'
        url:
          description: URL for cta_url button type
          example: https://httpbin.org/get
          format: uri
          type: string
      required:
      - type
      - label
      type: object
    InvitationLinkResponse:
      additionalProperties: false
      description: Response containing a regenerated invitation link.
      properties:
        invitationLink:
          description: Invitation link generated by WhatsApp.
          format: uri
          type: string
      required:
      - invitationLink
      type: object
    LIDResolveBatchRequest:
      additionalProperties: false
      description: |
        Request for batch LID resolution.
        Resolves WhatsApp Linked IDs (LIDs) to phone numbers using the local LID store.
      properties:
        lids:
          description: |
            Array of LID strings to resolve.
            Each LID must be a valid WhatsApp LID JID (e.g. "102473725436019:0@lid").
          example:
          - 102473725436019:0@lid
          - 98765432109876:0@lid
          items:
            type: string
          maxItems: 1000
          minItems: 1
          type: array
      required:
      - lids
      type: object
    LIDResolveBatchResponse:
      additionalProperties: false
      description: Response for batch LID resolution.
      properties:
        results:
          items:
            $ref: '#/components/schemas/LIDResolveResult'
          type: array
      required:
      - results
      type: object
    LIDResolveResult:
      additionalProperties: false
      description: Result of a single LID resolution attempt.
      properties:
        lid:
          description: The input LID string
          example: 102473725436019:0@lid
          type: string
        phone:
          description: Resolved phone number (without + prefix), if available
          example: "5511999999999"
          type: string
        phoneJid:
          description: Full phone JID string, if available
          example: 5511999999999@s.whatsapp.net
          type: string
        resolved:
          description: Whether the LID was successfully resolved to a phone number
          example: true
          type: boolean
      required:
      - lid
      - resolved
      type: object
    ListRow:
      additionalProperties: false
      description: |
        Row item in a list/option message.

        **Limits:**
        - Title: max 24 characters
        - Description: max 72 characters
      properties:
        description:
          description: Optional row description
          example: This is the first option
          maxLength: 72
          type: string
        id:
          description: Unique identifier for the row (returned in selection callback)
          example: row_1
          type: string
        title:
          description: Row title displayed to user
          example: Option 1
          maxLength: 24
          type: string
      required:
      - id
      - title
      type: object
    ListSection:
      additionalProperties: false
      description: |
        Section containing rows in a button list message.

        **Limits:**
        - Title: max 24 characters
        - Rows per section: max 10
      properties:
        rows:
          description: List of rows in this section
          items:
            $ref: '#/components/schemas/ListRow'
          maxItems: 10
          minItems: 1
          type: array
        title:
          description: Section title displayed as header
          example: Choose an option
          maxLength: 24
          type: string
      required:
      - title
      - rows
      type: object
    MediaStatsResponse:
      additionalProperties: false
      description: Statistics about media storage system
      properties:
        base_path:
          description: Base directory path for media storage
          example: /data/media
          type: string
        public_base_url:
          description: Public base URL for media access
          example: https://api.example.com/media
          type: string
        total_bytes:
          description: Total size of all media files in bytes
          example: 1073741824
          format: int64
          type: integer
        total_files:
          description: Total number of media files stored
          example: 1234
          type: integer
        url_expiry:
          description: Default URL expiration duration
          example: 24h0m0s
          type: string
      required:
      - total_files
      - total_bytes
      - base_path
      - url_expiry
      - public_base_url
      type: object
    MessageQueuedResponse:
      additionalProperties: false
      description: Response after successfully queuing an interactive message.
      properties:
        data:
          properties:
            messageId:
              description: Message ID (same as queueId until sent)
              example: 123e4567-e89b-12d3-a456-426614174001
              type: string
            queueId:
              description: Queue entry ID for tracking
              example: 123e4567-e89b-12d3-a456-426614174000
              format: uuid
              type: string
            status:
              description: Queue status
              enum:
              - queued
              - processing
              - sent
              - failed
              example: queued
              type: string
          required:
          - queueId
          - messageId
          - status
          type: object
        message:
          description: Status message
          example: Message queued successfully
          type: string
        success:
          description: Whether the message was queued successfully
          example: true
          type: boolean
      required:
      - success
      - message
      - data
      type: object
    ModifyBlockedRequest:
      additionalProperties: false
      description: Request to block or unblock a contact.
      properties:
        action:
          description: Action to perform.
          enum:
          - block
          - unblock
          example: block
          type: string
        phone:
          description: Phone number to block/unblock.
          example: "5511999999999"
          type: string
      required:
      - phone
      - action
      type: object
    ModifyBlockedResponse:
      additionalProperties: false
      description: Response after blocking or unblocking a contact.
      properties:
        blocked:
          description: Current block status.
          type: boolean
        message:
          description: Optional message.
          type: string
        phone:
          description: The phone number affected.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - phone
      - blocked
      type: object
    ModifyChatRequest:
      additionalProperties: false
      description: |
        Request body for modifying chat state.

        **Supported Actions:**
        - read: Mark chat as read
        - archive: Archive the chat
        - unarchive: Unarchive the chat
        - pin: Pin the chat
        - unpin: Unpin the chat
        - mute: Mute notifications (8 hours default)
        - unmute: Unmute notifications
        - clear: Clear chat messages (not supported by whatsmeow)
        - delete: Delete the chat
      properties:
        action:
          description: Action to perform on the chat
          enum:
          - read
          - archive
          - unarchive
          - pin
          - unpin
          - mute
          - unmute
          - clear
          - delete
          example: delete
          type: string
        phone:
          description: Phone number or group JID
          example: "554499999999"
          type: string
      required:
      - phone
      - action
      type: object
    ModifyChatResponse:
      additionalProperties: false
      description: Response for modify-chat operations
      properties:
        action:
          description: Action that was performed
          example: delete
          type: string
        message:
          description: Status message
          example: Chat delete successful
          type: string
        phone:
          description: Phone number that was modified
          example: "554499999999"
          type: string
        success:
          description: Whether the operation was successful
          example: true
          type: boolean
      required:
      - success
      - phone
      - action
      type: object
    NewsletterAdminActionRequest:
      additionalProperties: false
      description: Request body for admin invite management within a channel.
      properties:
        phone:
          description: Phone number of the target administrator.
          type: string
      required:
      - phone
      type: object
    NewsletterCreateRequest:
      additionalProperties: false
      description: Request body for creating a WhatsApp channel (newsletter).
      properties:
        description:
          description: Optional channel description.
          type:
          - string
          - "null"
        name:
          description: Channel display name.
          type: string
      required:
      - name
      type: object
    NewsletterCreateResponse:
      additionalProperties: false
      description: Response returned after creating a channel.
      properties:
        id:
          description: Channel identifier (always suffixed with `@newsletter`).
          type: string
      required:
      - id
      type: object
    NewsletterIdRequest:
      additionalProperties: false
      description: Request body for operations that only require the channel identifier.
      properties:
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
      required:
      - id
      type: object
    NewsletterMetadata:
      additionalProperties: false
      description: Metadata describing a channel (newsletter).
      properties:
        creationTime:
          description: Unix timestamp in seconds represented as string.
          type: string
        description:
          description: Channel description text.
          type:
          - string
          - "null"
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
        inviteLink:
          description: Invitation link for the channel.
          format: uri
          type:
          - string
          - "null"
        name:
          description: Channel display name.
          type: string
        picture:
          description: URL for the channel avatar.
          format: uri
          type:
          - string
          - "null"
        preview:
          description: URL for the preview image.
          format: uri
          type:
          - string
          - "null"
        state:
          description: Channel state reported by WhatsApp (e.g. `ACTIVE`, `NON_EXISTING`).
          type: string
        subscribersCount:
          description: Total subscriber count represented as string.
          type: string
        verification:
          description: Channel verification status (`VERIFIED`, `UNVERIFIED`).
          type: string
        viewMetadata:
          additionalProperties: false
          description: Metadata about how the authenticated account sees the channel.
          properties:
            mute:
              description: Indicates whether the channel is muted (`ON`, `OFF`).
              type: string
            role:
              description: Role of the authenticated account (`OWNER`, `SUBSCRIBER`).
              type: string
          required:
          - mute
          - role
          type: object
      required:
      - id
      - creationTime
      - state
      - name
      - subscribersCount
      - verification
      - viewMetadata
      type: object
    NewsletterSearchFilters:
      additionalProperties: false
      description: Filters applied when searching for channels.
      properties:
        countryCodes:
          description: List of ISO country codes used to filter channels.
          items:
            type: string
          minItems: 1
          type: array
      required:
      - countryCodes
      type: object
    NewsletterSearchItem:
      additionalProperties: false
      description: Single result entry returned by the search endpoint.
      properties:
        description:
          description: Channel description snippet.
          type:
          - string
          - "null"
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
        name:
          description: Channel display name.
          type: string
        picture:
          description: Channel picture URL when available.
          format: uri
          type:
          - string
          - "null"
        subscribersCount:
          description: Total subscriber count represented as string.
          type: string
      required:
      - id
      - name
      - subscribersCount
      type: object
    NewsletterSearchRequest:
      additionalProperties: false
      description: Request body for searching public channels.
      properties:
        filters:
          $ref: '#/components/schemas/NewsletterSearchFilters'
        limit:
          description: Maximum number of results to return.
          minimum: 1
          type: integer
        searchText:
          description: Optional free text search term.
          type:
          - string
          - "null"
        view:
          description: Optional view name used by WhatsApp (`RECOMMENDED`, `TRENDING`,
            `POPULAR`, `NEW`).
          enum:
          - RECOMMENDED
          - TRENDING
          - POPULAR
          - NEW
          type: string
      required:
      - limit
      - filters
      type: object
    NewsletterSearchResponse:
      additionalProperties: false
      description: Response payload returned by the newsletter search endpoint.
      properties:
        cursor:
          description: Cursor returned by WhatsApp for subsequent pages (currently
            always null).
          type:
          - string
          - "null"
        data:
          description: List of channels matching the search criteria.
          items:
            $ref: '#/components/schemas/NewsletterSearchItem'
          type: array
      required:
      - cursor
      - data
      type: object
    NewsletterSettingsRequest:
      additionalProperties: false
      description: Request body for updating newsletter settings.
      properties:
        reactionCodes:
          description: Restriction applied to reactions within the channel.
          enum:
          - basic
          - all
          type: string
      required:
      - reactionCodes
      type: object
    NewsletterTransferOwnershipRequest:
      additionalProperties: false
      description: Request body for transferring channel ownership.
      properties:
        phone:
          description: Phone number of the participant who will become the new owner.
          type: string
        quitAdmin:
          default: false
          description: When true, the current owner leaves the admin role after transfer.
          type: boolean
      required:
      - phone
      type: object
    NewsletterTransferOwnershipResponse:
      additionalProperties: false
      description: Response returned after attempting to transfer channel ownership.
      properties:
        message:
          description: Optional error message when the transfer fails.
          type:
          - string
          - "null"
        value:
          description: Indicates whether the transfer succeeded.
          type: boolean
      required:
      - value
      type: object
    NewsletterUpdateDescriptionRequest:
      additionalProperties: false
      description: Request body for updating the channel description.
      properties:
        description:
          description: New channel description.
          type: string
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
      required:
      - id
      - description
      type: object
    NewsletterUpdateNameRequest:
      additionalProperties: false
      description: Request body for updating the channel name.
      properties:
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
        name:
          description: New channel name.
          type: string
      required:
      - id
      - name
      type: object
    NewsletterUpdatePictureRequest:
      additionalProperties: false
      description: Request body for updating the channel profile picture.
      properties:
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
        pictureUrl:
          description: URL or base64 data URL for the new picture.
          type: string
      required:
      - id
      - pictureUrl
      type: object
    NotifySentByMeRequest:
      additionalProperties: false
      properties:
        notifySentByMe:
          type: boolean
      required:
      - notifySentByMe
      type: object
    OperationStatusResponse:
      additionalProperties: false
      properties:
        status:
          type: string
      required:
      - status
      type: object
    PIXKeyType:
      description: |
        Type of PIX key for Brazilian payment system.

        **PIX Key Types:**
        - `CPF` - Brazilian individual taxpayer ID (11 digits)
        - `CNPJ` - Brazilian company taxpayer ID (14 digits)
        - `EMAIL` - Email address
        - `PHONE` - Phone number with country code
        - `EVP` - Random PIX key (UUID format)
      enum:
      - CPF
      - CNPJ
      - EMAIL
      - PHONE
      - EVP
      example: CPF
      type: string
    PIXPayment:
      additionalProperties: false
      description: |
        PIX payment information for Brazilian payment messages.

        **Required Fields:**
        - `keyType`: Type of PIX key
        - `key`: The PIX key value
        - `name`: Beneficiary name
        - `amount`: Payment amount in BRL

        **Optional Fields:**
        - `description`: Payment description
        - `merchantCity`: Merchant city for PIX
        - `merchantName`: Merchant name
        - `txId`: Transaction identifier
      properties:
        amount:
          description: Payment amount in BRL (Brazilian Real)
          example: 99.9
          format: float
          minimum: 0.01
          type: number
        description:
          description: Payment description/memo
          example: Product purchase
          type: string
        key:
          description: PIX key value (format depends on keyType)
          example: "12345678900"
          type: string
        keyType:
          $ref: '#/components/schemas/PIXKeyType'
        merchantCity:
          description: Merchant city for PIX QR code
          example: SAO PAULO
          type: string
        merchantName:
          description: Merchant name for PIX QR code
          example: My Store
          type: string
        name:
          description: Beneficiary name (who receives the payment)
          example: John Doe
          type: string
        txId:
          description: Transaction identifier for tracking
          example: TX123456789
          type: string
      required:
      - keyType
      - key
      - name
      - amount
      type: object
    PartnerInstanceCreateRequest:
      additionalProperties: false
      properties:
        autoReadMessage:
          description: When true, messages are marked as read automatically.
          type: boolean
        businessDevice:
          default: true
          type: boolean
        callRejectAuto:
          description: When true, the instance rejects calls automatically.
          type: boolean
        callRejectMessage:
          description: Message returned when a call is rejected automatically.
          type: string
        clientAuthToken:
          description: |
            Optional per-instance Client-Token. When set, subscribers can authenticate
            instance-scoped API calls using this token instead of the global CLIENT_AUTH_TOKEN.
            If omitted, only the global token is accepted for this instance.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
        connectedCallbackUrl:
          format: uri
          type: string
        deliveryCallbackUrl:
          format: uri
          type: string
        disconnectedCallbackUrl:
          format: uri
          type: string
        historySyncCallbackUrl:
          description: Dedicated webhook endpoint for WhatsApp history sync events.
          format: uri
          type: string
        isDevice:
          default: false
          type: boolean
        messageStatusCallbackUrl:
          format: uri
          type: string
        name:
          description: Display name for the instance.
          type: string
        notifySentByMe:
          default: false
          type: boolean
        presenceChatCallbackUrl:
          format: uri
          type: string
        receivedAndDeliveryCallbackUrl:
          format: uri
          type: string
        receivedCallbackUrl:
          format: uri
          type: string
        sessionName:
          description: Optional session identifier used by partners.
          type: string
      required:
      - name
      type: object
    PartnerInstanceCreateResponse:
      additionalProperties: false
      properties:
        autoReadMessage:
          type: boolean
        callRejectAuto:
          type: boolean
        callRejectMessage:
          type:
          - string
          - "null"
        clientAuthToken:
          description: Per-instance Client-Token if one was provided during creation,
            or null.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type:
          - string
          - "null"
        createdAt:
          format: date-time
          type: string
        due:
          description: Millisecond timestamp returned.
          format: int64
          type: integer
        id:
          description: identifier (duplicate of instanceId).
          format: uuid
          type: string
        instanceId:
          format: uuid
          type: string
        instanceToken:
          type: string
        middleware:
          enum:
          - web
          - mobile
          type: string
        name:
          type: string
        sessionName:
          type: string
        subscriptionActive:
          type: boolean
        token:
          description: instance token.
          type: string
        webhooks:
          $ref: '#/components/schemas/WebhookSettings'
      required:
      - id
      - token
      - due
      - instanceId
      - name
      - sessionName
      - instanceToken
      - subscriptionActive
      - createdAt
      type: object
    PhoneCodeResponse:
      additionalProperties: false
      properties:
        code:
          description: Six-character pairing code formatted with dash (e.g., `ABCD-EF`).
          type: string
      required:
      - code
      type: object
    PhoneExistsBatchRequest:
      additionalProperties: false
      description: |
        request for batch phone number validation.
        Allows validating up to 50,000 phone numbers in a single request.
      properties:
        phones:
          description: |
            Array of phone numbers to validate.
            Each number must be in international format (DDI DDD NUMBER).
            Numbers only - no formatting, spaces, or masks.
          example:
          - "554499999999"
          - "554488888888"
          items:
            pattern: ^\d+$
            type: string
          maxItems: 50000
          minItems: 1
          type: array
      required:
      - phones
      type: object
    PhoneExistsBatchResponse:
      additionalProperties: false
      description: |
        response for batch phone number validation.
        Contains the validation result for each phone number in the batch.
      properties:
        exists:
          description: true if the phone number has WhatsApp, false otherwise
          example: true
          type: boolean
        inputPhone:
          description: Phone number as sent in the request (may or may not include
            ninth digit)
          example: "554499999999"
          type: string
        outputPhone:
          description: |
            Formatted phone number from WhatsApp response.
            Reflects the WhatsApp registration and includes ninth digit if applicable.
          example: "554499999999"
          type: string
      required:
      - exists
      - inputPhone
      - outputPhone
      type: object
    PhoneExistsResponse:
      additionalProperties: false
      description: |
        response for phone number validation.
        Returns whether a phone number is registered on WhatsApp along with phone and LID.
      properties:
        exists:
          description: true if the phone number has WhatsApp, false otherwise
          example: true
          type: boolean
        lid:
          description: LID (Linked ID) if available, null otherwise
          example: 140712372899859@lid
          type:
          - string
          - "null"
        phone:
          description: Phone number if exists on WhatsApp, null otherwise
          example: "5521979232690"
          type:
          - string
          - "null"
      required:
      - exists
      type: object
    PinMessageRequest:
      additionalProperties: false
      description: Request to pin or unpin a chat.
      properties:
        phone:
          description: Phone number or JID of the chat to pin.
          example: "5511999999999"
          type: string
        pin:
          default: true
          description: True to pin, false to unpin.
          type: boolean
      required:
      - phone
      type: object
    PinMessageResponse:
      additionalProperties: false
      description: Response after pinning or unpinning a chat.
      properties:
        message:
          description: Optional message.
          type: string
        phone:
          description: The chat that was pinned/unpinned.
          type: string
        pinned:
          description: Current pin status.
          type: boolean
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - phone
      - pinned
      type: object
    PollOption:
      additionalProperties: false
      description: A single poll option
      properties:
        name:
          description: Option text
          example: Zé da API
          type: string
      required:
      - name
      type: object
    PrivacySettingsResponse:
      additionalProperties: false
      description: Current privacy settings for the connected account.
      properties:
        callAdd:
          description: Who can call you.
          enum:
          - all
          - known
          example: all
          type: string
        groupAdd:
          description: Who can add you to groups.
          enum:
          - all
          - contacts
          - contact_blacklist
          - none
          example: contacts
          type: string
        lastSeen:
          description: Who can see your last seen.
          enum:
          - all
          - contacts
          - contact_blacklist
          - none
          example: contacts
          type: string
        online:
          description: Online presence visibility.
          enum:
          - all
          - match_last_seen
          example: all
          type: string
        profile:
          description: Who can see your profile photo.
          enum:
          - all
          - contacts
          - contact_blacklist
          - none
          example: contacts
          type: string
        readReceipts:
          description: Read receipts setting.
          enum:
          - all
          - none
          example: all
          type: string
        status:
          description: Who can see your status.
          enum:
          - all
          - contacts
          - contact_blacklist
          - none
          example: contacts
          type: string
      type: object
    ProfilePictureResponse:
      additionalProperties: false
      description: Profile picture information.
      properties:
        id:
          description: Picture ID.
          type: string
        type:
          description: Picture type (image, preview).
          enum:
          - image
          - preview
          type: string
        url:
          description: Direct URL to the profile picture.
          example: https://pps.whatsapp.net/v/t61...
          format: uri
          type: string
      required:
      - url
      type: object
    PrometheusMetrics:
      description: |
        Prometheus exposition format metrics.
        Contains application metrics including:
        - HTTP request counts and latencies
        - Message queue statistics
        - WhatsApp connection status
        - Event processing metrics
      example: |
        # HELP http_requests_total Total HTTP requests
        # TYPE http_requests_total counter
        http_requests_total{method="GET",path="/health"} 1234
      type: string
    ProxyConfig:
      properties:
        healthFailures:
          description: Consecutive health check failures
          type: integer
        healthStatus:
          description: Current proxy health status
          enum:
          - healthy
          - unhealthy
          - unknown
          type: string
        lastHealthCheck:
          description: Timestamp of last health check
          format: date-time
          nullable: true
          type: string
        noMedia:
          type: boolean
        noWebsocket:
          type: boolean
        onlyLogin:
          type: boolean
        proxyEnabled:
          description: Whether proxy is active for this instance
          type: boolean
        proxyUrl:
          description: Configured proxy URL (credentials masked)
          nullable: true
          type: string
      type: object
    ProxyHealthResponse:
      properties:
        logs:
          items:
            properties:
              checkedAt:
                format: date-time
                type: string
              errorMessage:
                nullable: true
                type: string
              id:
                type: integer
              instanceId:
                format: uuid
                type: string
              latencyMs:
                nullable: true
                type: integer
              proxyUrl:
                type: string
              status:
                enum:
                - healthy
                - unhealthy
                - timeout
                - unreachable
                type: string
            type: object
          type: array
        proxy:
          $ref: '#/components/schemas/ProxyConfig'
      type: object
    ProxySwapRequest:
      properties:
        proxyUrl:
          description: New proxy URL to hot-swap to
          example: socks5://new-proxy.example.com:1080
          type: string
      required:
      - proxyUrl
      type: object
    ProxyTestRequest:
      properties:
        proxyUrl:
          description: Proxy URL to test
          example: http://proxy.example.com:8080
          type: string
      required:
      - proxyUrl
      type: object
    ProxyTestResponse:
      properties:
        error:
          description: Error message if unreachable
          type: string
        latencyMs:
          description: Round-trip latency in milliseconds
          type: integer
        reachable:
          description: Whether the proxy can reach WhatsApp servers
          type: boolean
      type: object
    ProxyUpdateRequest:
      properties:
        noMedia:
          default: false
          description: Do not use proxy for media uploads/downloads
          type: boolean
        noWebsocket:
          default: false
          description: Do not use proxy for websocket connections
          type: boolean
        onlyLogin:
          default: false
          description: Use proxy only for pre-login websocket
          type: boolean
        proxyUrl:
          description: Proxy URL (http, https, or socks5 scheme)
          example: socks5://user:pass@proxy.example.com:1080
          type: string
      required:
      - proxyUrl
      type: object
    QRCodeImageResponse:
      additionalProperties: false
      properties:
        image:
          description: PNG image encoded as data URL (`data:image/png;base64,...`).
          type: string
      required:
      - image
      type: object
    QueueCancelResponse:
      additionalProperties: false
      description: Message cancellation response
      properties:
        message:
          description: Operation confirmation message
          example: Message cancelled successfully
          type: string
      required:
      - message
      type: object
    QueueClearResponse:
      additionalProperties: false
      description: Queue clear operation response
      properties:
        message:
          description: Operation confirmation message
          example: Queue cleared successfully
          type: string
      required:
      - message
      type: object
    QueueCountResponse:
      additionalProperties: false
      description: Queue count response
      properties:
        count:
          description: Number of messages in queue
          example: 42
          type: integer
      required:
      - count
      type: object
    QueueListResponse:
      description: Array of queue messages
      items:
        $ref: '#/components/schemas/QueueMessageResponse'
      type: array
    QueueMessageResponse:
      additionalProperties: false
      description: Represents a message in the queue with format
      properties:
        _id:
          description: Message ID (same as zaapId)
          example: 39BB1684570F00E91090F6BBC7EE7646
          type: string
        attempt:
          description: Current attempt number (0-based)
          example: 0
          type: integer
        created:
          description: Unix timestamp in milliseconds
          example: 1624977905648
          format: int64
          type: integer
        delayMessage:
          description: Delay in seconds before sending
          example: 5
          format: int64
          type: integer
        delayTyping:
          description: Typing indicator duration in seconds
          example: 3
          format: int64
          type: integer
        errors:
          description: List of error messages (if any)
          items:
            type:
            - string
            - "null"
          type: array
        instanceId:
          description: Instance UUID
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        maxAttempts:
          description: Maximum retry attempts
          example: 3
          type: integer
        message:
          description: Message text content (only for text messages)
          example: Hello from Zé da API
          type:
          - string
          - "null"
        messageId:
          description: WhatsApp message ID (after sending)
          example: 7AD29EAA5EF34C301F0B
          type: string
        messageType:
          description: Type of message
          enum:
          - text
          - image
          - audio
          - video
          - document
          example: text
          type: string
        phone:
          description: Recipient phone/group/newsletter
          example: "5511999999999"
          type: string
        sequenceNumber:
          description: FIFO sequence number
          example: 1
          format: int64
          type: integer
        status:
          description: Current job status
          enum:
          - available
          - scheduled
          - running
          - completed
          - failed
          - cancelled
          - discarded
          example: available
          type: string
        zaapId:
          description: Zé da API message tracking ID
          example: 39BB1684570F00E91090F6BBC7EE7646
          type: string
      required:
      - _id
      - zaapId
      - messageId
      - instanceId
      - phone
      - delayMessage
      - delayTyping
      - created
      type: object
    ReactionResponse:
      additionalProperties: false
      description: Response after sending or removing a reaction.
      properties:
        message:
          description: Optional message.
          type: string
        messageId:
          description: The message ID that was reacted to.
          type: string
        reaction:
          description: The reaction that was sent (empty if removed).
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - messageId
      type: object
    ReadMessageRequest:
      additionalProperties: false
      description: Request to mark messages as read.
      properties:
        messageIds:
          description: List of message IDs to mark as read.
          example:
          - 3EB0796DC18B7F954D54
          - 3EB0796DC18B7F954D55
          items:
            type: string
          type: array
        phone:
          description: Phone number or JID of the chat.
          example: "5511999999999"
          type: string
      required:
      - phone
      - messageIds
      type: object
    ReadMessageResponse:
      additionalProperties: false
      description: Response after marking messages as read.
      properties:
        markedCount:
          description: Number of messages marked as read.
          type: integer
        message:
          description: Optional message.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - markedCount
      type: object
    ReadinessComponentStatus:
      additionalProperties: false
      description: Status information for a single dependency checked by the readiness
        probe.
      properties:
        circuit_state:
          description: Circuit breaker state reported by the lock manager (when available).
          type:
          - string
          - "null"
        duration_ms:
          description: Time spent executing the check in milliseconds.
          format: int64
          type: integer
        error:
          type:
          - string
          - "null"
        status:
          enum:
          - healthy
          - degraded
          - unhealthy
          type: string
      required:
      - status
      type: object
    ReadinessResponse:
      additionalProperties: false
      description: Readiness probe payload containing aggregated dependency status.
      properties:
        checks:
          additionalProperties:
            $ref: '#/components/schemas/ReadinessComponentStatus'
          description: Map of dependency name to component status (e.g. `database`,
            `redis`).
          type: object
        observed_at:
          format: date-time
          type: string
        ready:
          type: boolean
      required:
      - ready
      - observed_at
      - checks
      type: object
    RemoveContactRequest:
      additionalProperties: false
      description: Request to remove a contact from the address book.
      properties:
        phone:
          description: Phone number in international format.
          example: "5511999999999"
          type: string
      required:
      - phone
      type: object
    RemoveContactResponse:
      additionalProperties: false
      description: Response after removing a contact.
      properties:
        message:
          description: Status message.
          type: string
        phone:
          description: The phone number of the contact.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - phone
      - message
      type: object
    SendAudioRequest:
      additionalProperties: false
      description: Request body for sending audio/voice messages
      properties:
        audio:
          description: Audio URL (http/https) or base64 data URI (data:audio/ogg;base64,...)
          example: https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3
          type: string
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional "recording audio" indicator duration in seconds (1-15
            seconds)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        mentioned:
          description: Array of phone numbers to mention
          example:
          - "5511999999999"
          - "5511888888888"
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members without listing them
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages, reply in private to sender
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        viewOnce:
          default: false
          description: If true, audio can only be played once
          type: boolean
      required:
      - phone
      - audio
      type: object
    SendAudioStatusRequest:
      additionalProperties: false
      description: |
        Request body for sending audio/voice note to WhatsApp Status/Stories.

        **Status Broadcasting**: Audio is automatically broadcast to all contacts
        who can view your status based on your privacy settings.

        **Key Features**:
        - Audio URL or base64 data URI support
        - Automatic waveform generation (64 samples) for visual bars
        - Voice note (PTT) format with waveform visualization
        - Automatic conversion to Opus/OGG if needed
        - Optional custom message ID for tracking

        **Waveform Visualization**: The audio is processed to generate
        64 amplitude samples (0-100 range) that WhatsApp displays as
        the classic "ondinhas" (wave bars) in the voice note player.

        **Supported Formats**: OGG (Opus), MP3, WAV, M4A, AAC
      properties:
        audio:
          description: |
            Audio URL (http/https) or base64 data URI.

            **Examples**:
            - URL: `https://example.com/audio.mp3`
            - Base64: `data:audio/ogg;base64,T2dnUwACAA...`

            **Recommended**: OGG Opus format for best compatibility
          example: https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3
          type: string
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        messageId:
          description: |
            Optional custom message ID for tracking.
            If not provided, WhatsApp generates one automatically.
          example: custom-audio-status-123
          type:
          - string
          - "null"
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - audio
      type: object
    SendButtonActionsRequest:
      additionalProperties: false
      description: |
        Request body for sending button actions messages.

        **Features:**
        - CTA buttons (URL, Call, Copy)
        - Optional image header
        - Quick reply buttons

        **Button Types:**
        - `quick_reply` - Simple reply button
        - `cta_url` - Opens a URL
        - `cta_call` - Initiates a phone call
        - `cta_copy` - Copies text to clipboard

        **Limits:**
        - Max 3 buttons
        - Label: max 25 chars (20 for quick_reply)
        - Title: max 60 chars
        - Message: max 1024 chars
        - Footer: max 60 chars

        **Message Queue:** Messages are queued per recipient with FIFO ordering.
      properties:
        buttons:
          description: Action buttons (max 3)
          items:
            $ref: '#/components/schemas/ActionButton'
          maxItems: 3
          minItems: 1
          type: array
        delayMessage:
          description: Delay in seconds before sending. Any non-negative integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 0
          minimum: 0
          type: integer
        footer:
          description: Footer text
          example: Thank you
          maxLength: 60
          type: string
        image:
          description: |
            Optional header image URL or base64.

            **Formats:**
            - URL: `https://picsum.photos/600/400.jpg`
            - Base64: `data:image/png;base64,...`
          example: https://picsum.photos/600/400.jpg
          type: string
        message:
          description: Message body text
          example: Please take one of the following actions
          maxLength: 1024
          type: string
        messageId:
          description: Optional custom message ID for tracking
          format: uuid
          type: string
        phone:
          description: Recipient phone number in international format
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        title:
          description: Message title
          example: Action Required
          maxLength: 60
          type: string
      required:
      - phone
      - buttons
      type: object
    SendButtonListRequest:
      additionalProperties: false
      description: |
        Request body for sending simple reply button messages.

        **Features:**
        - Simple reply buttons (1-3 buttons)
        - Optional header image/video
        - Quick selection callbacks

        **Limits:**
        - Max 3 buttons
        - Title: max 60 chars
        - Message: max 1024 chars
        - Footer: max 60 chars
        - Button title: max 20 chars

        **Message Queue:** Messages are queued per recipient with FIFO ordering.
      properties:
        buttons:
          description: Simple reply buttons (1-3 buttons)
          items:
            $ref: '#/components/schemas/Button'
          maxItems: 3
          minItems: 1
          type: array
        delayMessage:
          description: Delay in seconds before sending. Any non-negative integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 0
          minimum: 0
          type: integer
        delayTyping:
          description: Typing indicator delay in seconds (0-15)
          example: 0
          maximum: 15
          minimum: 0
          type: integer
        footer:
          description: Footer text at the bottom of the message (optional)
          example: Powered by our service
          maxLength: 60
          type: string
        image:
          description: |
            Optional header image URL or base64.

            **Formats:**
            - URL: `https://picsum.photos/600/400.jpg`
            - Base64: `data:image/png;base64,...`
          example: https://picsum.photos/600/400.jpg
          type: string
        message:
          description: Message body text
          example: Please select one of the options below
          maxLength: 1024
          type: string
        messageId:
          description: Optional custom message ID for tracking/reply
          type: string
        phone:
          description: |
            Recipient phone number in international format (without + prefix).

            **Examples:**
            - Individual: `5511999999999` (Brazil mobile)
            - Group: `120363047204807488@g.us`
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        title:
          description: Message title displayed at the top (optional)
          example: Choose an option
          maxLength: 60
          type: string
        video:
          description: |
            Optional header video URL or base64.

            **Formats:**
            - URL: `https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4`
            - Base64: `data:video/mp4;base64,...`
          example: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
          type: string
      required:
      - phone
      - message
      - buttons
      type: object
    SendButtonOTPRequest:
      additionalProperties: false
      description: |
        Request body for sending OTP (One-Time Password) messages.

        **Features:**
        - One-tap copy button
        - Verification code display
        - 2FA/Authentication flows

        **Use Cases:**
        - Login verification
        - Password reset
        - Two-factor authentication
        - Account verification

        **Message Queue:** Messages are queued per recipient with FIFO ordering.
      properties:
        code:
          description: OTP code to copy (max 20 chars)
          example: "123456"
          maxLength: 20
          type: string
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 0
          minimum: 1
          type: integer
        delayTyping:
          description: Typing indicator delay in seconds (1-15)
          example: 0
          maximum: 15
          minimum: 1
          type: integer
        footer:
          description: Optional footer text
          example: Code expires in 5 minutes
          maxLength: 60
          type: string
        message:
          description: Message body containing OTP context (required)
          example: Your verification code is below. Do not share it with anyone.
          maxLength: 1024
          type: string
        messageId:
          description: Optional custom message ID for tracking
          format: uuid
          type: string
        phone:
          description: Recipient phone number in international format
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        title:
          description: Optional header text
          example: Verification Code
          maxLength: 60
          type: string
      required:
      - phone
      - message
      - code
      type: object
    SendButtonPIXRequest:
      additionalProperties: false
      description: |
        Request body for sending PIX payment messages.

        **Features:**
        - PIX QR code generation
        - Copy-paste PIX code
        - Multiple PIX key types

        **PIX Key Types:**
        - `CPF` - Brazilian individual taxpayer ID
        - `CNPJ` - Brazilian company taxpayer ID
        - `EMAIL` - Email address
        - `PHONE` - Phone number
        - `EVP` - Random PIX key (UUID format)

        **Message Queue:** Messages are queued per recipient with FIFO ordering.
      properties:
        amount:
          description: Payment amount in BRL (optional)
          example: 99.9
          format: float
          minimum: 0.01
          type: number
        delayMessage:
          description: Delay in seconds before sending. Any non-negative integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 0
          minimum: 0
          type: integer
        delayTyping:
          description: Typing indicator delay in seconds (0-15)
          example: 0
          maximum: 15
          minimum: 0
          type: integer
        message:
          description: Message body (optional, default "Pagamento via PIX")
          example: Please complete your payment
          maxLength: 1024
          type: string
        messageId:
          description: Optional custom message ID for tracking/reply
          type: string
        name:
          description: Beneficiary name (optional)
          example: John Doe
          type: string
        phone:
          description: Recipient phone number in international format
          example: "5511999999999"
          type: string
        pixKey:
          description: PIX key value (format depends on key type)
          example: "12345678900"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        transactionId:
          description: Transaction identifier for tracking (optional)
          example: TX123456789
          type: string
        type:
          $ref: '#/components/schemas/PIXKeyType'
      required:
      - phone
      - pixKey
      - type
      type: object
    SendCarouselRequest:
      additionalProperties: false
      description: |
        Request body for sending carousel messages.

        **Features:**
        - Multiple swipeable cards with media
        - Action buttons per card (1-3)
        - Optional card type selection

        **Limits:**
        - Cards: 1-10 per carousel
        - Buttons per card: 1-3
        - Body text: max 1024 chars per card

        **Card Types:**
        - HSCROLL_CARDS: Horizontal scrolling cards (default)
        - ALBUM_IMAGE: Image album format

        **Use Cases:**
        - Product catalogs
        - Image galleries
        - Multi-option presentations
        - Tutorial sequences

        **Message Queue:** Messages are queued per recipient with FIFO ordering.
      properties:
        cardType:
          default: HSCROLL_CARDS
          description: Card display type
          enum:
          - HSCROLL_CARDS
          - ALBUM_IMAGE
          example: HSCROLL_CARDS
          type: string
        cards:
          description: Carousel cards (1-10 cards)
          items:
            $ref: '#/components/schemas/CarouselCard'
          maxItems: 10
          minItems: 1
          type: array
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 0
          minimum: 1
          type: integer
        delayTyping:
          description: Typing indicator delay in seconds (1-15)
          example: 0
          maximum: 15
          minimum: 1
          type: integer
        message:
          description: |
            Carousel body text displayed above the cards.
            This is the main message that appears before the carousel cards.
          example: Check out our latest products!
          maxLength: 1024
          type: string
        messageId:
          description: Optional custom message ID for tracking
          type: string
        phone:
          description: Recipient phone number in international format
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - cards
      type: object
    SendContactRequest:
      additionalProperties: false
      description: Request body for sending a single contact card
      properties:
        address:
          allOf:
          - $ref: '#/components/schemas/ContactAddress'
          description: Structured address details for the vCard
        birthday:
          description: Birthday in YYYY-MM-DD format
          example: "1990-05-17"
          format: date
          type:
          - string
          - "null"
        contactBusinessDescription:
          description: Optional business or organization description of the contact
          example: Sales Manager at Example Corp
          type:
          - string
          - "null"
        contactName:
          description: Full name of the contact
          example: John Doe
          type: string
        contactPhone:
          description: Phone number of the contact in international format
          example: "5511999999999"
          type: string
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        email:
          description: Email address associated with the contact
          example: john@example.com
          format: email
          type:
          - string
          - "null"
        firstName:
          description: Given name component for the vCard
          example: John
          type:
          - string
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        jobTitle:
          description: Job title or position
          example: Sales Manager
          type:
          - string
          - "null"
        lastName:
          description: Family name component for the vCard
          example: Doe
          type:
          - string
          - "null"
        mentioned:
          description: Array of phone numbers to mention
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        middleName:
          description: Middle name or additional names
          example: Michael
          type:
          - string
          - "null"
        namePrefix:
          description: Honorific prefix (e.g. Dr., Mr., Ms.)
          example: Dr.
          type:
          - string
          - "null"
        nameSuffix:
          description: Honorific suffix (e.g. Jr., Sr.)
          example: Jr.
          type:
          - string
          - "null"
        nickname:
          description: Nickname or alias for the contact
          example: Johnny
          type:
          - string
          - "null"
        note:
          description: Additional notes or comments to include in the vCard
          example: Met at WhatsApp Summit 2024
          type:
          - string
          - "null"
        organization:
          description: Organization or company name (overrides contactBusinessDescription
            when provided)
          example: Example Corp
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages - if true, reply privately to the sender
            instead of the group
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        url:
          description: Website or social media URL for the contact
          example: https://example.com/john
          format: uri
          type:
          - string
          - "null"
      required:
      - phone
      - contactName
      - contactPhone
      type: object
    SendContactsRequest:
      additionalProperties: false
      description: Request body for sending multiple contact cards
      properties:
        contacts:
          description: Array of contacts to send (1-10 items, matching WhatsApp UI
            behaviour)
          items:
            $ref: '#/components/schemas/ContactInfo'
          maxItems: 10
          minItems: 1
          type: array
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        mentioned:
          description: Array of phone numbers to mention
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages - if true, reply privately to the sender
            instead of the group
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - contacts
      type: object
    SendDocumentRequest:
      additionalProperties: false
      description: Request body for sending document messages
      properties:
        caption:
          description: Optional document caption/description
          type:
          - string
          - "null"
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds (1-15 seconds)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        document:
          description: Document URL (http/https) or base64 data URI (data:application/pdf;base64,...)
          example: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
          type: string
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        fileName:
          description: Optional document filename
          example: report.pdf
          type:
          - string
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        mentioned:
          description: Array of phone numbers to mention
          example:
          - "5511999999999"
          - "5511888888888"
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members without listing them
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages, reply in private to sender
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - document
      type: object
    SendEditEventRequest:
      additionalProperties: false
      description: Request to edit an existing event.
      properties:
        canceled:
          default: false
          description: Set to true to cancel the event.
          type: boolean
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type: integer
        delayTyping:
          description: Optional typing simulation duration in seconds.
          maximum: 15
          minimum: 1
          type: integer
        description:
          description: Updated event description.
          example: Weekly sync moved to new time
          type: string
        endTime:
          description: Updated end time in RFC3339 format.
          example: "2024-01-15T15:00:00Z"
          format: date-time
          type: string
        eventId:
          description: ID of the event message to edit.
          example: 3EB047ED70306656281B34
          type: string
        location:
          description: Updated event location.
          example: Conference Room B
          type: string
        name:
          description: Updated event name.
          example: Team Meeting - Updated
          type: string
        phone:
          description: Phone number or JID of the chat containing the event.
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        startTime:
          description: Updated start time in RFC3339 format.
          example: "2024-01-15T14:00:00Z"
          format: date-time
          type: string
      required:
      - phone
      - eventId
      type: object
    SendEditEventResponse:
      additionalProperties: false
      description: Response after editing an event.
      properties:
        eventId:
          description: The event message ID.
          type: string
        message:
          description: Optional status message.
          type: string
        messageId:
          description: The sent message ID.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - eventId
      type: object
    SendEventRequest:
      additionalProperties: false
      description: |
        Request body for sending calendar event messages.

        **Features:**
        - Send calendar events to groups
        - Support for location and call links
        - Event cancellation support
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Typing indicator duration in seconds (1-15)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        event:
          $ref: '#/components/schemas/EventPayload'
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or group JID (e.g., "120363356737170752-group")
          example: 120363356737170752-group
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - event
      type: object
    SendEventResponseRequest:
      additionalProperties: false
      description: Request to respond to an event invitation (RSVP).
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type: integer
        delayTyping:
          description: Optional typing simulation duration in seconds.
          maximum: 15
          minimum: 1
          type: integer
        eventId:
          description: ID of the event message to respond to.
          example: 3EB047ED70306656281B34
          type: string
        extraGuestCount:
          description: Number of additional guests attending.
          example: 2
          minimum: 0
          type: integer
        phone:
          description: Phone number or JID of the chat containing the event.
          example: "5511999999999"
          type: string
        response:
          description: |
            Response type:
            - `going` - Confirm attendance
            - `not_going` - Decline invitation
            - `maybe` - Tentative response
          enum:
          - going
          - not_going
          - maybe
          example: going
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - eventId
      - response
      type: object
    SendEventResponseResponse:
      additionalProperties: false
      description: Response after sending an event RSVP.
      properties:
        eventId:
          description: The event message ID.
          type: string
        message:
          description: Optional status message.
          type: string
        response:
          description: The response that was sent.
          enum:
          - going
          - not_going
          - maybe
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - eventId
      - response
      type: object
    SendGifRequest:
      additionalProperties: false
      description: |
        Request body for sending GIF messages.

        **GIF Format**: Accepts URL (http/https) or base64 data URI (data:image/gif;base64,...).

        **Key Features**:
        - Animated GIFs supported
        - Optional caption/text
        - Reply to messages via messageId
        - Schedule delivery with delayMessage or scheduledFor (ISO 8601)
        - Show typing indicator with delayTyping (1-15s)
        - View-once messages with viewOnce flag
        - Ephemeral messages with duration (0, 86400, 604800, 7776000)
        - Mention users (@mentions)
        - Mention groups/communities
        - Mention all participants (@everyone)
        - Private reply in groups

        **Message Queue**: Messages are queued per recipient with FIFO ordering.

        **WhatsApp Compatibility**: Uses whatsmeow library with full WhatsApp Web protocol support.
      properties:
        caption:
          description: |
            Optional text caption for the GIF.
            Supports @mentions via mentioned/groupMentioned arrays.
          example: "Check this out! \U0001F389"
          type:
          - string
          - "null"
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: |
            Optional typing indicator duration in seconds (1-15 seconds).
            Shows "typing..." to recipient before message is sent.
          example: 2
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: |
            Optional ephemeral message duration (view-once timer).

            **Values**:
            - `0`: Permanent (default)
            - `86400`: 24 hours (1 day)
            - `604800`: 7 days (1 week)
            - `7776000`: 90 days (3 months)
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          example: 0
          type:
          - integer
          - "null"
        gif:
          description: |
            GIF file URL or base64 data URI.

            **Supported Formats**:
            - URL: `https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDd2MXRxbTN1NjN5cXBqYjZ0c2swY3EyNmRxaGJxODRnOGxqcjR2MyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3o7abKhOpu0NwenH3O/giphy.gif`
            - Base64: `data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==`

            **Requirements**:
            - Format: GIF (animated or static)
            - Max size: 16MB recommended
            - Aspect ratio: Any (auto-adjusted by WhatsApp)
          example: https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDd2MXRxbTN1NjN5cXBqYjZ0c2swY3EyNmRxaGJxODRnOGxqcjR2MyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3o7abKhOpu0NwenH3O/giphy.gif
          type: string
        groupMentioned:
          description: |
            Optional array of groups/communities to mention.
            Used for cross-community mentions and notifications.
          items:
            $ref: '#/components/schemas/GroupMention'
          type:
          - array
          - "null"
        mentioned:
          description: |
            Optional array of phone numbers to mention (@mention).
            Users will be notified and text will show @mentions.
          items:
            example: "5511888888888"
            type:
            - string
            - "null"
          type: array
        mentionedAll:
          default: false
          description: |
            Mention all participants in group (@everyone).
            Only works in groups where user has admin permissions.
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to (quoted message)
          example: 3EB0796DC1B61E519
          type:
          - string
          - "null"
        phone:
          description: |
            Recipient phone number in international format (without + prefix).

            **Examples**:
            - Individual: `5511999999999` (Brazil mobile)
            - Group: `120363047204807488@g.us`
            - Community: `123456789@newsletter`
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: |
            Send message as private reply in group context.
            Only recipient will see the message, others see "private reply".
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        viewOnce:
          default: false
          description: |
            Send as view-once message (disappears after first view).
            Recipient can only view the GIF once.
          type: boolean
      required:
      - phone
      - gif
      type: object
    SendImageRequest:
      additionalProperties: false
      description: Request body for sending image messages
      properties:
        caption:
          description: Optional image caption/title
          example: Check out this image!
          type:
          - string
          - "null"
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds (1-15 seconds)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        image:
          description: Image URL (http/https) or base64 data URI (data:image/png;base64,...)
          example: https://picsum.photos/600/400.jpg
          type: string
        mentioned:
          description: Array of phone numbers to mention
          example:
          - "5511999999999"
          - "5511888888888"
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members without listing them
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages, reply in private to sender
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        viewOnce:
          default: false
          description: If true, image can only be viewed once
          type: boolean
      required:
      - phone
      - image
      type: object
    SendImageStatusRequest:
      additionalProperties: false
      description: |
        Request body for sending an image to WhatsApp Status/Stories.

        **Status Broadcasting**: Image is automatically broadcast to all contacts
        who can view your status based on your privacy settings.

        **Key Features**:
        - Image URL or base64 data URI support
        - Optional caption/text overlay
        - Automatic thumbnail generation
        - Optional custom message ID for tracking

        **Supported Formats**: JPEG, PNG, WebP, GIF (static)
      properties:
        caption:
          description: |
            Optional caption/text to display with the image.
            Supports emoji and unicode characters.
          example: "Check out this view! \U0001F305"
          type:
          - string
          - "null"
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        image:
          description: |
            Image URL (http/https) or base64 data URI.

            **Examples**:
            - URL: `https://example.com/image.jpg`
            - Base64: `data:image/jpeg;base64,/9j/4AAQSkZ...`
          example: https://picsum.photos/600/400.jpg
          type: string
        messageId:
          description: |
            Optional custom message ID for tracking.
            If not provided, WhatsApp generates one automatically.
          example: custom-image-status-123
          type:
          - string
          - "null"
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - image
      type: object
    SendLinkRequest:
      additionalProperties: false
      description: |
        Request body for sending link messages with custom preview.

        **Features:**
        - Custom link preview title and description
        - Custom preview image
        - Optional message text before the link
        - Reply-to support
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 5
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Typing indicator duration in seconds (1-15)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        image:
          description: Custom preview image URL
          example: https://api.whatsgo.wa-api.io/logos/zeapi-dark.png
          type: string
        linkDescription:
          description: Custom link preview description
          example: Descricao do link
          type: string
        linkUrl:
          description: URL to share
          example: https://api.whatsgo.wa-api.io
          format: uri
          type: string
        message:
          description: Optional text message that appears before the link
          example: Mensagem que ira aparecer antes do link
          type: string
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number in international format
          example: "5544999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        title:
          description: Custom link preview title
          example: Titulo da mensagem
          type: string
      required:
      - phone
      - linkUrl
      type: object
    SendLocationRequest:
      additionalProperties: false
      description: Request body for sending location messages
      properties:
        address:
          description: Optional location address
          example: Av. Paulista, 1578 - São Paulo, SP
          type:
          - string
          - "null"
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        latitude:
          description: Location latitude
          example: -23.55052
          format: double
          type: number
        longitude:
          description: Location longitude
          example: -46.633308
          format: double
          type: number
        mentioned:
          description: Array of phone numbers to mention
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        name:
          description: Optional location name/title
          example: Paulista Avenue
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - latitude
      - longitude
      type: object
    SendMessageResponse:
      additionalProperties: false
      description: Response after enqueuing a message
      properties:
        id:
          description: Same as messageId for Zapier compatibility
          example: 39BB1684570F00E91090F6BBC7EE7646
          type: string
        messageId:
          description: WhatsApp message ID (initially same as zaapId, updated after
            send)
          example: 39BB1684570F00E91090F6BBC7EE7646
          type: string
        status:
          description: Queue status for the enqueued message (always queued on success)
          example: queued
          type: string
        whatsAppStatus:
          $ref: '#/components/schemas/WhatsAppStatus'
        zaapId:
          description: Unique message ID in our system
          example: 39BB1684570F00E91090F6BBC7EE7646
          type: string
      required:
      - zaapId
      - messageId
      - id
      - status
      type: object
    SendNewsletterAdminInviteRequest:
      additionalProperties: false
      description: Request body for sending admin invite to a channel participant.
      properties:
        id:
          description: Channel identifier (suffix `@newsletter`).
          type: string
        phone:
          description: Phone number of the participant to invite as administrator.
          type: string
      required:
      - id
      - phone
      type: object
    SendOptionListRequest:
      additionalProperties: false
      description: |
        Request body for sending interactive list/menu messages.

        **Features:**
        - Multiple sections with rows
        - Expandable list menu
        - Selection callbacks

        **Limits:**
        - Max 10 sections
        - Max 10 rows per section
        - Title: max 60 chars
        - Message: max 4096 chars
        - Footer: max 60 chars
        - Button label: max 20 chars
        - Section title: max 24 chars
        - Row title: max 24 chars
        - Row description: max 72 chars

        **Message Queue:** Messages are queued per recipient with FIFO ordering.
      properties:
        buttonLabel:
          description: Text on the button that opens the menu (max 20 chars)
          example: View Menu
          maxLength: 20
          type: string
        delayMessage:
          description: Delay in seconds before sending. Any non-negative integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 0
          minimum: 0
          type: integer
        delayTyping:
          description: Typing indicator delay in seconds (0-15)
          example: 0
          maximum: 15
          minimum: 0
          type: integer
        footer:
          description: Footer text (optional)
          example: Footer text
          maxLength: 60
          type: string
        message:
          description: Message body text
          example: Please select one of the options below
          maxLength: 4096
          type: string
        messageId:
          description: Optional custom message ID for tracking/reply
          type: string
        phone:
          description: Recipient phone number in international format
          example: "5511999999999"
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        sections:
          description: List of sections containing rows (1-10 sections)
          items:
            $ref: '#/components/schemas/ListSection'
          maxItems: 10
          minItems: 1
          type: array
        title:
          description: Message title (optional)
          example: Select an option
          maxLength: 60
          type: string
      required:
      - phone
      - message
      - buttonLabel
      - sections
      type: object
    SendPTVRequest:
      additionalProperties: false
      description: |
        Request body for sending PTV (Push-To-Talk Video) messages.

        **PTV Format**: Circular video notes displayed similarly to voice notes but with video content.

        **Key Features**:
        - Circular video notes (like voice notes with video)
        - Video URL or base64 data URI support
        - Optional caption/text
        - Reply to messages via messageId
        - Schedule delivery with delayMessage or scheduledFor (ISO 8601)
        - Show typing indicator with delayTyping (1-15s)
        - Ephemeral messages with duration (0, 86400, 604800, 7776000)
        - Mention users (@mentions)
        - Mention groups/communities
        - Mention all participants (@everyone)
        - Private reply in groups

        **Message Queue**: Messages are queued per recipient with FIFO ordering.

        **WhatsApp Compatibility**: Uses whatsmeow library with full WhatsApp Web protocol support.
      properties:
        caption:
          description: |
            Optional text caption for the PTV video.
            Supports @mentions via mentioned/groupMentioned arrays.
          example: Check out this video note!
          type:
          - string
          - "null"
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: |
            Optional typing indicator duration in seconds (1-15 seconds).
            Shows "recording..." to recipient before message is sent.
          example: 2
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: |
            Optional ephemeral message duration (view-once timer).

            **Values**:
            - `0`: Permanent (default)
            - `86400`: 24 hours (1 day)
            - `604800`: 7 days (1 week)
            - `7776000`: 90 days (3 months)
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          example: 0
          type:
          - integer
          - "null"
        groupMentioned:
          description: |
            Optional array of groups/communities to mention.
            Used for cross-community mentions and notifications.
          items:
            $ref: '#/components/schemas/GroupMention'
          type:
          - array
          - "null"
        mentioned:
          description: |
            Optional array of phone numbers to mention (@mention).
            Users will be notified and text will show @mentions.
          items:
            example: "5511888888888"
            type:
            - string
            - "null"
          type: array
        mentionedAll:
          default: false
          description: |
            Mention all participants in group (@everyone).
            Only works in groups where user has admin permissions.
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to (quoted message)
          example: 3EB0796DC1B61E519
          type:
          - string
          - "null"
        phone:
          description: |
            Recipient phone number in international format (without + prefix).

            **Examples**:
            - Individual: `5511999999999` (Brazil mobile)
            - Group: `120363047204807488@g.us`
            - Community: `123456789@newsletter`
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: |
            Send message as private reply in group context.
            Only recipient will see the message, others see "private reply".
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        video:
          description: |
            Video file URL or base64 data URI.

            **Supported Formats**:
            - URL: `https://example.com/video.mp4`
            - Base64: `data:video/mp4;base64,AAAAIGZ0eXBpc29t...`

            **Requirements**:
            - Format: MP4, 3GP, MOV (auto-converted if needed)
            - Max duration: 60 seconds recommended for PTV
            - Circular display in WhatsApp
          example: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
          type: string
        viewOnce:
          default: false
          description: |
            If true, the PTV video can only be viewed once by the recipient.
            After viewing, the message disappears from the chat.
          example: false
          type: boolean
      required:
      - phone
      - video
      type: object
    SendPollRequest:
      additionalProperties: false
      description: |
        Request body for sending poll messages.

        **Features:**
        - Create polls with 2-12 options
        - Single or multiple choice selection
        - Optional reply-to support
        - Typing indicator and delay support
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 5
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Typing indicator duration in seconds (1-15)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        message:
          description: Poll question text (Zé da API uses "message" field for the
            question)
          example: Outra enquete
          type: string
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number in international format
          example: "554499999999"
          type: string
        poll:
          description: Poll options array (2-12 options required)
          example:
          - name: Zé da API
          - name: Test
          items:
            $ref: '#/components/schemas/PollOption'
          maxItems: 12
          minItems: 2
          type: array
        pollMaxOptions:
          default: 0
          description: 'Maximum selections allowed: 0 for single choice, 1+ for multiple
            choice'
          example: 1
          maximum: 12
          minimum: 0
          type: integer
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - message
      - poll
      type: object
    SendPollVoteRequest:
      additionalProperties: false
      description: Request to vote on a poll.
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type: integer
        options:
          description: Selected option names.
          example:
          - Option A
          - Option B
          items:
            type: string
          type: array
        phone:
          description: Phone number or JID of the chat containing the poll.
          example: "5511999999999"
          type: string
        pollMessageId:
          description: ID of the poll message.
          example: 3EB0796DC18B7F954D54
          type: string
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - pollMessageId
      - options
      type: object
    SendPollVoteResponse:
      additionalProperties: false
      description: Response after voting on a poll.
      properties:
        message:
          description: Optional message.
          type: string
        pollMessageId:
          description: The poll message ID.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
        votedOptions:
          description: Options that were voted for.
          items:
            type: string
          type: array
      required:
      - success
      - pollMessageId
      - votedOptions
      type: object
    SendReactionRequest:
      additionalProperties: false
      description: Request to send a reaction to a message.
      properties:
        messageId:
          description: ID of the message to react to.
          example: 3EB0796DC18B7F954D54
          type: string
        phone:
          description: Phone number or JID of the chat containing the message.
          example: "5511999999999"
          type: string
        reaction:
          description: Emoji reaction to send.
          example: "\U0001F44D"
          type: string
      required:
      - phone
      - messageId
      - reaction
      type: object
    SendRemoveReactionRequest:
      additionalProperties: false
      description: Request to remove a reaction from a message.
      properties:
        messageId:
          description: ID of the message to remove reaction from.
          example: 3EB0796DC18B7F954D54
          type: string
        phone:
          description: Phone number or JID of the chat containing the message.
          example: "5511999999999"
          type: string
      required:
      - phone
      - messageId
      type: object
    SendStickerRequest:
      additionalProperties: false
      description: |
        Request body for sending sticker messages.

        **Sticker Format**: Accepts URL (http/https) or base64 data URI (data:image/webp;base64,...).

        **Key Features**:
        - Animated stickers supported (WebP format)
        - No caption support (stickers are sent without text)
        - Reply to messages via messageId
        - Schedule delivery with delayMessage or scheduledFor (ISO 8601)
        - Show typing indicator with delayTyping (1-15s)
        - Ephemeral messages with duration (0, 86400, 604800, 7776000)
        - Mention users (@mentions)
        - Mention groups/communities
        - Mention all participants (@everyone)
        - Private reply in groups

        **Message Queue**: Messages are queued per recipient with FIFO ordering.

        **WhatsApp Compatibility**: Uses whatsmeow library with full WhatsApp Web protocol support.
      properties:
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: |
            Optional typing indicator duration in seconds (1-15 seconds).
            Shows "typing..." to recipient before message is sent.
          example: 2
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: |
            Optional ephemeral message duration (view-once timer).

            **Values**:
            - `0`: Permanent (default)
            - `86400`: 24 hours (1 day)
            - `604800`: 7 days (1 week)
            - `7776000`: 90 days (3 months)
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          example: 0
          type:
          - integer
          - "null"
        groupMentioned:
          description: |
            Optional array of groups/communities to mention.
            Used for cross-community mentions and notifications.
          items:
            $ref: '#/components/schemas/GroupMention'
          type:
          - array
          - "null"
        mentioned:
          description: |
            Optional array of phone numbers to mention (@mention).
            Users will be notified and text will show @mentions.
          items:
            example: "5511888888888"
            type:
            - string
            - "null"
          type: array
        mentionedAll:
          default: false
          description: |
            Mention all participants in group (@everyone).
            Only works in groups where user has admin permissions.
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to (quoted message)
          example: 3EB0796DC1B61E519
          type:
          - string
          - "null"
        phone:
          description: |
            Recipient phone number in international format (without + prefix).

            **Examples**:
            - Individual: `5511999999999` (Brazil mobile)
            - Group: `120363047204807488@g.us`
            - Community: `123456789@newsletter`
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: |
            Send message as private reply in group context.
            Only recipient will see the message, others see "private reply".
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        sticker:
          description: |
            Sticker file URL or base64 data URI.

            **Supported Formats**:
            - URL: `https://www.gstatic.com/webp/gallery/1.webp`
            - Base64: `data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoBAAEAAwA0JaQAA3AA/vuUAAA=`

            **Requirements**:
            - Format: WebP (animated or static)
            - Max size: 100KB recommended for animated, 500KB for static
            - Dimensions: 512x512 pixels recommended
          example: https://www.gstatic.com/webp/gallery/1.webp
          type: string
      required:
      - phone
      - sticker
      type: object
    SendTextRequest:
      additionalProperties: false
      description: Request body for sending text messages
      properties:
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            Default random 1-3 seconds.
          example: 5
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds (1-15 seconds,
            default 0)
          example: 3
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds (0, 86400, 604800, 7776000)
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          example: 86400
          type:
          - integer
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        linkPreview:
          description: If nil/omitted, auto-detect URLs and generate preview; if true,
            force preview; if false, disable preview
          example: true
          type:
          - boolean
          - "null"
        mentioned:
          description: Array of phone numbers to mention
          example:
          - "5511999999999"
          - "5511888888888"
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members without listing them
          type: boolean
        message:
          description: Text message content
          example: Hello from Zé da API!
          type: string
        messageId:
          description: Optional WhatsApp message ID to reply to
          example: 3EB0796DC18B7F954D54
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number in international format (numbers only)
            or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages - if true, reply in private to sender
          example: false
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
      required:
      - phone
      - message
      type: object
    SendTextStatusRequest:
      additionalProperties: false
      description: |
        Request body for sending text to WhatsApp Status/Stories.

        **Status Broadcasting**: Text is automatically broadcast to all contacts
        who can view your status based on your privacy settings.

        **Key Features**:
        - Custom background color (hex or ARGB format)
        - Multiple font styles (0-5)
        - Optional custom message ID for tracking
        - Delayed sending and scheduled delivery support (delayMessage or scheduledFor)

        **Note**: Unlike regular messages, status messages don't require a phone number.
        They broadcast to status@broadcast automatically.
      properties:
        backgroundColor:
          description: |
            Background color for text status.

            **Supported Formats**:
            - Hex: `#FF5733` (RGB)
            - ARGB: `0xFF5733FF` (with alpha)

            **Default**: WhatsApp default gradient
          example: '#FF5733'
          type:
          - string
          - "null"
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        font:
          description: |
            Font style for text status.

            **Font Options**:
            - 0: Default (Sans-serif)
            - 1: Serif
            - 2: Norican Script
            - 3: Bryndan Write
            - 4: Bebasneue Regular
            - 5: Oswald Heavy
          example: 0
          maximum: 5
          minimum: 0
          type:
          - integer
          - "null"
        messageId:
          description: |
            Optional custom message ID for tracking.
            If not provided, WhatsApp generates one automatically.
          example: custom-status-123
          type:
          - string
          - "null"
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        text:
          description: |
            Text content for the status. Supports emoji and unicode characters.
            Maximum length depends on WhatsApp limits (typically ~700 characters).
          example: "Hello from my status! \U0001F389"
          type: string
      required:
      - text
      type: object
    SendVideoRequest:
      additionalProperties: false
      description: Request body for sending video messages
      properties:
        caption:
          description: Optional video caption/title
          type:
          - string
          - "null"
        delayMessage:
          description: Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          minimum: 1
          type:
          - integer
          - "null"
        delayTyping:
          description: Optional typing indicator duration in seconds (1-15 seconds)
          maximum: 15
          minimum: 1
          type:
          - integer
          - "null"
        duration:
          description: Ephemeral message duration in seconds
          enum:
          - 0
          - 86400
          - 604800
          - 7776000
          type:
          - integer
          - "null"
        groupMentioned:
          description: Array of groups to mention in communities
          items:
            $ref: '#/components/schemas/GroupMention'
          type: array
        mentioned:
          description: Array of phone numbers to mention
          example:
          - "5511999999999"
          - "5511888888888"
          items:
            type: string
          type: array
        mentionedAll:
          default: false
          description: Mention all group members without listing them
          type: boolean
        messageId:
          description: Optional WhatsApp message ID to reply to
          type:
          - string
          - "null"
        phone:
          description: Recipient phone number or WhatsApp JID
          example: "5511999999999"
          type: string
        privateAnswer:
          default: false
          description: For group messages, reply in private to sender
          type: boolean
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        video:
          description: Video URL (http/https) or base64 data URI (data:video/mp4;base64,...)
          example: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
          type: string
        viewOnce:
          default: false
          description: If true, video can only be viewed once
          type: boolean
      required:
      - phone
      - video
      type: object
    SendVideoStatusRequest:
      additionalProperties: false
      description: |
        Request body for sending a video to WhatsApp Status/Stories.

        **Status Broadcasting**: Video is automatically broadcast to all contacts
        who can view your status based on your privacy settings.

        **Key Features**:
        - Video URL or base64 data URI support
        - Optional caption/text overlay
        - Automatic thumbnail generation
        - Optional custom message ID for tracking

        **Supported Formats**: MP4, 3GP, MOV, AVI
        **Duration Limit**: WhatsApp status videos are typically limited to 30 seconds
      properties:
        caption:
          description: |
            Optional caption/text to display with the video.
            Supports emoji and unicode characters.
          example: "Amazing video! \U0001F3AC"
          type:
          - string
          - "null"
        delayMessage:
          description: |
            Delay in seconds before sending. Any positive integer accepted.
            For longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.
          example: 3
          minimum: 1
          type:
          - integer
          - "null"
        messageId:
          description: |
            Optional custom message ID for tracking.
            If not provided, WhatsApp generates one automatically.
          example: custom-video-status-123
          type:
          - string
          - "null"
        scheduledFor:
          description: ISO 8601 timestamp for scheduled delivery. Takes priority over
            delayMessage if both provided.
          format: date-time
          type:
          - string
          - "null"
        video:
          description: |
            Video URL (http/https) or base64 data URI.

            **Examples**:
            - URL: `https://example.com/video.mp4`
            - Base64: `data:video/mp4;base64,AAAAIGZ0eXBpc29t...`
          example: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
          type: string
      required:
      - video
      type: object
    StatusCacheAggregatedStatus:
      additionalProperties: false
      description: |
        Aggregated status summary for a message, showing delivery statistics
        across all recipients (for groups) or the single recipient (for direct messages).
      properties:
        createdAt:
          description: Unix timestamp (ms) when first status was cached
          example: 1735200000000
          format: int64
          type: integer
        groupId:
          description: Group ID (only present for group messages)
          example: "120363182823169824"
          type: string
        instanceId:
          description: Instance that sent the message
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        isGroup:
          description: Whether this is a group message
          example: true
          type: boolean
        messageId:
          description: WhatsApp message ID
          example: 3EB0A1B2C3D4E5F6
          type: string
        participants:
          description: Individual participant statuses (only included when requested)
          items:
            $ref: '#/components/schemas/StatusCacheParticipantStatus'
          type: array
        phone:
          description: |
            For direct messages: recipient phone number.
            For groups: group JID or identifier.
          example: "5511999999999"
          type: string
        status:
          additionalProperties:
            type: integer
          description: Count of participants by status type
          example:
            delivered: 23
            played: 0
            read: 15
            sent: 25
          type: object
        totalParticipants:
          description: Total number of participants with status updates
          example: 25
          type: integer
        updatedAt:
          description: Unix timestamp (ms) of most recent status update
          example: 1735200060000
          format: int64
          type: integer
      required:
      - messageId
      - instanceId
      - phone
      - isGroup
      - totalParticipants
      - status
      - createdAt
      - updatedAt
      type: object
    StatusCacheClearAllResult:
      additionalProperties: false
      description: Result of clearing all cached entries for an instance.
      properties:
        cleared:
          description: Total number of entries cleared
          example: 150
          format: int64
          type: integer
      required:
      - cleared
      type: object
    StatusCacheClearSingleResult:
      additionalProperties: false
      description: Result of clearing a single message from cache.
      properties:
        cleared:
          description: Number of entries cleared (0 or 1)
          example: 1
          type: integer
        messageId:
          description: The message ID that was cleared
          example: 3EB0A1B2C3D4E5F6
          type: string
      required:
      - cleared
      - messageId
      type: object
    StatusCacheFlushRequest:
      additionalProperties: false
      description: |
        Request to flush (deliver) pending webhooks.
        Specify either `messageId` for a single message or `all: true` for all pending.
      properties:
        all:
          default: false
          description: Set to true to flush all pending webhooks
          type: boolean
        messageId:
          description: Flush webhooks for a specific message ID
          example: 3EB0A1B2C3D4E5F6
          type: string
      type: object
    StatusCacheFlushResult:
      additionalProperties: false
      description: Result of a flush operation.
      properties:
        flushed:
          description: Number of pending webhook entries processed
          example: 15
          type: integer
        webhooksTriggered:
          description: Number of webhooks actually dispatched
          example: 15
          type: integer
      required:
      - flushed
      - webhooksTriggered
      type: object
    StatusCacheParticipantStatus:
      additionalProperties: false
      description: Individual participant's status within a group message.
      properties:
        device:
          description: WhatsApp device ID (0 = primary, 1+ = linked devices)
          example: 0
          type: integer
        phone:
          description: Participant's phone number (MSISDN format)
          example: "5511999999999"
          type: string
        status:
          description: |
            Current status of the message for this participant.
            - `sent`: Message sent to WhatsApp servers
            - `delivered`: Message delivered to participant's device
            - `read`: Message read by participant
            - `played`: Audio/video/PTT played by participant
          enum:
          - sent
          - delivered
          - read
          - played
          example: read
          type: string
        timestamp:
          description: Unix timestamp in milliseconds when status was received
          example: 1735200000000
          format: int64
          type: integer
      required:
      - phone
      - status
      - timestamp
      type: object
    StatusCacheQueryMeta:
      additionalProperties: false
      description: Pagination metadata for status cache queries.
      properties:
        limit:
          description: Maximum entries per page
          example: 100
          type: integer
        offset:
          description: Current page offset
          example: 0
          type: integer
        total:
          description: Total number of matching entries
          example: 150
          format: int64
          type: integer
      required:
      - total
      - limit
      - offset
      type: object
    StatusCacheQueryResult:
      additionalProperties: false
      description: |
        Aggregated query result with human-readable status summaries.
        Returns processed data with participant counts by status type.
      properties:
        data:
          description: Array of aggregated status entries
          items:
            $ref: '#/components/schemas/StatusCacheAggregatedStatus'
          type: array
        meta:
          $ref: '#/components/schemas/StatusCacheQueryMeta'
      required:
      - data
      - meta
      type: object
    StatusCacheRawQueryResult:
      additionalProperties: false
      description: |
        Raw query result with original webhook payloads.
        Use format=raw to retrieve this format.
      properties:
        data:
          description: Array of raw status payloads
          items:
            $ref: '#/components/schemas/StatusCacheRawStatusPayload'
          type: array
        meta:
          $ref: '#/components/schemas/StatusCacheQueryMeta'
      required:
      - data
      - meta
      type: object
    StatusCacheRawStatusPayload:
      additionalProperties: false
      description: |
        Raw status payload as originally received from WhatsApp.
        Useful for debugging or when exact original data is needed.
      properties:
        cachedAt:
          description: Unix timestamp (ms) when entry was cached
          example: 1735200000000
          format: int64
          type: integer
        instanceId:
          description: Instance ID
          example: 550e8400-e29b-41d4-a716-446655440000
          format: uuid
          type: string
        messageId:
          description: WhatsApp message ID
          example: 3EB0A1B2C3D4E5F6
          type: string
        payload:
          additionalProperties: true
          description: Original webhook payload
          type: object
      required:
      - messageId
      - instanceId
      - payload
      - cachedAt
      type: object
    StatusCacheStats:
      additionalProperties: false
      description: Statistics about the status cache for an instance.
      properties:
        entriesByInstance:
          additionalProperties:
            format: int64
            type: integer
          description: Breakdown of entries by instance ID
          example:
            550e8400-e29b-41d4-a716-446655440000: 1500
          type: object
        pendingWebhooks:
          description: Number of webhooks pending delivery (waiting for flush)
          example: 45
          format: int64
          type: integer
        totalEntries:
          description: Total number of cached status entries
          example: 1500
          format: int64
          type: integer
      required:
      - totalEntries
      - entriesByInstance
      - pendingWebhooks
      type: object
    StringValueRequest:
      additionalProperties: false
      properties:
        value:
          description: String value for the setting.
          type: string
      required:
      - value
      type: object
    UpdatePrivacyRequest:
      additionalProperties: false
      description: Request body for updating a privacy setting.
      properties:
        value:
          description: New privacy value.
          example: contacts
          type: string
      required:
      - value
      type: object
    UpdatePrivacyResponse:
      additionalProperties: false
      description: Response after updating a privacy setting.
      properties:
        message:
          description: Optional message.
          type: string
        setting:
          description: The setting that was updated.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
        value:
          description: The new value.
          type: string
      required:
      - success
      - setting
      - value
      type: object
    UpdateProfileDescriptionRequest:
      additionalProperties: false
      description: Request to update profile description (About/Status).
      properties:
        description:
          description: New profile description.
          example: Hey there! I am using WhatsApp.
          maxLength: 139
          type: string
      required:
      - description
      type: object
    UpdateProfileDescriptionResponse:
      additionalProperties: false
      description: Response after updating profile description.
      properties:
        description:
          description: The new profile description.
          type: string
        message:
          description: Optional message.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - description
      type: object
    UpdateProfileNameRequest:
      additionalProperties: false
      description: Request to update profile name (push name).
      properties:
        name:
          description: New profile name.
          example: John Doe
          maxLength: 25
          minLength: 1
          type: string
      required:
      - name
      type: object
    UpdateProfileNameResponse:
      additionalProperties: false
      description: Response after updating profile name.
      properties:
        message:
          description: Optional message.
          type: string
        name:
          description: The new profile name.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      - name
      type: object
    UpdateProfilePictureRequest:
      additionalProperties: false
      description: Request to update profile picture.
      properties:
        image:
          description: Base64-encoded JPEG image or URL.
          example: data:image/jpeg;base64,/9j/4AAQ...
          type: string
      required:
      - image
      type: object
    UpdateProfilePictureResponse:
      additionalProperties: false
      description: Response after updating profile picture.
      properties:
        message:
          description: Optional message.
          type: string
        pictureId:
          description: New picture ID assigned by WhatsApp.
          type: string
        success:
          description: Whether the operation succeeded.
          type: boolean
      required:
      - success
      type: object
    ValueResponse:
      additionalProperties: false
      properties:
        value:
          description: Indicates whether the operation was successful.
          type: boolean
      type: object
    WebhookEveryRequest:
      additionalProperties: false
      properties:
        notifySentByMe:
          description: Optional flag to also toggle the notify-sent-by-me option.
          type: boolean
        value:
          description: HTTPS endpoint applied to all webhook types.
          type: string
      required:
      - value
      type: object
    WebhookSettings:
      additionalProperties: false
      properties:
        connectedCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        deliveryCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        disconnectedCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        historySyncCallbackUrl:
          description: Dedicated webhook endpoint for WhatsApp history sync events.
          format: uri
          type:
          - string
          - "null"
        messageStatusCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        notifySentByMe:
          type: boolean
        presenceChatCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        receivedAndDeliveryCallbackUrl:
          format: uri
          type:
          - string
          - "null"
        receivedCallbackUrl:
          format: uri
          type:
          - string
          - "null"
      type: object
    WebhookUpdateResponse:
      additionalProperties: false
      properties:
        value:
          description: Indicates whether the update was accepted.
          type: boolean
        webhooks:
          $ref: '#/components/schemas/WebhookSettings'
      required:
      - value
      type: object
    WebhookValueRequest:
      additionalProperties: false
      properties:
        value:
          description: HTTPS endpoint that should receive the webhook.
          type: string
      required:
      - value
      type: object
    WhatsAppStatus:
      description: Snapshot of the WhatsApp connectivity state when the message was
        enqueued
      properties:
        connected:
          description: Indicates if the WhatsApp client is connected at enqueue time
          type: boolean
        lastSeen:
          description: Timestamp of the last known successful connection (RFC3339)
          format: date-time
          type:
          - string
          - "null"
        reason:
          description: Reason for the current connectivity state (connected, reconnecting,
            logged_out, etc.)
          example: disconnected
          type: string
        workerId:
          description: Identifier of the worker handling the instance, when available
          type:
          - string
          - "null"
      type: object
  securitySchemes:
    ClientTokenAuth:
      description: Instance client token obtained during provisioning.
      in: header
      name: Client-Token
      type: apiKey
    PartnerBearer:
      bearerFormat: JWT
      description: Partner integrator bearer token.
      scheme: bearer
      type: http
info:
  description: |
    Production WhatsApp Business API built on Whatsmeow.
    Full-featured REST API for sending messages, managing instances, configuring webhooks, and handling WhatsApp events.
  title: Zé da API (Whatsmeow Bridge)
  version: v3.38.0
openapi: 3.1.0
paths:
  /health:
    get:
      description: Returns a JSON object indicating that the API process is running.
      operationId: healthLiveness
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatusResponse'
          description: Process is alive and capable of serving traffic.
      security: []
      summary: Liveness probe
      tags:
      - System
  /instances:
    get:
      description: Returns a paginated list of managed WhatsApp instances for the
        partner account.
      operationId: listInstances
      parameters:
      - description: Filter results by instance name or session name.
        in: query
        name: query
        schema:
          type: string
      - description: Informational middleware flag (matches Zé da API contract).
        in: query
        name: middleware
        schema:
          type: string
      - description: Page number (1-indexed).
        example: 1
        in: query
        name: page
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Page size (defaults to 15 as in Zé da API examples).
        example: 15
        in: query
        name: pageSize
        required: true
        schema:
          maximum: 200
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceListResponse'
          description: List of instances owned by the partner.
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing or invalid Partner bearer token.
      security:
      - PartnerBearer: []
      summary: List partner instances
      tags:
      - Partner
  /instances/{instanceId}:
    delete:
      description: |
        **⚠️ IRREVERSIBLE OPERATION ⚠️**

        Permanently deletes a WhatsApp instance including all associated data from both databases.

        **Complete Cleanup Operations:**
        - ✅ Disconnects the WhatsApp client immediately
        - ✅ Disables auto-reconnect to prevent reconnection
        - ✅ **Deletes device store from whatsmeow_store database**
        - ✅ Stops lock refresh goroutine
        - ✅ Releases Redis distributed lock
        - ✅ Removes client from in-memory registry
        - ✅ **Deletes instance record from api_core database**
        - ✅ **Deletes all webhook configurations (CASCADE)**
        - ✅ **Deletes all webhook outbox entries (CASCADE)**
        - ✅ **Deletes all webhook DLQ entries (manual deletion)**
        - ✅ **Deletes all instance event logs (manual deletion)**

        **Database Deletion Strategy:**
        - Uses transaction to ensure ACID compliance
        - Manually deletes tables without CASCADE constraints (webhook_dlq, instance_events_log)
        - Relies on CASCADE for webhook_configs and webhook_outbox
        - Deletes device credentials from separate whatsmeow_store database

        **Authentication:**
        - Requires Partner Bearer token only (no instance token needed)
        - This is a Partner-level administrative operation

        **Use Cases:**
        - Cleanup of test/development instances
        - Customer offboarding and data removal
        - GDPR/data deletion compliance requests
        - Freeing resources from inactive instances

        **Important Notes:**
        - **This operation cannot be undone or reversed**
        - All data associated with the instance is permanently lost
        - The instance cannot be recovered or reconnected after deletion
        - Consider using `/disconnect` if you need to preserve the instance record
      operationId: partnerDeleteInstance
      parameters:
      - description: Unique instance identifier to permanently delete.
        example: 550e8400-e29b-41d4-a716-446655440000
        in: path
        name: instanceId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        "200":
          content:
            application/json:
              example:
                status: deleted
              schema:
                properties:
                  status:
                    description: Confirmation that instance was deleted
                    enum:
                    - deleted
                    example: deleted
                    type: string
                required:
                - status
                type: object
          description: Instance permanently deleted successfully
        "400":
          content:
            application/json:
              example:
                error: invalid instance id
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid instance ID format (must be valid UUID)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing or invalid Partner bearer token
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found in database
        "500":
          content:
            application/json:
              example:
                error: 'delete instance from database: connection error'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal error during deletion (transaction may have been rolled
            back)
      security:
      - PartnerBearer: []
      summary: Permanently delete instance (Partner API)
      tags:
      - Partner
  /instances/{instanceId}/token/{instanceToken}/accept-invite-group:
    get:
      description: Accepts a group invitation link on behalf of the connected WhatsApp
        account.
      operationId: acceptGroupInvite
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Group invitation URL to accept.
        in: query
        name: url
        required: true
        schema:
          format: uri
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanSuccessResponse'
          description: Invitation accepted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or invitation not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Accept group invite
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/add-admin:
    post:
      description: Promotes participants to administrators for a group or community.
      operationId: addAdministrators
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              community:
                summary: Promote community administrators
                value:
                  communityId: "120363019502650977"
                  phones:
                  - "5544999999999"
                  - "5544888888888"
              group:
                summary: Promote group administrators
                value:
                  groupId: 120363019502650977-group
                  phones:
                  - "5544999999999"
                  - "5544888888888"
            schema:
              oneOf:
              - $ref: '#/components/schemas/GroupParticipantListRequest'
              - $ref: '#/components/schemas/CommunityAdminMutationRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Administrators promoted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, group or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Promote administrators
      tags:
      - Groups
      - Communities
  /instances/{instanceId}/token/{instanceToken}/add-contact:
    post:
      description: |
        Adds or updates a contact in the WhatsApp address book using AppState sync.
      operationId: addContact
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              fullName: John Doe
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/AddContactRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddContactResponse'
          description: Contact added successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Add contact to address book
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/add-participant:
    post:
      description: Adds participants to a group or to the announcements group of a
        community.
      operationId: addParticipants
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              community:
                summary: Add participants to a community
                value:
                  autoInvite: true
                  communityId: "120363019502650977"
                  phones:
                  - "5544999999999"
                  - "5544888888888"
              group:
                summary: Add participants to a group
                value:
                  autoInvite: true
                  groupId: 120363019502650977-group
                  phones:
                  - "5544999999999"
                  - "5544888888888"
            schema:
              oneOf:
              - $ref: '#/components/schemas/GroupAddParticipantsRequest'
              - $ref: '#/components/schemas/CommunityAddParticipantsRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Participants added successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, group or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Add participants
      tags:
      - Groups
      - Communities
  /instances/{instanceId}/token/{instanceToken}/approve-participant:
    post:
      description: Approves pending join requests for a group.
      operationId: approveGroupParticipants
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              groupId: 120363019502650977-group
              phones:
              - "5544999999999"
              - "5544888888888"
            schema:
              $ref: '#/components/schemas/GroupParticipantListRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Participants approved successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Approve participants
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/business/available-categories:
    get:
      description: Returns all WhatsApp business categories that can be assigned to
        a profile.
      operationId: getAvailableCategories
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  properties:
                    displayName:
                      type: string
                    id:
                      type: string
                    label:
                      type: string
                  type: object
                type: array
          description: Array of available categories
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get available business categories
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/categories:
    post:
      description: Sets the business categories for the WhatsApp profile (1 to 3 categories).
      operationId: setCategories
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                categories:
                  items:
                    type: string
                  maxItems: 3
                  minItems: 1
                  type: array
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Categories updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Set business categories
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/company-address:
    post:
      description: Updates the business address shown on the WhatsApp profile.
      operationId: setCompanyAddress
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                value:
                  type: string
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Address updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Set company address
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/company-description:
    post:
      description: Updates the business description shown on the WhatsApp profile.
      operationId: setCompanyDescription
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                value:
                  type: string
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Description updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Set company description
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/company-email:
    post:
      description: Updates the business email shown on the WhatsApp profile.
      operationId: setCompanyEmail
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                value:
                  type: string
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Email updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Set company email
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/company-websites:
    post:
      description: Updates the business websites shown on the WhatsApp profile (max
        2).
      operationId: setCompanyWebsites
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                websites:
                  items:
                    type: string
                  maxItems: 2
                  type: array
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Websites updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Set company websites
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/create-tag:
    post:
      description: Creates a label tag that can be applied to chats.
      operationId: createTag
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                color:
                  maximum: 19
                  minimum: 0
                  type: integer
                name:
                  type: string
              required:
              - name
              - color
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                type: object
          description: Tag created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Create a new tag
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/edit-tag/{tagId}:
    post:
      description: Updates the name and/or color of an existing tag.
      operationId: editTag
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Tag identifier
        in: path
        name: tagId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                color:
                  maximum: 19
                  minimum: 0
                  type: integer
                name:
                  type: string
              required:
              - name
              - color
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Tag updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Tag or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Edit a tag
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/hours:
    post:
      description: Configures the business hours displayed on the WhatsApp profile.
      operationId: setBusinessHours
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                days:
                  items:
                    properties:
                      closeTime:
                        type: string
                      dayOfWeek:
                        type: string
                      openTime:
                        type: string
                    type: object
                  type: array
                mode:
                  type: string
                timezone:
                  type: string
              type: object
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Business hours updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Set business hours
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/profile:
    get:
      description: Returns the WhatsApp Business profile for this instance.
      operationId: getBusinessProfile
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  address:
                    type: string
                  businessHours:
                    properties:
                      days:
                        items:
                          properties:
                            closeTime:
                              type: string
                            dayOfWeek:
                              type: string
                            openTime:
                              type: string
                          type: object
                        type: array
                      mode:
                        type: string
                      timezone:
                        type: string
                    type: object
                  categories:
                    items:
                      properties:
                        displayName:
                          type: string
                        id:
                          type: string
                        label:
                          type: string
                      type: object
                    type: array
                  description:
                    type: string
                  email:
                    type: string
                  hasCoverPhoto:
                    type: boolean
                  websites:
                    items:
                      type: string
                    type: array
                type: object
          description: Business profile data
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get business profile
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/tag/{tagId}:
    delete:
      description: Permanently removes a label tag from the instance.
      operationId: deleteTag
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Tag identifier
        in: path
        name: tagId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Tag deleted
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Tag or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Delete a tag
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/business/tags/colors:
    get:
      description: Returns the palette of available tag colors as a map of index to
        hex color.
      operationId: getTagColors
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Map of color index to hex color string
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get available tag colors
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs:
    get:
      description: Returns the product catalog for this instance, including cart status.
      operationId: listProducts
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  cartEnabled:
                    type: boolean
                  products:
                    items:
                      properties:
                        availability:
                          type: string
                        currency:
                          type: string
                        description:
                          type: string
                        id:
                          type: string
                        images:
                          items:
                            type: string
                          type: array
                        isHidden:
                          type: boolean
                        name:
                          type: string
                        price:
                          type: string
                        quantity:
                          nullable: true
                          type: boolean
                        retailerId:
                          nullable: true
                          type: string
                        salePrice:
                          type: string
                        url:
                          type: string
                      type: object
                    type: array
                type: object
          description: Product catalog
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List all products
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/{phone}:
    get:
      description: Returns the product catalog for a specific contact's phone number.
      operationId: getProductsByPhone
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number of the catalog owner
        in: path
        name: phone
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  cartEnabled:
                    type: boolean
                  nextCursor:
                    nullable: true
                    type: string
                  products:
                    items:
                      properties:
                        availability:
                          type: string
                        currency:
                          type: string
                        description:
                          type: string
                        id:
                          type: string
                        images:
                          items:
                            type: string
                          type: array
                        isHidden:
                          type: boolean
                        name:
                          type: string
                        price:
                          type: string
                        quantity:
                          nullable: true
                          type: boolean
                        retailerId:
                          nullable: true
                          type: string
                        salePrice:
                          type: string
                        url:
                          type: string
                      type: object
                    type: array
                type: object
          description: Products for the specified phone
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get products by phone
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/collection:
    get:
      description: Returns all product collections for this instance.
      operationId: listCollections
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  collections:
                    items:
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        status:
                          type: string
                      type: object
                    type: array
                  nextCursor:
                    nullable: true
                    type: string
                type: object
          description: Array of collections
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List collections
      tags:
      - Business
    post:
      description: Creates a new product collection in the catalog.
      operationId: createCollection
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                productIds:
                  items:
                    type: string
                  type: array
              required:
              - name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  collectionId:
                    type: string
                type: object
          description: Collection created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Create a collection
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/collection-edit/{collectionId}:
    post:
      description: Updates the name of an existing collection.
      operationId: editCollection
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Collection identifier
        in: path
        name: collectionId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
              required:
              - name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  collectionId:
                    type: string
                  success:
                    type: boolean
                type: object
          description: Collection updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Collection or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Edit a collection
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/collection-products/{phone}:
    get:
      description: Returns the products in a collection for a specific contact's phone
        number.
      operationId: listCollectionProducts
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number of the catalog owner
        in: path
        name: phone
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  nextCursor:
                    nullable: true
                    type: string
                  products:
                    items:
                      properties:
                        availability:
                          type: string
                        currency:
                          type: string
                        description:
                          type: string
                        id:
                          type: string
                        images:
                          items:
                            type: string
                          type: array
                        isHidden:
                          type: boolean
                        name:
                          type: string
                        price:
                          type: string
                        quantity:
                          nullable: true
                          type: boolean
                        retailerId:
                          nullable: true
                          type: string
                        salePrice:
                          type: string
                        url:
                          type: string
                      type: object
                    type: array
                type: object
          description: Collection products
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List collection products by phone
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/collection/{collectionId}:
    delete:
      description: Permanently removes a product collection.
      operationId: deleteCollection
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Collection identifier
        in: path
        name: collectionId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Collection deleted
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Collection or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Delete a collection
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/collection/add-product:
    post:
      description: Adds one or more products to an existing collection.
      operationId: addProductToCollection
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                collectionId:
                  type: string
                productIds:
                  items:
                    type: string
                  type: array
              required:
              - collectionId
              - productIds
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  collectionId:
                    type: string
                  success:
                    type: boolean
                type: object
          description: Products added to collection
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Collection or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Add products to collection
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/collection/remove-product:
    post:
      description: Removes one or more products from an existing collection.
      operationId: removeProductFromCollection
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                collectionId:
                  type: string
                productIds:
                  items:
                    type: string
                  type: array
              required:
              - collectionId
              - productIds
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  collectionId:
                    type: string
                  success:
                    type: boolean
                type: object
          description: Products removed from collection
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Collection or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Remove products from collection
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/catalogs/config:
    post:
      description: Enables or disables the shopping cart for this instance catalog.
      operationId: saveCatalogConfig
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cartEnabled:
                  type: boolean
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Catalog configuration saved
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Save catalog configuration
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/chats:
    get:
      description: |
        Returns a paginated list of WhatsApp chats (conversations) for the instance.

        **Features:**
        - ✅ Pagination support (page, pageSize)
        - ✅ Individual, group, and community chats
        - ✅ Unread message counts
        - ✅ Last message timestamp
        - ✅ Mute status and expiry
        - ✅ Archive, pin, and spam status
        - ✅ X-Total-Count header for total count
        - ✅ Ordered by lastMessageTime (most recent first)

        **Chat Types:**
        - Individual chats (person-to-person)
        - Group chats (multiple participants)
        - Community announcement channels

        **Data Sources:**
        - WhatsApp chat metadata (from store)
        - Message history (last message timestamp)
        - Chat settings (mute, archive, pin, spam status)

        **Ordering:** Chats are ordered by lastMessageTime descending (most recent first).

        **Unread Counts:** Both `unread` and `messagesUnread` fields represent the same count.
      operationId: getChats
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Page number (1-indexed)
        example: 1
        in: query
        name: page
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Number of chats per page (max 100)
        example: 20
        in: query
        name: pageSize
        required: true
        schema:
          maximum: 100
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              example:
              - archived: false
                isGroup: false
                isMarkedSpam: false
                isMuted: false
                lastMessageTime: "2025-01-11T14:30:00Z"
                messagesUnread: 5
                muteEndTime: "0001-01-01T00:00:00Z"
                name: João Silva
                phone: 5511999999999@s.whatsapp.net
                pinned: true
                unread: 5
              - archived: false
                isGroup: true
                isMarkedSpam: false
                isMuted: true
                lastMessageTime: "2025-01-11T13:45:00Z"
                messagesUnread: 12
                muteEndTime: "2025-01-12T14:30:00Z"
                name: Família Silva
                phone: 120363047204807488@g.us
                pinned: false
                unread: 12
              - archived: true
                isGroup: false
                isMarkedSpam: false
                isMuted: false
                lastMessageTime: "2025-01-11T10:15:00Z"
                messagesUnread: 0
                muteEndTime: "0001-01-01T00:00:00Z"
                name: Maria Oliveira
                phone: 5511888888888@s.whatsapp.net
                pinned: false
                unread: 0
              schema:
                items:
                  $ref: '#/components/schemas/Chat'
                type: array
          description: Chats retrieved successfully
          headers:
            X-Total-Count:
              description: Total number of chats available
              example: 75
              schema:
                type: integer
        "400":
          content:
            application/json:
              example:
                error: page must be >= 1
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid pagination parameters
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: List WhatsApp chats
      tags:
      - Chats
  /instances/{instanceId}/token/{instanceToken}/chats/{phone}/notes:
    post:
      description: Stores notes associated with a specific chat.
      operationId: saveChatNotes
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number or JID of the chat
        in: path
        name: phone
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                notes:
                  type: string
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Notes saved
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or chat not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Save chat notes
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/chats/{phone}/tags/{tag}/add:
    put:
      description: Assigns a label tag to the specified chat.
      operationId: addTagToChat
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number or JID of the chat
        in: path
        name: phone
        required: true
        schema:
          type: string
      - description: Tag name or identifier
        in: path
        name: tag
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  value:
                    example: true
                    type: boolean
                type: object
          description: Tag added to chat
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or chat not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Add tag to chat
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/chats/{phone}/tags/{tag}/remove:
    put:
      description: Removes a label tag from the specified chat.
      operationId: removeTagFromChat
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number or JID of the chat
        in: path
        name: phone
        required: true
        schema:
          type: string
      - description: Tag name or identifier
        in: path
        name: tag
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  value:
                    example: true
                    type: boolean
                type: object
          description: Tag removed from chat
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or chat not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Remove tag from chat
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/communities:
    get:
      description: Returns the communities the connected account participates in.
      operationId: listCommunities
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Optional page number (1-indexed).
        example: 1
        in: query
        name: page
        schema:
          minimum: 1
          type: integer
      - description: Optional page size.
        example: 10
        in: query
        name: pageSize
        schema:
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/CommunityListItem'
                type: array
          description: Array of communities (unwrapped, matching Zé da API behaviour).
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List communities
      tags:
      - Communities
    post:
      description: Creates a new WhatsApp community.
      operationId: createCommunity
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              description: Comunidade de testes
              name: Minha primeira Comunidade
            schema:
              $ref: '#/components/schemas/CommunityCreateRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityCreateResponse'
          description: Community created successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Create community
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/communities-metadata/{communityId}:
    get:
      description: Returns metadata and linked groups for a community.
      operationId: getCommunityMetadata
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Community identifier.
        in: path
        name: communityId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityMetadataResponse'
          description: Community metadata returned successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get community metadata
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/communities/{communityId}:
    delete:
      description: |
        Mirrors Zé da API `DELETE /communities/{communityId}`, permanently deleting a community.

        **Important**: This action is irreversible. All linked groups will be unlinked but not deleted.
      operationId: deleteCommunity
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Community identifier (e.g., "120363019502650977")
        example: "120363019502650977"
        in: path
        name: communityId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              example:
                value: true
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Community deleted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Delete community
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/communities/link:
    post:
      description: Links one or more groups to a community.
      operationId: linkCommunityGroups
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              communityId: "98372465382764532938"
              groupsPhones:
              - 1345353454354354-group
              - 1203634230225498-group
            schema:
              $ref: '#/components/schemas/CommunityLinkRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanSuccessResponse'
          description: Groups linked successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, community or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Link groups to community
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/communities/settings:
    post:
      description: Updates who can add new groups to the community.
      operationId: updateCommunitySettings
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              communityId: "98372465382764532938"
              whoCanAddNewGroups: admins
            schema:
              $ref: '#/components/schemas/CommunitySettingsRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanSuccessResponse'
          description: Settings updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update community settings
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/communities/unlink:
    post:
      description: Removes the association between groups and a community.
      operationId: unlinkCommunityGroups
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              communityId: "98372465382764532938"
              groupsPhones:
              - 1345353454354354-group
            schema:
              $ref: '#/components/schemas/CommunityLinkRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanSuccessResponse'
          description: Groups unlinked successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, community or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Unlink groups from community
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/contacts:
    get:
      description: |
        Returns a paginated list of WhatsApp contacts from the instance's device.

        **Features:**
        - ✅ Pagination support (page, pageSize)
        - ✅ Device contacts integration (name, short name)
        - ✅ WhatsApp profile data (notify/push name)
        - ✅ VCard information (if shared)
        - ✅ Privacy-aware (respects WhatsApp privacy settings)
        - ✅ X-Total-Count header for total count

        **Data Sources:**
        - Device address book (name, short, vname fields)
        - WhatsApp profile (notify field from push name)
        - VCard sharing (vname field)

        **Field Availability:**
        - `phone`: Always present (WhatsApp JID)
        - `name`, `short`, `vname`: Only if in address book
        - `notify`: Only if user has interacted with contact

        **Privacy Notes:** Contact data respects WhatsApp privacy settings.
        Users who hide their profile will only show notify field.
      operationId: getContacts
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Page number (1-indexed)
        example: 1
        in: query
        name: page
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Number of contacts per page (max 100)
        example: 20
        in: query
        name: pageSize
        required: true
        schema:
          maximum: 100
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              example:
              - name: João Silva Santos
                notify: João S.
                phone: "5511999999999"
                short: João
                vname: null
              - name: Maria Oliveira
                notify: Maria O.
                phone: "5511888888888"
                short: Maria
                vname: null
              - name: null
                notify: Carlos
                phone: "5511777777777"
                short: null
                vname: null
              schema:
                items:
                  $ref: '#/components/schemas/Contact'
                type: array
          description: Contacts retrieved successfully
          headers:
            X-Total-Count:
              description: Total number of contacts available
              example: 150
              schema:
                type: integer
        "400":
          content:
            application/json:
              example:
                error: page must be >= 1
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid pagination parameters
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: List WhatsApp contacts
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/contacts/{phone}/metadata:
    get:
      description: |
        Retrieves detailed metadata for a specific contact.

        **Data Returned:**
        - `name` — Full name (only if saved in contacts)
        - `phone` — Phone number
        - `notify` — WhatsApp display name
        - `short` — First name (only if saved in contacts)
        - `imgUrl` — Full-quality profile picture URL (expires after 48h)
        - `about` — Status/about text
      operationId: getContactMetadata
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number in international format (numbers only)
        example: "5511999999999"
        in: path
        name: phone
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactMetadataResponse'
          description: Contact metadata retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid phone number
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get contact metadata
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/contacts/{phone}/profile-picture:
    get:
      description: |
        Retrieves the profile picture URL for a specific contact.

        **Note:** Returns empty or error if contact has privacy settings
        that hide their profile picture from you.
      operationId: getContactProfilePicture
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number in international format (numbers only)
        example: "5511999999999"
        in: path
        name: phone
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilePictureResponse'
          description: Profile picture retrieved successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid phone number
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get contact profile picture
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/create-group:
    post:
      description: Creates a WhatsApp group with the provided participants.
      operationId: createGroup
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              autoInvite: true
              groupName: Grupo Zé da API
              phones:
              - "5544999999999"
              - "5544888888888"
            schema:
              $ref: '#/components/schemas/GroupCreateRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupCreateResponse'
          description: Group created successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Create group
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/create-newsletter:
    post:
      description: Creates a WhatsApp channel (newsletter) owned by the connected
        account.
      operationId: createNewsletter
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              description: Descrição do canal
              name: Nome do canal
            schema:
              $ref: '#/components/schemas/NewsletterCreateRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterCreateResponse'
          description: Channel created successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Create channel
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/delete-newsletter:
    delete:
      description: Deletes a channel owned by the connected account.
      operationId: deleteNewsletter
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
            schema:
              $ref: '#/components/schemas/NewsletterIdRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel deleted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Delete channel
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/device:
    get:
      description: Mirrors Zé da API `/device`, returning information about the currently
        linked phone.
      operationId: getInstanceDevice
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceDeviceResponse'
          description: Device metadata currently associated with the instance.
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Retrieve device metadata
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/disconnect:
    get:
      description: |
        Performs a complete disconnect with full cleanup, equivalent to logout/reset.

        **This operation performs the following actions:**

        - ✅ Disables auto-reconnect to prevent automatic reconnection
        - ✅ Disconnects WebSocket connection immediately
        - ✅ **Deletes device store from whatsmeow_store database**
        - ✅ Stops lock refresh goroutine
        - ✅ Releases Redis distributed lock
        - ✅ Removes client from in-memory registry
        - ✅ Clears store_jid in api_core database (sets to NULL)

        **Important Notes:**

        - The instance record remains in the database (status becomes "disconnected")
        - To permanently delete the instance, use `DELETE /partner/instances/{instanceId}`
        - After disconnect, you can reconnect by calling `/qrcode` or `/pairphone`
        - All webhook configurations are preserved

        **Use Cases:**

        - User logout from WhatsApp
        - Switching to a different phone number
        - Temporary disconnection for maintenance
        - Resetting a stuck connection

        **Comparison with DELETE endpoint:**

        - Disconnect: Keeps instance record, allows reconnection
        - Delete: Permanent removal, cannot be recovered
      operationId: disconnectInstanceGet
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                value: true
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Complete disconnect with cleanup accepted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid client token or instance token)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Complete disconnect with cleanup (Logout)
      tags:
      - Instances
    post:
      description: |
        Performs a complete disconnect with full cleanup, equivalent to logout/reset.

        **This operation performs the following actions:**
        - ✅ Disables auto-reconnect to prevent automatic reconnection
        - ✅ Disconnects WebSocket connection immediately
        - ✅ **Deletes device store from whatsmeow_store database**
        - ✅ Stops lock refresh goroutine
        - ✅ Releases Redis distributed lock
        - ✅ Removes client from in-memory registry
        - ✅ Clears store_jid in api_core database (sets to NULL)

        **Important Notes:**
        - The instance record remains in the database (status becomes "disconnected")
        - To permanently delete the instance, use `DELETE /partner/instances/{instanceId}`
        - After disconnect, you can reconnect by calling `/qrcode` or `/pairphone`
        - All webhook configurations are preserved

        **Use Cases:**
        - User logout from WhatsApp
        - Switching to a different phone number
        - Temporary disconnection for maintenance
        - Resetting a stuck connection

        **Comparison with DELETE endpoint:**
        - Disconnect: Keeps instance record, allows reconnection
        - Delete: Permanent removal, cannot be recovered
      operationId: disconnectInstance
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                value: true
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Complete disconnect with cleanup accepted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid client token or instance token)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Complete disconnect with cleanup (Logout)
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/dlq/events:
    get:
      description: Returns a paginated list of DLQ events for the instance, with optional
        filters by status and event type.
      operationId: listDLQEvents
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Page number (1-based)
        in: query
        name: page
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of events per page (max 100)
        in: query
        name: pageSize
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      - description: Filter by reprocess status
        in: query
        name: status
        schema:
          enum:
          - pending
          - processing
          - success
          - failed
          - discarded
          type: string
      - description: Filter by event type (e.g. message, receipt)
        in: query
        name: eventType
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQListResponse'
          description: Paginated list of DLQ events
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid parameters
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: List DLQ events
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/dlq/events/{eventId}:
    get:
      description: Returns full details of a single DLQ event, including the original
        payload and metadata.
      operationId: getDLQEvent
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: DLQ event UUID
        in: path
        name: eventId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQEventResponse'
          description: DLQ event details
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Event or instance not found
      security:
      - ClientTokenAuth: []
      summary: Get DLQ event detail
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/dlq/events/{eventId}/discard:
    post:
      description: Marks a DLQ event as discarded. Discarded events will not be retried
        and can be purged.
      operationId: discardDLQEvent
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: DLQ event UUID to discard
        in: path
        name: eventId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQRetryResponse'
          description: Event discarded
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Event or instance not found
      security:
      - ClientTokenAuth: []
      summary: Discard a DLQ event
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/dlq/events/{eventId}/retry:
    post:
      description: Re-enqueues a single DLQ event for delivery. The event must be
        in "pending" or "failed" state.
      operationId: retryDLQEvent
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: DLQ event UUID to retry
        in: path
        name: eventId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQRetryResponse'
          description: Event re-enqueued
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Event or instance not found
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Event is not in a retryable state
      security:
      - ClientTokenAuth: []
      summary: Retry a DLQ event
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/dlq/purge:
    delete:
      description: Deletes DLQ events with "success" or "discarded" status that are
        older than the specified number of days. Instance-scoped.
      operationId: purgeDLQEvents
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Delete resolved events older than this many days (default 7)
        in: query
        name: olderThanDays
        schema:
          default: 7
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQPurgeResponse'
          description: Purge result
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Purge resolved DLQ events
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/dlq/retry-all:
    post:
      description: Bulk-retries all retryable (pending and failed) DLQ events for
        the instance, up to a configurable limit.
      operationId: retryAllDLQEvents
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Maximum number of events to retry (default 100, max 500)
        in: query
        name: limit
        schema:
          default: 100
          maximum: 500
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQRetryAllResponse'
          description: Bulk retry result
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Retry all retryable DLQ events
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/dlq/stats:
    get:
      description: Returns aggregated DLQ statistics for the instance, including counts
        by status, event type, and failure reason. If NATS is enabled, also includes
        JetStream DLQ stream stats.
      operationId: getDLQStats
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DLQStatsResponse'
          description: DLQ statistics
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Get DLQ statistics
      tags:
      - Dead Letter Queue
  /instances/{instanceId}/token/{instanceToken}/follow-newsletter:
    put:
      description: Follows a channel (newsletter) to receive updates.
      operationId: followNewsletter
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
            schema:
              $ref: '#/components/schemas/NewsletterIdRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel followed successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Follow channel
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/forward-message:
    post:
      description: |
        Forwards an existing message to another chat.

        **Features:**
        - Forward any message type (text, media, etc.)
        - Preserves original message metadata
        - Shows "Forwarded" label on recipient's device
        - FIFO queue with per-recipient ordering
      operationId: forwardMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              isGroup: false
              messageId: 3EB047ED70306656281B34
              phone: "5511888888888"
            schema:
              $ref: '#/components/schemas/ForwardMessageRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message forwarded successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Forward a message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/group-invitation-link/{groupId}:
    post:
      description: Returns the current invitation link for a group.
      operationId: getGroupInvitationLink
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Group JID (suffix `-group`).
        in: path
        name: groupId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupInvitationLinkResponse'
          description: Invitation link retrieved successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get group invitation link
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/group-invitation-metadata:
    get:
      description: Resolves a group invitation link and returns metadata about the
        group.
      operationId: getGroupInvitationMetadata
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Group invitation URL.
        in: query
        name: url
        required: true
        schema:
          format: uri
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupInvitationMetadataResponse'
          description: Invitation metadata returned successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or invitation not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Resolve group invitation metadata
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/group-metadata/{groupId}:
    get:
      description: Returns detailed metadata for a specific group.
      operationId: getGroupMetadata
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Group JID (suffix `-group`).
        in: path
        name: groupId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMetadataResponse'
          description: Group metadata returned successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get group metadata
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/groups:
    get:
      description: Returns a paginated list of WhatsApp groups the instance participates
        in.
      operationId: listGroups
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Page number (1-indexed).
        example: 1
        in: query
        name: page
        required: true
        schema:
          minimum: 1
          type: integer
      - description: Number of groups to return per page.
        example: 10
        in: query
        name: pageSize
        required: true
        schema:
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/GroupListItem'
                type: array
          description: Array of groups (unwrapped, matching Zé da API behaviour).
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List groups
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/integrator/client-token:
    delete:
      description: |
        Removes the custom `Client-Token` from a specific instance, revoking the subscriber's
        ability to authenticate with their per-instance token.

        After deletion, **only** the global `CLIENT_AUTH_TOKEN` will be accepted for this instance.
        This effectively revokes direct API access for the subscriber while preserving the
        Manager's (dashboard) ability to operate the instance via the global token.

        **Use cases:**
        - Revoking a subscriber's direct API access after subscription cancellation.
        - Security incident response — immediately invalidate a compromised per-instance token.
        - Resetting token state before assigning a new one via PUT.

        **Behavior:**
        - Sets `client_auth_token` to `NULL` in the database.
        - Idempotent: calling DELETE when no per-instance token exists succeeds with the same response.
        - Does not affect the global `CLIENT_AUTH_TOKEN`.
      operationId: partnerDeleteClientToken
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                clientAuthToken: null
                updated: true
              schema:
                $ref: '#/components/schemas/ClientTokenDeleteResponse'
          description: Client-Token successfully removed (or was already absent)
        "400":
          content:
            application/json:
              examples:
                invalidId:
                  summary: Malformed UUID
                  value:
                    error: invalid instance id
                missingToken:
                  summary: Missing instance token in URL
                  value:
                    error: missing instance token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid instance ID format or missing instance token
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing or invalid Partner Bearer token
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found (invalid instanceId or instanceToken mismatch)
        "500":
          content:
            application/json:
              example:
                error: internal error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error while removing the token
      security:
      - PartnerBearer: []
      summary: Remove per-instance Client-Token
      tags:
      - Partner
    put:
      description: |
        Assigns a custom `Client-Token` to a specific instance, allowing the instance owner
        (subscriber) to authenticate instance-scoped API calls with their own token instead of
        the global `CLIENT_AUTH_TOKEN`.

        **Authentication model:**
        - The API validates the `Client-Token` header on every instance-scoped request.
        - Two values are accepted: the global token (from `CLIENT_AUTH_TOKEN` env var) **or**
          the per-instance token stored in the database.
        - Setting a per-instance token does **not** invalidate the global token — both remain valid.

        **Use cases:**
        - SaaS platforms generating unique tokens per subscriber so each subscriber only has
          access to their own instances.
        - Revoking a subscriber's access by deleting their per-instance token (see DELETE endpoint).
        - Rotating a subscriber's token without affecting other instances.

        **Validation:**
        - `clientAuthToken` must be a non-empty string.
        - The instance is identified by both `instanceId` and `instanceToken` in the URL path.
        - Requires Partner Bearer authentication.
      operationId: partnerUpdateClientToken
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              clientAuthToken: a1b2c3d4-e5f6-7890-abcd-ef1234567890
            schema:
              $ref: '#/components/schemas/ClientTokenUpdateRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                clientAuthToken: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                updated: true
              schema:
                $ref: '#/components/schemas/ClientTokenUpdateResponse'
          description: Client-Token successfully set or updated
        "400":
          content:
            application/json:
              examples:
                invalidJson:
                  summary: Malformed JSON body
                  value:
                    error: invalid json payload
                missingField:
                  summary: Empty or absent clientAuthToken
                  value:
                    error: clientAuthToken is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid JSON payload or missing `clientAuthToken` field
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing or invalid Partner Bearer token
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found (invalid instanceId or instanceToken mismatch)
        "500":
          content:
            application/json:
              example:
                error: internal error
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error while updating the token
      security:
      - PartnerBearer: []
      summary: Set or update per-instance Client-Token
      tags:
      - Partner
  /instances/{instanceId}/token/{instanceToken}/integrator/on-demand/cancel:
    post:
      description: Cancels the on-demand subscription for the instance, matching Zé
        da API behaviour.
      operationId: partnerCancelInstance
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
          description: Subscription cancelled
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - PartnerBearer: []
      summary: Cancel partner subscription
      tags:
      - Partner
  /instances/{instanceId}/token/{instanceToken}/integrator/on-demand/subscription:
    post:
      description: Enables on-demand billing/usage for the specified instance (Zé
        da API parity).
      operationId: partnerSubscribeInstance
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationStatusResponse'
          description: Subscription activated
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - PartnerBearer: []
      summary: Activate partner subscription
      tags:
      - Partner
  /instances/{instanceId}/token/{instanceToken}/leave-group:
    post:
      description: Removes the connected WhatsApp account from a group.
      operationId: leaveGroup
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              groupId: 120363019502650977-group
            schema:
              $ref: '#/components/schemas/GroupLeaveRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Left the group successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Leave group
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/light-group-metadata/{groupId}:
    get:
      description: Returns metadata for a specific group without fetching the invitation
        link (lower latency variant).
      operationId: getLightGroupMetadata
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Group JID (suffix `-group`).
        in: path
        name: groupId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMetadataResponse'
          description: Group metadata returned successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get group metadata (light)
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/messages:
    delete:
      description: |
        Deletes (revokes) a previously sent message from a chat.

        **Features:**
        - ✅ Delete own messages (sender = you)
        - ✅ Delete others' messages (group admin only)
        - ✅ Works in private chats and groups
        - ✅ query parameters


        Uses query parameters instead of request body:
        - `phone` - The chat phone number (recipient)
        - `messageId` - The WhatsApp message ID to delete
        - `owner` - "true" for own messages, "false" for others (admin delete)

        **Behavior:**
        - For `owner=true`: Message is deleted for everyone ("Delete for Everyone")
        - For `owner=false`: Admin delete in groups (removes message sent by others)
        - Deleted messages show "This message was deleted" placeholder

        **Restrictions:**
        - Own messages: Can be deleted within ~1 hour of sending
        - Admin delete: Requires group admin privileges
        - Once deleted, the message cannot be recovered
      operationId: deleteMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Phone number of the chat (recipient)
        example: "5511999999999"
        in: query
        name: phone
        required: true
        schema:
          type: string
      - description: WhatsApp message ID to delete
        example: 3EB047ED70306656281B34
        in: query
        name: messageId
        required: true
        schema:
          type: string
      - description: |
          Whether the message was sent by you:
          - "true" = your own message (Delete for Everyone)
          - "false" = someone else's message (admin delete in groups)
        example: "true"
        in: query
        name: owner
        required: true
        schema:
          enum:
          - "true"
          - "false"
          type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                adminDelete:
                  summary: Admin deleted message
                  value:
                    message: message deleted successfully
                    messageId: 3EB047ED70306656281B34
                    phone: 120363356737170752@g.us
                    success: true
                ownMessage:
                  summary: Own message deleted
                  value:
                    message: message deleted successfully
                    messageId: 3EB047ED70306656281B34
                    phone: "5511999999999"
                    success: true
              schema:
                $ref: '#/components/schemas/DeleteMessageResponse'
          description: Message deleted successfully
        "400":
          content:
            application/json:
              examples:
                missingMessageId:
                  summary: Missing message ID
                  value:
                    error: messageId is required
                missingOwner:
                  summary: Missing owner flag
                  value:
                    error: owner is required
                missingPhone:
                  summary: Missing phone
                  value:
                    error: phone is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing parameters)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "500":
          content:
            application/json:
              example:
                error: 'failed to delete message: timeout'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Failed to delete message
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Delete message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/messages-status:
    get:
      description: |
        Query the cached status of message deliveries. Status Cache stores delivery receipts
        (sent, delivered, read, played) for messages, especially useful for group messages
        where tracking individual participant statuses is important.

        **Important:** This endpoint works independently of webhook configuration.
        You can use Status Cache in API-only mode (pull) without configuring any webhooks.

        **Query Types:**
        - **No filter**: Get ALL cached statuses for the instance (paginated)
        - By `messageId`: Get status for a specific message
        - By `groupId`: Get all message statuses for a group
        - By `phone`: Get all message statuses for a phone number

        **Response Formats:**
        - `aggregated` (default): Returns aggregated counts and optionally participant details
        - `raw`: Returns data in Zé da API webhook format for compatibility

        **Use Cases:**
        - Check if a message was read by all group participants
        - Get delivery statistics for messages to a specific contact
        - Retrieve batch status updates for UI dashboards
        - Poll for status updates without webhook configuration

        **Note:** Status data is cached with a configurable TTL (default 24h).

        **Requirements:**
        - `STATUS_CACHE_ENABLED=true` environment variable
        - `STATUS_CACHE_SCOPE` must include the message type (groups, direct, or both)
      operationId: getMessagesStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: |
          Query status for a specific message. When provided, returns detailed status
          for that message including all participant statuses.
        example: 3EB0A1B2C3D4E5F6
        in: query
        name: messageId
        required: false
        schema:
          type: string
      - description: |
          Query all message statuses for a group. Returns paginated results.
          The groupId should be the numeric part of the WhatsApp JID (without @g.us).
        example: "120363182823169824"
        in: query
        name: groupId
        required: false
        schema:
          type: string
      - description: |
          Query all message statuses for messages to/from a phone number.
          Use E.164 format without the + prefix.
        example: "5511999999999"
        in: query
        name: phone
        required: false
        schema:
          type: string
      - description: |
          Response format:
          - `aggregated`: Returns aggregated counts with optional participant details
          - `raw`: Returns data in Zé da API MessageStatusCallback webhook format
        in: query
        name: format
        required: false
        schema:
          default: aggregated
          enum:
          - aggregated
          - raw
          type: string
      - description: Maximum number of results to return (1-1000).
        in: query
        name: limit
        required: false
        schema:
          default: 100
          maximum: 1000
          minimum: 1
          type: integer
      - description: Number of results to skip for pagination.
        in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          type: integer
      - description: |
          When true and format is `aggregated`, includes the full list of
          participant statuses in the response. Useful for detailed analysis
          but increases response size significantly for groups.
        in: query
        name: includeParticipants
        required: false
        schema:
          default: false
          type: boolean
      responses:
        "200":
          content:
            application/json:
              examples:
                aggregatedSingle:
                  summary: Single message aggregated status
                  value:
                    data:
                    - createdAt: 1703548800000
                      groupId: "120363182823169824"
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: true
                      messageId: 3EB0A1B2C3D4E5F6
                      phone: 120363182823169824-group
                      status:
                        delivered: 95
                        played: 0
                        read: 42
                        sent: 100
                      totalParticipants: 100
                      updatedAt: 1703552400000
                    meta:
                      limit: 100
                      offset: 0
                      total: 1
                aggregatedWithParticipants:
                  summary: With participant details
                  value:
                    data:
                    - createdAt: 1703548800000
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: false
                      messageId: 3EB0A1B2C3D4E5F6
                      participants:
                      - device: 1
                        phone: "5511999999999"
                        status: read
                        timestamp: 1703548900000
                      phone: "5511999999999"
                      status:
                        delivered: 1
                        played: 0
                        read: 1
                        sent: 1
                      totalParticipants: 1
                      updatedAt: 1703548900000
                    meta:
                      limit: 100
                      offset: 0
                      total: 1
                allStatuses:
                  description: When no filter is provided, returns all cached statuses
                    for the instance with pagination
                  summary: All cached statuses (no filter)
                  value:
                    data:
                    - createdAt: 1703548800000
                      groupId: "120363182823169824"
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: true
                      messageId: 3EB0A1B2C3D4E5F6
                      phone: 120363182823169824-group
                      status:
                        delivered: 45
                        played: 0
                        read: 20
                        sent: 50
                      totalParticipants: 50
                      updatedAt: 1703552400000
                    - createdAt: 1703548900000
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: false
                      messageId: 3EB0A1B2C3D4E5F7
                      phone: "5511999999999"
                      status:
                        delivered: 1
                        played: 0
                        read: 1
                        sent: 1
                      totalParticipants: 1
                      updatedAt: 1703549000000
                    meta:
                      limit: 100
                      offset: 0
                      total: 150
                allStatusesRaw:
                  description: Use format=raw to get data in EXACT webhook payload
                    format
                  summary: All cached statuses in raw/webhook format
                  value:
                    data:
                    - chatLid: ""
                      fromMe: true
                      ids:
                      - 3EB0A1B2C3D4E5F6
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: true
                      momment: 1703548900000
                      participantLid: ""
                      phone: "120363182823169824"
                      senderDevice: 1
                      status: read
                      type: MessageStatusCallback
                    - chatLid: ""
                      fromMe: true
                      ids:
                      - 3EB0A1B2C3D4E5F7
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: false
                      momment: 1703549000000
                      participantLid: ""
                      phone: "5511999999999"
                      senderDevice: 1
                      status: delivered
                      type: MessageStatusCallback
                    meta:
                      limit: 100
                      offset: 0
                      total: 150
                empty:
                  summary: No cached status found
                  value:
                    data: []
                    meta:
                      limit: 0
                      offset: 0
                      total: 0
                rawFormat:
                  summary: Raw
                  value:
                    data:
                    - fromMe: true
                      ids:
                      - 3EB0A1B2C3D4E5F6
                      instanceId: 550e8400-e29b-41d4-a716-446655440000
                      isGroup: false
                      momment: 1703548900000
                      phone: "5511999999999"
                      senderDevice: 1
                      status: read
                      type: MessageStatusCallback
                    meta:
                      limit: 100
                      offset: 0
                      total: 1
              schema:
                oneOf:
                - $ref: '#/components/schemas/StatusCacheQueryResult'
                - $ref: '#/components/schemas/StatusCacheRawQueryResult'
          description: Status data retrieved successfully.
        "400":
          content:
            application/json:
              example:
                error: invalid instance id
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request - invalid parameters
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized - invalid or missing Client-Token
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - ClientTokenAuth: []
      summary: Query message delivery status
      tags:
      - Status Cache
  /instances/{instanceId}/token/{instanceToken}/messages-status/cache:
    delete:
      description: |
        Removes cached status entries from the status cache.

        **Options:**
        - Clear by `messageId`: Removes cache for a specific message
        - Clear all (`all=true`): Removes all cached entries for the instance

        **Warning:** Clearing cache is irreversible. Cached status data and pending
        webhooks for cleared entries will be permanently deleted.

        **Use Cases:**
        - Free up cache storage space
        - Remove obsolete message status data
        - Reset cache after testing
      operationId: clearMessagesStatusCache
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Clear cache for a specific message ID.
        example: 3EB0A1B2C3D4E5F6
        in: query
        name: messageId
        required: false
        schema:
          type: string
      - description: Set to true to clear all cached entries for this instance.
        in: query
        name: all
        required: false
        schema:
          default: false
          type: boolean
      responses:
        "200":
          content:
            application/json:
              examples:
                allCleared:
                  summary: All entries cleared
                  value:
                    cleared: 150
                singleMessage:
                  summary: Single message cleared
                  value:
                    cleared: 1
                    messageId: 3EB0A1B2C3D4E5F6
              schema:
                oneOf:
                - $ref: '#/components/schemas/StatusCacheClearSingleResult'
                - $ref: '#/components/schemas/StatusCacheClearAllResult'
          description: Cache cleared successfully.
        "400":
          content:
            application/json:
              example:
                error: specify messageId or set all=true
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request - missing parameter
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - ClientTokenAuth: []
      summary: Clear cached status entries
      tags:
      - Status Cache
  /instances/{instanceId}/token/{instanceToken}/messages-status/flush:
    post:
      description: |
        Triggers delivery of suppressed webhooks for cached status events.

        When `STATUS_CACHE_SUPPRESS_WEBHOOKS=true`, status webhooks are not immediately
        sent but stored for later delivery. This endpoint allows manual triggering
        of those pending webhooks.

        **Webhook Requirement:** This endpoint REQUIRES a webhook to be configured:
        - Primary: `messageStatusCallbackUrl`
        - Fallback: `deliveryCallbackUrl`

        If no webhook is configured, flush will succeed but no data will be delivered.
        In API-only mode, use `/messages-status` GET endpoint instead.

        **Use Cases:**
        - Force immediate delivery of status updates to webhook endpoints
        - Recover from webhook endpoint downtime
        - Batch process status updates at specific intervals

        **Options:**
        - Flush by specific `messageId`: Delivers webhooks for one message
        - Flush all (`all: true`): Delivers all pending webhooks for the instance

        **Note:** Flushing is idempotent - already-flushed webhooks won't be re-sent.
      operationId: flushMessagesStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              flushAll:
                summary: Flush all pending
                value:
                  all: true
              flushMessage:
                summary: Flush specific message
                value:
                  messageId: 3EB0A1B2C3D4E5F6
            schema:
              $ref: '#/components/schemas/StatusCacheFlushRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                noPending:
                  summary: No pending webhooks
                  value:
                    flushed: 0
                    webhooksTriggered: 0
                success:
                  summary: Flush completed
                  value:
                    flushed: 15
                    webhooksTriggered: 15
              schema:
                $ref: '#/components/schemas/StatusCacheFlushResult'
          description: Flush completed successfully.
        "400":
          content:
            application/json:
              examples:
                invalidBody:
                  summary: Invalid request body
                  value:
                    error: invalid request body
                missingParam:
                  summary: Missing parameter
                  value:
                    error: specify messageId or set all=true
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request - invalid parameters
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - ClientTokenAuth: []
      summary: Flush pending webhooks
      tags:
      - Status Cache
  /instances/{instanceId}/token/{instanceToken}/messages-status/stats:
    get:
      description: |
        Returns statistics about the status cache for this instance.

        **Important:** This endpoint works independently of webhook configuration.
        Use it to verify that Status Cache is receiving and storing events.

        **Metrics included:**
        - Total cached entries
        - Entries breakdown by instance
        - Number of pending webhooks awaiting flush

        **Use Cases:**
        - Monitor cache usage and storage
        - Determine if flush is needed
        - Debug cache behavior
        - Verify Status Cache is working (totalEntries > 0)

        **Troubleshooting:**
        If `totalEntries` is 0, check:
        1. `STATUS_CACHE_ENABLED=true` is set
        2. `STATUS_CACHE_SCOPE` matches your message types (groups/direct)
        3. `STATUS_CACHE_TYPES` includes the receipt types you expect (read,delivered,played,sent)
      operationId: getMessagesStatusStats
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                entriesByInstance:
                  550e8400-e29b-41d4-a716-446655440000: 1500
                pendingWebhooks: 45
                totalEntries: 1500
              schema:
                $ref: '#/components/schemas/StatusCacheStats'
          description: Statistics retrieved successfully.
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - ClientTokenAuth: []
      summary: Get cache statistics
      tags:
      - Status Cache
  /instances/{instanceId}/token/{instanceToken}/modify-blocked:
    post:
      description: |
        Blocks or unblocks a WhatsApp contact.

        **Actions:**
        - `block`: Block the contact (they can't message you)
        - `unblock`: Unblock a previously blocked contact
      operationId: modifyBlocked
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              action: block
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/ModifyBlockedRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModifyBlockedResponse'
          description: Contact blocked/unblocked successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Block or unblock a contact
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/modify-chat:
    post:
      description: |
        Performs various chat modification actions like read, archive, pin, mute, clear, or delete.

        **Supported Actions:**
        - `read` - Mark chat as read
        - `archive` - Archive the chat
        - `unarchive` - Unarchive the chat
        - `pin` - Pin the chat to top
        - `unpin` - Unpin the chat
        - `mute` - Mute chat notifications
        - `unmute` - Unmute chat notifications
        - `clear` - Clear all messages in chat
        - `delete` - Delete the entire chat


        Request body with `phone` and `action` fields.

        **Behavior:**
        - `read`: Marks all messages in chat as read (blue checkmarks)
        - `archive/unarchive`: Moves chat to/from archive
        - `pin/unpin`: Pins/unpins chat to top of chat list
        - `mute/unmute`: Enables/disables notifications
        - `clear`: Removes all messages but keeps chat
        - `delete`: Completely removes the chat
      operationId: modifyChat
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              archiveChat:
                description: Move chat to archive
                summary: Archive chat
                value:
                  action: archive
                  phone: "5511999999999"
              clearChat:
                description: Remove all messages from chat
                summary: Clear chat
                value:
                  action: clear
                  phone: "5511999999999"
              deleteChat:
                description: Completely remove the chat
                summary: Delete chat
                value:
                  action: delete
                  phone: "5511999999999"
              markRead:
                description: Mark all messages in chat as read
                summary: Mark chat as read
                value:
                  action: read
                  phone: "5511999999999"
              muteChat:
                description: Disable notifications for chat
                summary: Mute notifications
                value:
                  action: mute
                  phone: "5511999999999"
              pinChat:
                description: Pin chat to top of list
                summary: Pin chat
                value:
                  action: pin
                  phone: "5511999999999"
              unarchiveChat:
                description: Remove chat from archive
                summary: Unarchive chat
                value:
                  action: unarchive
                  phone: "5511999999999"
              unmuteChat:
                description: Enable notifications for chat
                summary: Unmute notifications
                value:
                  action: unmute
                  phone: "5511999999999"
              unpinChat:
                description: Unpin chat from top
                summary: Unpin chat
                value:
                  action: unpin
                  phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/ModifyChatRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                archiveSuccess:
                  summary: Archived
                  value:
                    action: archive
                    message: chat archived successfully
                    phone: "5511999999999"
                    success: true
                muteSuccess:
                  summary: Muted
                  value:
                    action: mute
                    message: chat muted successfully
                    phone: "5511999999999"
                    success: true
                pinSuccess:
                  summary: Pinned
                  value:
                    action: pin
                    message: chat pinned successfully
                    phone: "5511999999999"
                    success: true
                readSuccess:
                  summary: Marked as read
                  value:
                    action: read
                    message: chat marked as read successfully
                    phone: "5511999999999"
                    success: true
              schema:
                $ref: '#/components/schemas/ModifyChatResponse'
          description: Chat modified successfully
        "400":
          content:
            application/json:
              examples:
                invalidAction:
                  summary: Invalid action
                  value:
                    error: 'invalid action: must be one of read, archive, unarchive,
                      pin, unpin, mute, unmute, clear, delete'
                missingAction:
                  summary: Missing action
                  value:
                    error: action is required
                missingPhone:
                  summary: Missing phone
                  value:
                    error: phone is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "500":
          content:
            application/json:
              example:
                error: 'failed to modify chat: operation not supported'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Failed to modify chat
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Modify chat
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/mute-newsletter:
    put:
      description: Mutes notifications for a channel.
      operationId: muteNewsletter
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
            schema:
              $ref: '#/components/schemas/NewsletterIdRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel muted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Mute channel
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter:
    get:
      description: Returns metadata for channels followed or owned by the connected
        account.
      operationId: listNewsletters
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/NewsletterMetadata'
                type: array
          description: Array of channels (unwrapped, matching Zé da API behaviour).
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List channels
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter/accept-admin-invite/{newsletterId}:
    post:
      description: Accepts an invitation to become administrator of a channel.
      operationId: acceptNewsletterAdminInvite
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Channel identifier (suffix `@newsletter`).
        in: path
        name: newsletterId
        required: true
        schema:
          type: string
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Admin invitation accepted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Accept channel admin invite
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter/metadata/{newsletterId}:
    get:
      description: Returns metadata about a specific channel (newsletter).
      operationId: getNewsletterMetadata
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Channel identifier (suffix `@newsletter`).
        in: path
        name: newsletterId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterMetadata'
          description: Channel metadata returned successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get channel metadata
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter/remove-admin/{newsletterId}:
    post:
      description: Removes an administrator from a channel.
      operationId: removeNewsletterAdmin
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Channel identifier (suffix `@newsletter`).
        in: path
        name: newsletterId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              phone: "5544999999999"
            schema:
              $ref: '#/components/schemas/NewsletterAdminActionRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Administrator removed successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Remove channel admin
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter/revoke-admin-invite/{newsletterId}:
    post:
      description: Revokes a pending administrator invitation for a channel.
      operationId: revokeNewsletterAdminInvite
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Channel identifier (suffix `@newsletter`).
        in: path
        name: newsletterId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              phone: "5544999999999"
            schema:
              $ref: '#/components/schemas/NewsletterAdminActionRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Invitation revoked successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Revoke channel admin invite
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter/settings/{newsletterId}:
    post:
      description: Updates channel reaction settings.
      operationId: updateNewsletterSettings
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Channel identifier (suffix `@newsletter`).
        in: path
        name: newsletterId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              reactionCodes: basic
            schema:
              $ref: '#/components/schemas/NewsletterSettingsRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel settings updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update channel settings
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/newsletter/transfer-ownership/{newsletterId}:
    post:
      description: Transfers ownership of a channel to another administrator.
      operationId: transferNewsletterOwnership
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Channel identifier (suffix `@newsletter`).
        in: path
        name: newsletterId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Transfer ownership and keep current admin role
                value:
                  phone: "5544999999999"
              quitAdmin:
                summary: Transfer ownership and leave admin role
                value:
                  phone: "5544999999999"
                  quitAdmin: true
            schema:
              $ref: '#/components/schemas/NewsletterTransferOwnershipRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterTransferOwnershipResponse'
          description: Ownership transfer attempted.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Transfer channel ownership
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/phone-code/{phone}:
    get:
      description: Mirrors Zé da API `/phone-code/{phone}`, returning a code that
        can be typed into WhatsApp instead of scanning the QR code.
      operationId: getInstancePhoneCode
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: International phone number (numbers only) used for code pairing.
        in: path
        name: phone
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneCodeResponse'
          description: Pairing code generated for the provided phone number.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid phone number supplied.
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Fetch phone pairing code
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/phone-exists-batch:
    post:
      description: |
        Validates multiple phone numbers to check if they are registered on WhatsApp.

        **Use Cases:**
        - Bulk contact validation before marketing campaigns
        - CRM data cleansing and enrichment
        - Lead qualification at scale
        - Form validation with multiple numbers

        **Important Notes:**
        - Maximum batch size: 50,000 numbers per request
        - Use for validation purposes, not before sending messages
        - Not designed for spam - use responsibly

        **Phone Format:**
        - International format: DDI + DDD + NUMBER
        - Numbers only (no formatting, spaces, or masks)
        - Example: `551199999999` (Brazil mobile)

        **Response Fields:**
        - `exists`: Whether the phone has WhatsApp
        - `inputPhone`: The number as you sent it
        - `outputPhone`: The number formatted by WhatsApp (may include 9th digit)
      operationId: phoneExistsBatch
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              phones:
              - "554499999999"
              - "554488888888"
            schema:
              $ref: '#/components/schemas/PhoneExistsBatchRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
              - exists: true
                inputPhone: "554499999999"
                outputPhone: "554499999999"
              - exists: false
                inputPhone: "554488888888"
                outputPhone: "554488888888"
              schema:
                items:
                  $ref: '#/components/schemas/PhoneExistsBatchResponse'
                type: array
          description: Batch validation results
        "400":
          content:
            application/json:
              examples:
                batch_exceeded:
                  value:
                    error: Batch size exceeds maximum limit of 50000 numbers
                empty_array:
                  value:
                    error: Phones array is required and cannot be empty
                invalid_format:
                  value:
                    error: Phone at index 0 must contain only digits
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (empty array, invalid format, or batch size
            exceeded)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "500":
          content:
            application/json:
              example:
                error: Failed to check phone numbers
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        "503":
          content:
            application/json:
              example:
                error: Contacts service not available
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Contacts service not available
      security:
      - ClientTokenAuth: []
      summary: Batch validate phone numbers on WhatsApp
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/phone-exists/{phone}:
    get:
      description: |
        Verifies if a phone number is registered on WhatsApp.

        **Use Cases:**
        - Form validation (verify phone before saving)
        - Contact verification before sending messages
        - Lead qualification in CRM systems

        **Important Notes:**
        - Use this API for form validation purposes
        - Do NOT use before sending messages (Zé da API validates automatically)
        - Using for message validation creates duplicate checks
        - Not designed for spam - use responsibly

        **Phone Format:**
        - International format: DDI + DDD + NUMBER
        - Numbers only (no formatting, spaces, or masks)
        - Example: `551199999999` (Brazil mobile)
      operationId: phoneExists
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: |
          Phone number in international format (DDI DDD NUMBER).
          Numbers only - no formatting, spaces, or masks.
        example: "551199999999"
        in: path
        name: phone
        required: true
        schema:
          pattern: ^\d+$
          type: string
      responses:
        "200":
          content:
            application/json:
              examples:
                exists_with_lid:
                  description: Phone number is registered on WhatsApp and LID is available
                  summary: Phone exists with LID
                  value:
                    exists: true
                    lid: 140712372899859@lid
                    phone: "5521979232690"
                exists_without_lid:
                  description: Phone number is registered but LID is not available
                  summary: Phone exists without LID
                  value:
                    exists: true
                    lid: null
                    phone: "5521979232690"
                not_exists:
                  description: Phone number is not registered on WhatsApp
                  summary: Phone does not exist
                  value:
                    exists: false
                    lid: null
                    phone: null
              schema:
                $ref: '#/components/schemas/PhoneExistsResponse'
          description: Phone validation result
        "400":
          content:
            application/json:
              example:
                error: Phone number must contain only digits
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid phone number format
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "500":
          content:
            application/json:
              example:
                error: Failed to check phone number
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        "503":
          content:
            application/json:
              example:
                error: Contacts service not available
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Contacts service not available
      security:
      - ClientTokenAuth: []
      summary: Check if phone number has WhatsApp
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/pin-message:
    post:
      description: |
        Pins or unpins a chat in the chat list.

        **Note:** This pins/unpins the entire chat, not individual messages.

        **Features:**
        - Pin important conversations to top of chat list
        - Unpin to remove from pinned section
      operationId: pinMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              phone: "5511999999999"
              pin: true
            schema:
              $ref: '#/components/schemas/PinMessageRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinMessageResponse'
          description: Chat pinned/unpinned successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Pin or unpin a chat
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/privacy-settings:
    get:
      description: |
        Retrieves all privacy settings for the connected WhatsApp account.

        **Settings Returned:**
        - `groupAdd`: Who can add you to groups (all, contacts, contact_blacklist)
        - `lastSeen`: Who can see your last seen (all, contacts, contact_blacklist, none)
        - `status`: Who can see your status (all, contacts, contact_blacklist, none)
        - `profile`: Who can see your profile photo (all, contacts, contact_blacklist, none)
        - `readReceipts`: Read receipts setting (all, none)
        - `online`: Online status visibility (all, match_last_seen)
        - `callAdd`: Who can call you (all, known)
      operationId: getPrivacySettings
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                callAdd: all
                groupAdd: contacts
                lastSeen: contacts
                online: all
                profile: contacts
                readReceipts: all
                status: all
              schema:
                $ref: '#/components/schemas/PrivacySettingsResponse'
          description: Privacy settings retrieved successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get privacy settings
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/call-add:
    put:
      description: |
        Updates who can call you.

        **Values:**
        - `all`: Anyone can call you
        - `known`: Only known contacts can call you
      operationId: updatePrivacyCallAdd
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: all
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update call privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/group-add:
    put:
      description: |
        Updates who can add you to WhatsApp groups.

        **Values:**
        - `all`: Anyone can add you
        - `contacts`: Only contacts can add you
        - `contact_blacklist`: Contacts except blocked
      operationId: updatePrivacyGroupAdd
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: contacts
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update group add privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/last-seen:
    put:
      description: |
        Updates who can see your last seen time.

        **Values:**
        - `all`: Everyone can see
        - `contacts`: Only contacts can see
        - `contact_blacklist`: Contacts except blocked
        - `none`: Nobody can see
      operationId: updatePrivacyLastSeen
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: contacts
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update last seen privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/online:
    put:
      description: |
        Updates online status visibility.

        **Values:**
        - `all`: Everyone can see when you're online
        - `match_last_seen`: Match your last seen setting
      operationId: updatePrivacyOnline
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: all
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update online status privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/profile-photo:
    put:
      description: |
        Updates who can see your profile photo.

        **Values:**
        - `all`: Everyone can see
        - `contacts`: Only contacts can see
        - `contact_blacklist`: Contacts except blocked
        - `none`: Nobody can see
      operationId: updatePrivacyProfilePhoto
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: contacts
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update profile photo privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/read-receipts:
    put:
      description: |
        Updates read receipts (blue ticks) setting.

        **Values:**
        - `all`: Send and receive read receipts
        - `none`: Disable read receipts (you won't see others' either)
      operationId: updatePrivacyReadReceipts
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: all
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update read receipts privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/privacy-settings/status:
    put:
      description: |
        Updates who can see your status updates.

        **Values:**
        - `all`: Everyone can see
        - `contacts`: Only contacts can see
        - `contact_blacklist`: Contacts except blocked
        - `none`: Nobody can see
      operationId: updatePrivacyStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              value: contacts
            schema:
              $ref: '#/components/schemas/UpdatePrivacyRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePrivacyResponse'
          description: Privacy setting updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid value
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update status privacy
      tags:
      - Privacy
  /instances/{instanceId}/token/{instanceToken}/products:
    post:
      description: Adds a new product to the instance catalog.
      operationId: createProduct
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                currency:
                  type: string
                description:
                  type: string
                images:
                  items:
                    type: string
                  type: array
                isHidden:
                  type: boolean
                name:
                  type: string
                price:
                  type: integer
                retailerId:
                  type: string
                salePrice:
                  type: integer
                url:
                  type: string
              required:
              - name
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                type: object
          description: Product created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Create a product
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/products/{productId}:
    delete:
      description: Removes a product from the instance catalog.
      operationId: deleteProduct
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Product identifier
        in: path
        name: productId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                type: object
          description: Product deleted
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Product or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Delete a product
      tags:
      - Business
    get:
      description: Returns details of a specific product from the instance catalog.
      operationId: getProduct
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Product identifier
        in: path
        name: productId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  cartEnabled:
                    type: boolean
                  catalogId:
                    type: string
                  product:
                    properties:
                      availability:
                        type: string
                      currency:
                        type: string
                      description:
                        type: string
                      id:
                        type: string
                      images:
                        items:
                          type: string
                        type: array
                      isHidden:
                        type: boolean
                      name:
                        type: string
                      price:
                        type: string
                      quantity:
                        nullable: true
                        type: boolean
                      retailerId:
                        nullable: true
                        type: string
                      salePrice:
                        type: string
                      url:
                        type: string
                    type: object
                type: object
          description: Product details
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Product or instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Get a single product
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/profile-description:
    put:
      description: |
        Updates the profile description (About/Status) for the connected WhatsApp account.

        **Note:** This is the text that appears in your profile's "About" section.
        Can be empty to clear the description.
      operationId: updateProfileDescription
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              description: Available for business inquiries
            schema:
              $ref: '#/components/schemas/UpdateProfileDescriptionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProfileDescriptionResponse'
          description: Profile description updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update profile description
      tags:
      - Profile
  /instances/{instanceId}/token/{instanceToken}/profile-name:
    put:
      description: |
        Updates the profile name (push name) for the connected WhatsApp account.

        **Note:** This is the name that appears to other users in their
        chat list and message notifications.
      operationId: updateProfileName
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              name: John Doe
            schema:
              $ref: '#/components/schemas/UpdateProfileNameRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProfileNameResponse'
          description: Profile name updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update profile name
      tags:
      - Profile
  /instances/{instanceId}/token/{instanceToken}/profile-picture:
    put:
      description: |
        Updates the profile picture for the connected WhatsApp account.

        **Image Format:**
        - Base64-encoded JPEG image
        - Image URL (http/https)
        - Empty string to remove profile picture

        **Requirements:**
        - JPEG format recommended
        - Other formats may be rejected
      operationId: updateProfilePicture
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              image: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...
            schema:
              $ref: '#/components/schemas/UpdateProfilePictureRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProfilePictureResponse'
          description: Profile picture updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request or image format
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update profile picture
      tags:
      - Profile
  /instances/{instanceId}/token/{instanceToken}/proxy:
    delete:
      description: |
        Removes the proxy configuration from this instance.
        The client reverts to direct connection (or environment proxy).
      operationId: removeProxy
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueResponse'
          description: Proxy removed
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Remove proxy configuration
      tags:
      - Proxy
    get:
      description: Returns the current proxy configuration and health status for this
        instance.
      operationId: getProxy
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  proxy:
                    $ref: '#/components/schemas/ProxyConfig'
                  value:
                    type: boolean
                type: object
          description: Proxy configuration
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Get proxy configuration
      tags:
      - Proxy
  /instances/{instanceId}/token/{instanceToken}/proxy/health:
    get:
      description: |
        Returns the current proxy health status along with recent health check logs.
        Useful for monitoring proxy reliability and diagnosing connectivity issues.
      operationId: getProxyHealth
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyHealthResponse'
          description: Proxy health status and logs
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Get proxy health status and history
      tags:
      - Proxy
  /instances/{instanceId}/token/{instanceToken}/proxy/swap:
    post:
      description: |
        Atomically swaps the proxy on an active WhatsApp connection.
        The new proxy is tested before applying. The client is disconnected
        from the current proxy and immediately reconnected through the new one.
        The WhatsApp session is preserved - only the transport changes.

        **Important:** The proxy is validated before swap. If the new proxy
        is unreachable, the swap is rejected and the current connection is maintained.
      operationId: swapProxy
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxySwapRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  proxy:
                    $ref: '#/components/schemas/ProxyConfig'
                  value:
                    type: boolean
                type: object
          description: Proxy swapped successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid proxy URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Proxy unreachable - swap rejected
      security:
      - ClientTokenAuth: []
      summary: Hot-swap proxy on active connection
      tags:
      - Proxy
  /instances/{instanceId}/token/{instanceToken}/proxy/test:
    post:
      description: |
        Tests a proxy URL by attempting to connect through it to WhatsApp servers.
        Does NOT apply the proxy - use update-proxy to apply it.
        Returns reachability status and latency.
      operationId: testProxy
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProxyTestRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyTestResponse'
          description: Proxy test result
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid proxy URL format
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Test proxy connectivity
      tags:
      - Proxy
  /instances/{instanceId}/token/{instanceToken}/qr-code:
    get:
      description: Mirrors Zé da API `/qr-code`, returning the current QR string required
        to link a phone.
      operationId: getInstanceQRCode
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            text/plain:
              schema:
                type: string
          description: Current QR code payload (text/plain)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Fetch QR code for pairing
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/qr-code/image:
    get:
      description: Mirrors Zé da API `/qr-code/image`, returning a PNG image encoded
        in base64 for rendering in clients.
      operationId: getInstanceQRCodeImage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QRCodeImageResponse'
          description: QR code rendered as base64 PNG data URL.
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Fetch QR code as base64 image
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/queue:
    delete:
      description: |+
        Clears all pending messages from the queue for a specific instance.

        **Behavior:**
        - ✅ Removes messages in state: `available`, `scheduled`
        - ❌ Does NOT affect messages: `running`, `completed`, `failed`, `discarded`

        **Use Cases:**
        - Emergency stop of all pending messages
        - Queue cleanup during maintenance
        - Cancel all scheduled messages at once



      operationId: clearQueue
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                message: Queue cleared successfully
              schema:
                $ref: '#/components/schemas/QueueClearResponse'
          description: Queue cleared successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid or missing Client-Token)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Clear all pending messages in queue
      tags:
      - Queue
    get:
      description: |
        Lists all messages in the queue for a specific instance with pagination.



        - Uses `page` and `pageSize` parameters
        - Returns direct array of messages (not wrapped in object)
        - Field names in camelCase
        - Delays in seconds (not milliseconds)
        - Created timestamp in milliseconds

        **Response Format:**
        - Direct array: `[{message1}, {message2}, ...]`
        - NOT wrapped: `{data: [{message1}]}` ❌

        **Pagination:**
        - `page`: Page number starting from 1
        - `pageSize`: Messages per page (default 100, max 1000)
      operationId: listQueueMessages
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Page number (1-indexed)
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of messages per page
        example: 50
        in: query
        name: pageSize
        required: false
        schema:
          default: 100
          maximum: 1000
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              example:
              - _id: 39BB1684570F00E91090F6BBC7EE7646
                attempt: 0
                created: 1624977905648
                delayMessage: 5
                delayTyping: 3
                instanceId: 550e8400-e29b-41d4-a716-446655440000
                maxAttempts: 3
                message: Hello from Zé da API
                messageId: 7AD29EAA5EF34C301F0B
                messageType: text
                phone: "5511999999999"
                sequenceNumber: 1
                status: available
                zaapId: 39BB1684570F00E91090F6BBC7EE7646
              - _id: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
                attempt: 0
                created: 1624977906000
                delayMessage: 0
                delayTyping: 0
                instanceId: 550e8400-e29b-41d4-a716-446655440000
                maxAttempts: 3
                message: null
                messageId: F5G6H7I8J9K0L1M2N3O4
                messageType: image
                phone: 120363XXXXX@g.us
                sequenceNumber: 2
                status: scheduled
                zaapId: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
              schema:
                $ref: '#/components/schemas/QueueListResponse'
          description: List of queue messages (direct array)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid or missing Client-Token)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: List messages in queue with pagination
      tags:
      - Queue
  /instances/{instanceId}/token/{instanceToken}/queue/{zaapId}:
    delete:
      description: |+
        Cancels a pending message by its zaapId (returned when message was enqueued).

        **Behavior:**
        - ✅ Cancels messages in state: `available`, `scheduled`, `retryable`
        - ❌ Returns error if message already processed or doesn't exist



      operationId: cancelQueueMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Message ID returned when message was sent (zaapId)
        example: 39BB1684570F00E91090F6BBC7EE7646
        in: path
        name: zaapId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              example:
                message: Message cancelled successfully
              schema:
                $ref: '#/components/schemas/QueueCancelResponse'
          description: Message cancelled successfully
        "400":
          content:
            application/json:
              example:
                error: 'job not found or already processed: 39BB1684570F00E91090F6BBC7EE7646'
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Message not found or already processed
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid or missing Client-Token)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Cancel a specific message in queue
      tags:
      - Queue
  /instances/{instanceId}/token/{instanceToken}/queue/count:
    get:
      description: |+
        Returns the total number of messages in the queue for a specific instance.



      operationId: getQueueCount
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                count: 42
              schema:
                $ref: '#/components/schemas/QueueCountResponse'
          description: Queue message count
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid or missing Client-Token)
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Get queue message count
      tags:
      - Queue
  /instances/{instanceId}/token/{instanceToken}/read-message:
    post:
      description: |
        Marks one or more messages as read (sends read receipts/blue ticks).

        **Features:**
        - Mark single or multiple messages as read
        - Works for both individual and group chats
        - Immediate execution (not queued)
      operationId: readMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              messageIds:
              - 3EB047ED70306656281B34
              - 3EB047ED70306656281B35
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/ReadMessageRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadMessageResponse'
          description: Messages marked as read successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Mark messages as read
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/redefine-invitation-link/{resourceId}:
    post:
      description: Generates a new invitation link for a group or community.
      operationId: redefineInvitationLink
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      - description: Group JID (suffix `-group`) or community ID whose invitation
          link should be reset.
        in: path
        name: resourceId
        required: true
        schema:
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitationLinkResponse'
          description: Invitation link regenerated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, group or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Redefine invitation link
      tags:
      - Groups
      - Communities
  /instances/{instanceId}/token/{instanceToken}/reject-participant:
    post:
      description: Rejects pending join requests for a group.
      operationId: rejectGroupParticipants
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              groupId: 120363019502650977-group
              phones:
              - "5544999999999"
              - "5544888888888"
            schema:
              $ref: '#/components/schemas/GroupParticipantListRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Participants rejected successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Reject participants
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/remove-admin:
    post:
      description: Removes administrator privileges from participants in a group or
        community.
      operationId: removeAdministrators
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              community:
                summary: Demote community administrators
                value:
                  communityId: "120363019502650977"
                  phones:
                  - "5544999999999"
                  - "5544888888888"
              group:
                summary: Demote group administrators
                value:
                  groupId: 120363019502650977-group
                  phones:
                  - "5544999999999"
                  - "5544888888888"
            schema:
              oneOf:
              - $ref: '#/components/schemas/GroupParticipantListRequest'
              - $ref: '#/components/schemas/CommunityAdminMutationRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Administrators demoted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, group or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Demote administrators
      tags:
      - Groups
      - Communities
  /instances/{instanceId}/token/{instanceToken}/remove-contact:
    post:
      description: |
        Removes a contact from the WhatsApp address book using AppState sync.
      operationId: removeContact
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/RemoveContactRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveContactResponse'
          description: Contact removed successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Remove contact from address book
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/remove-participant:
    post:
      description: Removes participants from a group or a community announcements
        group.
      operationId: removeParticipants
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              community:
                summary: Remove participants from a community
                value:
                  communityId: "120363019502650977"
                  phones:
                  - "5544999999999"
                  - "5544888888888"
              group:
                summary: Remove participants from a group
                value:
                  groupId: 120363019502650977-group
                  phones:
                  - "5544999999999"
                  - "5544888888888"
            schema:
              oneOf:
              - $ref: '#/components/schemas/GroupParticipantListRequest'
              - $ref: '#/components/schemas/CommunityParticipantListRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Participants removed successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance, group or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Remove participants
      tags:
      - Groups
      - Communities
  /instances/{instanceId}/token/{instanceToken}/resolve-lids:
    post:
      description: |
        Resolves WhatsApp Linked IDs (LIDs) to phone numbers using the local LID mapping store.

        After WhatsApp's LID migration, some contacts are stored with @lid JIDs instead
        of phone-based JIDs. This endpoint resolves those LIDs to actual phone numbers
        when a mapping is available in the local store.

        **Important Notes:**
        - Resolution depends on existing LID mappings in the store
        - Mappings are populated when IsOnWhatsApp or GetUserInfo are called
        - New instances may have empty LID stores until contacts are queried
        - Maximum batch size: 1,000 LIDs per request
      operationId: resolveLids
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              lids:
              - 102473725436019:0@lid
              - 98765432109876:0@lid
            schema:
              $ref: '#/components/schemas/LIDResolveBatchRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                results:
                - lid: 102473725436019:0@lid
                  phone: "5511999999999"
                  phoneJid: 5511999999999@s.whatsapp.net
                  resolved: true
                - lid: 98765432109876:0@lid
                  resolved: false
              schema:
                $ref: '#/components/schemas/LIDResolveBatchResponse'
          description: LID resolution results
        "400":
          content:
            application/json:
              examples:
                batch_exceeded:
                  value:
                    error: Batch size exceeds maximum limit of 1000 LIDs
                empty_array:
                  value:
                    error: LIDs array is required and cannot be empty
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "500":
          content:
            application/json:
              example:
                error: Failed to resolve LIDs
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        "503":
          content:
            application/json:
              example:
                error: Contacts service not available
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Contacts service not available
      security:
      - ClientTokenAuth: []
      summary: Resolve LIDs to phone numbers
      tags:
      - Contacts
  /instances/{instanceId}/token/{instanceToken}/restart:
    get:
      description: Equivalent to Zé da API `/restart`, forcing the client to reconnect
        to WhatsApp.
      operationId: restartInstanceGet
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                value: true
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Restart signal accepted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Restart an instance connection
      tags:
      - Instances
    post:
      description: Equivalent to Zé da API `/restart`, forcing the client to reconnect
        to WhatsApp.
      operationId: restartInstance
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              example:
                value: true
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Restart signal accepted
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Restart an instance connection
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/search-newsletter:
    post:
      description: Searches for public channels using the filters supported by WhatsApp.
      operationId: searchNewsletters
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              filters:
                countryCodes:
                - BR
                - CA
              limit: 50
              searchText: Zé da API
              view: TRENDING
            schema:
              $ref: '#/components/schemas/NewsletterSearchRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsletterSearchResponse'
          description: Search results returned successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Search channels
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/send-audio:
    post:
      description: |+
        Sends an audio or voice note via WhatsApp.

        **Features:**
        - ✅ Audio URL or base64 data URI support
        - ✅ Voice note (PTT) detection
        - ✅ "Recording audio" indicator (delayTyping)
        - ✅ View once support
        - ✅ Reply-to message support
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)

        **Supported Formats:** OGG, MP3, WAV



      operationId: sendAudioMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              audio: https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3
              delayTyping: 5
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendAudioRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send audio/voice message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-audio-status:
    post:
      description: |
        Sends an audio message to WhatsApp Status/Stories as a voice note with waveform visualization.

        **Status Broadcasting**: The audio is automatically broadcast to all contacts
        who can view your status based on your privacy settings. No phone number
        is required - the message is sent to `status@broadcast`.

        **Key Features**:
        - Audio URL or base64 data URI support
        - **Automatic waveform generation** (64 samples for visual bars - "ondinhas")
        - Voice note (PTT) format with waveform visualization
        - Automatic conversion to Opus/OGG if needed
        - FIFO queue with non-blocking response
        - Optional custom message ID for tracking

        **Waveform Visualization**: The audio is processed to generate
        64 amplitude samples (0-100 range) that WhatsApp displays as
        the classic wave bars in the voice note player. This creates the
        familiar "ondinhas" (little waves) visualization.

        **Supported Formats**: OGG (Opus), MP3, WAV, M4A, AAC, FLAC

        **Working Audio URLs for Testing**:
        | Source | URL | Description |
        |--------|-----|-------------|
        | SoundHelix | https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3 | Electronic music |
        | SampleLib | https://samplelib.com/lib/preview/mp3/sample-3s.mp3 | 3-second sample |
        | File Examples | https://filesamples.com/samples/audio/mp3/sample1.mp3 | MP3 sample |
        | Internet Archive | https://archive.org/download/testmp3testfile/mpthreetest.mp3 | Test MP3 |

        **Audio Processing Pipeline**:
        1. Download audio from URL or decode base64
        2. Detect format and convert to Opus/OGG if needed
        3. Generate 64-sample waveform for visualization
        4. Calculate duration for progress bar
        5. Upload to WhatsApp servers
        6. Send as PTT (Push-To-Talk) voice note
      operationId: sendAudioStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              archive_audio:
                description: Public domain test audio from Internet Archive
                summary: Internet Archive test audio
                value:
                  audio: https://archive.org/download/testmp3testfile/mpthreetest.mp3
              delayed_send:
                description: Audio with 5-second delay before sending
                summary: Delayed audio send
                value:
                  audio: https://samplelib.com/lib/preview/mp3/sample-9s.mp3
                  delayMessage: 5
              electronic_music:
                description: Full electronic music track from SoundHelix
                summary: Electronic music track
                value:
                  audio: https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3
              medium_sample:
                description: Medium length audio sample
                summary: 6-second sample
                value:
                  audio: https://samplelib.com/lib/preview/mp3/sample-6s.mp3
                  delayMessage: 2
              mp3_test_file:
                description: Standard MP3 file for compatibility testing
                summary: Standard MP3 test file
                value:
                  audio: https://filesamples.com/samples/audio/mp3/sample1.mp3
              short_sample:
                description: Brief audio clip for quick testing
                summary: Short 3-second sample
                value:
                  audio: https://samplelib.com/lib/preview/mp3/sample-3s.mp3
              song_track_3:
                description: Another electronic music option
                summary: Electronic track 3
                value:
                  audio: https://www.soundhelix.com/examples/mp3/SoundHelix-Song-3.mp3
              with_custom_id:
                description: Audio status with tracking ID
                summary: Audio with custom message ID
                value:
                  audio: https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3
                  messageId: voice-status-promo-001
            schema:
              $ref: '#/components/schemas/SendAudioStatusRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    id: c3d4e5f6-a7b8-9012-cdef-345678901234
                    messageId: 3EB0F4326B5A8C93D4E4
                    status: QUEUED
                    zaapId: BAE5F4326B5A8C93
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Status message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                download_failed:
                  summary: Failed to download audio
                  value:
                    code: DOWNLOAD_ERROR
                    error: failed to download audio from URL
                invalid_format:
                  summary: Unsupported audio format
                  value:
                    code: VALIDATION_ERROR
                    error: unsupported audio format
                missing_audio:
                  summary: Missing audio field
                  value:
                    code: VALIDATION_ERROR
                    error: audio is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing audio or invalid format)
        "401":
          content:
            application/json:
              example:
                code: UNAUTHORIZED
                error: invalid client token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized - Invalid or missing Client-Token
        "404":
          content:
            application/json:
              example:
                code: NOT_FOUND
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                code: SERVICE_UNAVAILABLE
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send audio/voice note to WhatsApp Status
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-button-actions:
    post:
      description: |
        Sends an interactive message with action buttons (CTA buttons).
        Supports URL, call, copy, and quick reply buttons.

        **Button Types:**
        - `quick_reply` - Simple reply button (max 20 chars label)
        - `cta_url` - Opens a URL in browser
        - `cta_call` - Initiates a phone call
        - `cta_copy` - Copies text to clipboard
        - `payment_info` - Payment information button
        - `review_and_pay` - Review and pay action

        **Features:**
        - ✅ Up to 3 action buttons
        - ✅ Optional header image
        - ✅ Title, message body, and footer
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering

        **Limits:**
        - Max 3 buttons per message
        - Label: max 25 characters (20 for quick_reply)
        - Title: max 60 characters
        - Message: max 1024 characters
        - Footer: max 60 characters
      operationId: sendButtonActionsMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              callButton:
                description: Message with a button to initiate a phone call
                summary: Call button
                value:
                  buttons:
                  - id: btn_call
                    label: Call Support
                    phone: "+5511999999999"
                    type: cta_call
                  footer: Available 24/7
                  message: Our support team is ready to assist you. Call us now!
                  phone: "5511999999999"
                  title: Need Help?
              copyButton:
                description: Message with a button to copy a discount code
                summary: Copy code button
                value:
                  buttons:
                  - copyCode: SAVE20OFF
                    id: btn_copy
                    label: Copy Code
                    type: cta_copy
                  footer: Valid until end of month
                  message: Use this exclusive code for 20% off your next purchase.
                  phone: "5511999999999"
                  title: Special Discount!
              multipleButtons:
                description: Message with multiple different action buttons
                summary: Multiple action buttons
                value:
                  buttons:
                  - id: btn_web
                    label: Visit Website
                    type: cta_url
                    url: https://httpbin.org/get
                  - id: btn_call
                    label: Call Us
                    phone: "+5511999999999"
                    type: cta_call
                  - copyCode: support@httpbin.org
                    id: btn_email
                    label: Copy Email
                    type: cta_copy
                  footer: We're here to help!
                  image: https://picsum.photos/600/400.jpg
                  message: Choose how you would like to get in touch with our team.
                  phone: "5511999999999"
                  title: Contact Us
              quickReplyButtons:
                description: Simple reply buttons for quick responses
                summary: Quick reply buttons
                value:
                  buttons:
                  - id: newsletter_yes
                    label: Yes, subscribe me
                    type: quick_reply
                  - id: newsletter_no
                    label: No, thanks
                    type: quick_reply
                  - id: newsletter_later
                    label: Maybe later
                    type: quick_reply
                  message: Would you like to receive our newsletter?
                  phone: "5511999999999"
                  title: Quick Question
              urlButton:
                description: Message with a button that opens a website
                summary: Single URL button
                value:
                  buttons:
                  - id: btn_url
                    label: Visit Website
                    type: cta_url
                    url: https://httpbin.org/anything/products
                  footer: Click the button below
                  message: Check out our latest products and special offers!
                  phone: "5511999999999"
                  title: Visit Our Website
              withImage:
                description: Action buttons with promotional image
                summary: With header image
                value:
                  buttons:
                  - id: btn_shop
                    label: Shop Now
                    type: cta_url
                    url: https://httpbin.org/anything/spring-2024
                  delayMessage: 3
                  footer: Limited stock available
                  image: https://picsum.photos/600/400.jpg
                  message: Discover our Spring 2024 collection with exclusive designs.
                  phone: "5511999999999"
                  title: New Collection Available!
            schema:
              $ref: '#/components/schemas/SendButtonActionsRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                invalidButtonType:
                  summary: Invalid button type
                  value:
                    error: 'invalid button type: must be one of quick_reply, cta_url,
                      cta_call, cta_copy, payment_info, review_and_pay'
                missingButtons:
                  summary: Missing buttons
                  value:
                    error: buttons is required and must have at least 1 item
                missingPhone:
                  summary: Missing phone for cta_call button
                  value:
                    error: phone is required for cta_call button type
                missingUrl:
                  summary: Missing URL for cta_url button
                  value:
                    error: url is required for cta_url button type
                tooManyButtons:
                  summary: Too many buttons
                  value:
                    error: buttons cannot have more than 3 items
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send interactive action buttons message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-button-list:
    post:
      description: |
        Sends an interactive button list message with quick reply buttons.
        The recipient can tap a button to respond.

        **Features:**
        - ✅ Up to 3 quick reply buttons
        - ✅ Header title and message body
        - ✅ Footer text
        - ✅ Optional image or video header
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering
        - ✅ Non-blocking (returns immediately with zaapId)

        **Limits:**
        - Max 3 buttons
        - Title: max 60 characters
        - Message: max 1024 characters
        - Footer: max 60 characters
        - Button title: max 20 characters

        **Use Cases:**
        - Quick response options (Yes/No/Maybe)
        - Survey responses
        - Confirmation dialogs
        - Simple navigation
      operationId: sendButtonListMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              serviceOptions:
                description: Quick reply buttons for customer support
                summary: Customer service quick actions
                value:
                  buttons:
                  - id: support_tech
                    title: Technical Help
                  - id: support_billing
                    title: Billing Question
                  - id: support_other
                    title: Other
                  footer: Select an option
                  message: How can we help you today?
                  phone: "5511999999999"
                  title: Customer Support
              simpleButtons:
                description: Basic button list with quick reply options
                summary: Simple reply buttons
                value:
                  buttons:
                  - id: btn_yes
                    title: "Yes"
                  - id: btn_no
                    title: "No"
                  - id: btn_maybe
                    title: Maybe Later
                  footer: Tap a button to continue
                  message: Please select one of the options below
                  phone: "5511999999999"
                  title: Choose an Option
              withDelay:
                description: Button message with custom delay before sending
                summary: With message delay
                value:
                  buttons:
                  - id: rate_good
                    title: Good
                  - id: rate_bad
                    title: Bad
                  delayMessage: 5
                  delayTyping: 3
                  message: Please share your feedback
                  phone: "5511999999999"
                  title: Quick Survey
              withImage:
                description: Button list with product image
                summary: Buttons with image header
                value:
                  buttons:
                  - id: buy_now
                    title: Buy Now
                  - id: more_info
                    title: More Info
                  footer: Limited time offer
                  image: https://picsum.photos/600/400.jpg
                  message: Get 20% off on this product today!
                  phone: "5511999999999"
                  title: Special Offer!
            schema:
              $ref: '#/components/schemas/SendButtonListRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                missingButtons:
                  summary: Missing buttons
                  value:
                    error: At least one button is required
                missingMessage:
                  summary: Missing message
                  value:
                    error: message is required
                missingPhone:
                  summary: Missing phone number
                  value:
                    error: phone is required
                titleTooLong:
                  summary: Title too long
                  value:
                    error: title cannot exceed 60 characters
                tooManyButtons:
                  summary: Too many buttons
                  value:
                    error: buttons cannot have more than 3 items
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send interactive button list message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-button-otp:
    post:
      description: |
        Sends a one-time password (OTP) message with a copy button.
        The recipient can easily copy the code with one tap.

        **Use Cases:**
        - Account verification
        - Two-factor authentication (2FA)
        - Password reset codes
        - Login verification
        - Transaction confirmation

        **Features:**
        - ✅ Prominent OTP code display
        - ✅ One-tap copy button
        - ✅ Custom button text
        - ✅ Expiration message support
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering

        **Security Notes:**
        - OTP codes should have limited validity (typically 5-10 minutes)
        - Messages automatically include security warnings
        - Never log or store OTP codes in plain text
      operationId: sendButtonOtpMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              login2fa:
                description: 2FA login code
                summary: Two-factor authentication
                value:
                  code: "789012"
                  message: Your login verification code for MyApp. If you didn't request
                    this, please ignore this message.
                  phone: "5511999999999"
                  title: Login Verification
              numericOnly:
                description: Short numeric code
                summary: Simple numeric OTP
                value:
                  code: "0000"
                  message: 'Your code:'
                  phone: "5511999999999"
              passwordReset:
                description: Code for password reset flow
                summary: Password reset code
                value:
                  code: RESET-ABC123
                  footer: Valid for 10 minutes
                  message: Use this code to reset your password. This code is valid
                    for 10 minutes only.
                  phone: "5511999999999"
                  title: Password Reset
              transactionConfirm:
                description: Code to confirm a financial transaction
                summary: Transaction confirmation
                value:
                  code: TXN-998877
                  message: Confirm your transaction of $500.00 to Account ****1234.
                    Enter this code in the app to proceed.
                  phone: "5511999999999"
                  title: Transaction Confirmation
              verification:
                description: Standard verification code message
                summary: Account verification code
                value:
                  code: "123456"
                  footer: Code expires in 5 minutes
                  message: Your verification code is below. This code expires in 5
                    minutes. Do not share it with anyone.
                  phone: "5511999999999"
                  title: Verification Code
              withCustomId:
                description: OTP message with custom message ID for tracking
                summary: OTP with tracking ID
                value:
                  code: AUTH-112233
                  message: Your authentication code for session verification.
                  messageId: auth-session-abc123-otp
                  phone: "5511999999999"
                  title: Authentication
              withDelay:
                description: Delayed OTP message
                summary: OTP with delay
                value:
                  code: SEC-456789
                  delayMessage: 2
                  footer: Valid for 5 minutes
                  message: Security code for your account access. Valid for 5 minutes.
                  phone: "5511999999999"
                  title: Security Code
            schema:
              $ref: '#/components/schemas/SendButtonOTPRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                emptyCode:
                  summary: Empty OTP code
                  value:
                    error: code cannot be empty
                missingCode:
                  summary: Missing OTP code
                  value:
                    error: code is required
                missingPhone:
                  summary: Missing phone number
                  value:
                    error: phone is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send OTP (One-Time Password) message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-button-pix:
    post:
      description: |
        Sends an interactive message with PIX payment information (Brazilian instant payment system).
        Includes QR code generation and copy-paste PIX code button.

        **PIX Key Types:**
        - `CPF` - Brazilian individual taxpayer ID (11 digits)
        - `CNPJ` - Brazilian company taxpayer ID (14 digits)
        - `EMAIL` - Email address
        - `PHONE` - Phone number with country code
        - `EVP` - Random PIX key (UUID format)

        **Features:**
        - ✅ Automatic PIX QR code generation
        - ✅ Copy PIX code button
        - ✅ Payment amount and description
        - ✅ Beneficiary name display
        - ✅ Transaction ID for reconciliation
        - ✅ Additional action buttons
        - ✅ Custom message ID for tracking
        - ✅ FIFO queue with per-recipient ordering

        **Required Fields:**
        - `phone` - Recipient WhatsApp number
        - `payment.keyType` - Type of PIX key
        - `payment.key` - The PIX key value
        - `payment.name` - Beneficiary name
        - `payment.amount` - Payment amount in BRL
      operationId: sendButtonPixMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              cnpjKey:
                description: Payment request using company taxpayer ID
                summary: PIX with CNPJ key
                value:
                  amount: 1500
                  footer: Company Name Ltd
                  message: Pay your invoice instantly via PIX
                  name: Company Name Ltd
                  phone: "5511999999999"
                  pixKey: "12345678000199"
                  title: Invoice Payment
                  transactionId: INV2024001
                  type: CNPJ
              cpfKey:
                description: Payment request using individual taxpayer ID
                summary: PIX with CPF key
                value:
                  amount: 99.9
                  footer: Secure instant payment
                  message: Please complete your purchase payment via PIX
                  name: John Doe
                  phone: "5511999999999"
                  pixKey: "12345678900"
                  title: Payment Request
                  transactionId: ORDER12345
                  type: CPF
              emailKey:
                description: Donation request using email as PIX key
                summary: PIX with email key
                value:
                  amount: 50
                  footer: Thank you for your support!
                  message: Your donation helps us continue our work
                  name: Charity Organization
                  phone: "5511999999999"
                  pixKey: donations@charity.org
                  title: Support Our Cause
                  type: EMAIL
              evpKey:
                description: Payment using random PIX key (UUID)
                summary: PIX with EVP (random) key
                value:
                  amount: 85.5
                  message: Your share of the dinner bill
                  name: Restaurant Name
                  phone: "5511999999999"
                  pixKey: 123e4567-e89b-12d3-a456-426614174000
                  title: Split Bill Payment
                  transactionId: DINNER-TABLE15-001
                  type: EVP
              phoneKey:
                description: Payment using phone number as PIX key
                summary: PIX with phone key
                value:
                  amount: 750
                  message: Payment for design services
                  name: Jane Designer
                  phone: "5511999999999"
                  pixKey: "+5511988887777"
                  title: Pay Freelancer
                  type: PHONE
              withDelay:
                description: Payment request with typing delay
                summary: PIX with message delay
                value:
                  amount: 299.99
                  delayMessage: 5
                  delayTyping: 3
                  footer: Questions? Contact us!
                  message: Pay via PIX to confirm your order
                  name: Seller Name
                  phone: "5511999999999"
                  pixKey: "98765432100"
                  title: Complete Your Order
                  type: CPF
            schema:
              $ref: '#/components/schemas/SendButtonPIXRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                invalidAmount:
                  summary: Invalid amount
                  value:
                    error: payment.amount must be greater than 0
                invalidCnpj:
                  summary: Invalid CNPJ format
                  value:
                    error: 'invalid CNPJ format: must be 14 digits'
                invalidCpf:
                  summary: Invalid CPF format
                  value:
                    error: 'invalid CPF format: must be 11 digits'
                invalidKeyType:
                  summary: Invalid PIX key type
                  value:
                    error: 'payment.keyType must be one of: CPF, CNPJ, EMAIL, PHONE,
                      EVP'
                missingName:
                  summary: Missing beneficiary name
                  value:
                    error: payment.name is required
                missingPayment:
                  summary: Missing payment information
                  value:
                    error: payment is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send PIX payment message (Brazil)
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-carousel:
    post:
      description: |
        Sends an interactive carousel message with multiple cards.
        Each card can have an image/video header, body text, and action buttons.

        **Features:**
        - ✅ 1-10 cards per carousel
        - ✅ Image or video header per card
        - ✅ Body text per card
        - ✅ Up to 2 action buttons per card
        - ✅ Horizontal swipe navigation
        - ✅ Introduction message before carousel
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering

        **Limits:**
        - Min 1 card, max 10 cards
        - Max 2 buttons per card
        - Body text: max 1024 characters per card
        - Header media: image or video URL

        **Use Cases:**
        - Product catalogs
        - Image galleries
        - Service showcases
        - Portfolio presentations
        - Tutorial sequences

        **Media Formats:**
        - Images: JPEG, PNG, WebP
        - Videos: MP4 (recommended), 3GP
      operationId: sendCarouselMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              imageGallery:
                description: Photo gallery showcase
                summary: Image gallery
                value:
                  cardType: ALBUM_IMAGE
                  cards:
                  - body: |-
                      Golden Sunset

                      Captured at Pacific Beach, California
                    buttons:
                    - id: btn_sunset
                      label: Like
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/10/600/400.jpg
                  - body: |-
                      Mountain Majesty

                      Swiss Alps in winter
                    buttons:
                    - id: btn_mountains
                      label: Like
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/11/600/400.jpg
                  - body: |-
                      Ocean Waves

                      Maldives crystal clear waters
                    buttons:
                    - id: btn_ocean
                      label: Like
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/12/600/400.jpg
                  - body: |-
                      Forest Path

                      Redwood National Park
                    buttons:
                    - id: btn_forest
                      label: Like
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/13/600/400.jpg
                  - body: |-
                      City Lights

                      New York City skyline at night
                    buttons:
                    - id: btn_city
                      label: Like
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/14/600/400.jpg
                  message: Our photo gallery - swipe through our favorite moments!
                  phone: "5511999999999"
              productCatalog:
                description: E-commerce product showcase
                summary: Product catalog
                value:
                  cardType: HSCROLL_CARDS
                  cards:
                  - body: |-
                      Premium Widget Pro

                      Our flagship product with advanced features.

                      $199.99
                    buttons:
                    - id: btn_view_pro
                      label: View Details
                      type: cta_url
                      url: https://httpbin.org/anything/products/widget-pro
                    - id: add_widget_pro
                      label: Add to Cart
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/1/600/400.jpg
                  - body: |-
                      Standard Widget

                      Perfect for everyday use.

                      $99.99
                    buttons:
                    - id: btn_view_basic
                      label: View Details
                      type: cta_url
                      url: https://httpbin.org/anything/products/widget-basic
                    - id: add_widget_basic
                      label: Add to Cart
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/2/600/400.jpg
                  - body: |-
                      Mini Widget

                      Compact and portable design.

                      $49.99
                    buttons:
                    - id: btn_view_mini
                      label: View Details
                      type: cta_url
                      url: https://httpbin.org/anything/products/widget-mini
                    - id: add_widget_mini
                      label: Add to Cart
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/3/600/400.jpg
                  message: Check out our amazing products! Swipe to explore our catalog.
                  phone: "5511999999999"
              realEstate:
                description: Property listings carousel
                summary: Real estate listings
                value:
                  cardType: HSCROLL_CARDS
                  cards:
                  - body: |-
                      Modern Family Home

                      4 bed | 3 bath | 2,500 sqft
                      Pacific Heights, SF

                      $1,250,000
                    buttons:
                    - id: btn_view_house1
                      label: View Listing
                      type: cta_url
                      url: https://httpbin.org/anything/property/house1
                    - id: btn_call_house1
                      label: Call Agent
                      phone: "+14155551234"
                      type: cta_call
                    mediaUrl: https://picsum.photos/id/49/600/400.jpg
                  - body: |-
                      Luxury Condo

                      2 bed | 2 bath | 1,200 sqft
                      SoMa District

                      $850,000
                    buttons:
                    - id: btn_view_condo1
                      label: View Listing
                      type: cta_url
                      url: https://httpbin.org/anything/property/condo1
                    - id: btn_call_condo1
                      label: Call Agent
                      phone: "+14155551234"
                      type: cta_call
                    mediaUrl: https://picsum.photos/id/164/600/400.jpg
                  - body: |-
                      Charming Townhouse

                      3 bed | 2.5 bath | 1,800 sqft
                      Mission District

                      $975,000
                    buttons:
                    - id: btn_view_townhouse1
                      label: View Listing
                      type: cta_url
                      url: https://httpbin.org/anything/property/townhouse1
                    - id: btn_call_townhouse1
                      label: Call Agent
                      phone: "+14155551234"
                      type: cta_call
                    mediaUrl: https://picsum.photos/id/188/600/400.jpg
                  message: Featured properties in your area - find your dream home
                    today!
                  phone: "5511999999999"
              restaurantMenu:
                description: Visual menu with images
                summary: Restaurant menu
                value:
                  cardType: HSCROLL_CARDS
                  cards:
                  - body: |-
                      Prime Ribeye Steak

                      12oz USDA Prime, grilled to perfection
                      Served with seasonal vegetables

                      $45.00
                    buttons:
                    - id: order_steak
                      label: Order Now
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/292/600/400.jpg
                  - body: |-
                      Atlantic Salmon

                      Fresh salmon with lemon butter sauce
                      Asparagus and rice pilaf

                      $32.00
                    buttons:
                    - id: order_salmon
                      label: Order Now
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/493/600/400.jpg
                  - body: |-
                      Truffle Pasta

                      Fresh fettuccine with black truffle
                      Parmesan and cream sauce

                      $28.00
                    buttons:
                    - id: order_pasta
                      label: Order Now
                      type: quick_reply
                    mediaUrl: https://picsum.photos/id/312/600/400.jpg
                  message: Today's specials - fresh ingredients, exceptional taste!
                  messageId: menu-daily-specials
                  phone: "5511999999999"
              singleCard:
                description: Carousel with just one card
                summary: Single card carousel
                value:
                  cardType: HSCROLL_CARDS
                  cards:
                  - body: |-
                      Limited Edition Product

                      Only 50 units available worldwide.
                      Get yours before they're gone!
                    buttons:
                    - id: btn_shop_featured
                      label: Shop Now
                      type: cta_url
                      url: https://httpbin.org/anything/featured
                    mediaUrl: https://picsum.photos/id/96/600/400.jpg
                  message: Don't miss this exclusive offer!
                  phone: "5511999999999"
              videoTutorials:
                description: Tutorial series with videos
                summary: Video tutorials
                value:
                  cardType: HSCROLL_CARDS
                  cards:
                  - body: |-
                      Getting Started Guide

                      Learn the basics in 5 minutes
                    buttons:
                    - id: btn_tutorial_1
                      label: Watch Full Video
                      type: cta_url
                      url: https://youtube.com/watch?v=eRsGyueVLvQ
                    mediaUrl: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
                  - body: |-
                      Advanced Features

                      Unlock the full potential
                    buttons:
                    - id: btn_tutorial_2
                      label: Watch Full Video
                      type: cta_url
                      url: https://youtube.com/watch?v=YE7VzlLtp-4
                    mediaUrl: https://download.blender.org/peach/trailer/trailer_480p.mov
                  - body: |-
                      Pro Tips & Tricks

                      Boost your productivity
                    buttons:
                    - id: btn_tutorial_3
                      label: Watch Full Video
                      type: cta_url
                      url: https://youtube.com/watch?v=aqz-KE-bpKQ
                    mediaUrl: https://download.blender.org/demo/movies/ToS/ToS-4k-1920.mov
                  message: Welcome to our tutorial series! Learn everything from basics
                    to advanced techniques.
                  phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendCarouselRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                bodyTooLong:
                  summary: Body text too long
                  value:
                    error: card body cannot exceed 1024 characters
                invalidHeaderType:
                  summary: Invalid header type
                  value:
                    error: header.type must be 'image' or 'video'
                missingCards:
                  summary: Missing cards
                  value:
                    error: cards is required and must have at least 1 item
                missingHeader:
                  summary: Missing card header
                  value:
                    error: each card must have a header with type and url
                tooManyButtons:
                  summary: Too many buttons per card
                  value:
                    error: each card can have maximum 2 buttons
                tooManyCards:
                  summary: Too many cards
                  value:
                    error: cards cannot have more than 10 items
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send carousel message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-contact:
    post:
      description: Sends a single contact card via WhatsApp.Using contactName, contactPhone,
        and optional contactBusinessDescription fields.
      operationId: sendContactMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              address:
                city: São Paulo
                country: Brasil
                region: SP
                street: Av. Paulista, 1578
                type: WORK
              contactBusinessDescription: Sales Manager at Example Corp
              contactName: John Doe
              contactPhone: "5511888888888"
              email: john.doe@example.com
              firstName: John
              groupMentioned:
              - phone: 120363000000000@g.us
                subject: Equipe Comercial
              lastName: Doe
              mentioned:
              - "5511990000000"
              phone: "5511999999999"
              privateAnswer: false
            schema:
              $ref: '#/components/schemas/SendContactRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send single contact card
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-contacts:
    post:
      description: Sends multiple contact cards via WhatsApp in a single message.
        Maximum 10 contacts per request.
      operationId: sendContactsMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              contacts:
              - address:
                  city: São Paulo
                  country: Brasil
                  region: SP
                  street: Av. Paulista, 1578
                  type: WORK
                contactBusinessDescription: Sales Manager
                contactName: John Doe
                contactPhone: "5511888888888"
                jobTitle: Sales Director
              - contactBusinessDescription: CEO
                contactName: Jane Smith
                contactPhone: "5511777777777"
                email: jane.smith@example.com
                url: https://example.com/jane
              phone: "5511999999999"
              privateAnswer: false
            schema:
              $ref: '#/components/schemas/SendContactsRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send multiple contact cards
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-document:
    post:
      description: |+
        Sends a document file via WhatsApp with optional caption and filename.

        **Features:**
        - ✅ Document URL or base64 data URI support
        - ✅ Custom filename support
        - ✅ Optional caption/description
        - ✅ Reply-to message support
        - ✅ Typing indicator and delayed sending
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)

        **Supported Formats:** PDF, DOC, DOCX, XLS, XLSX, TXT, CSV, ZIP, RAR



      operationId: sendDocumentMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              caption: Here is the monthly report
              document: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
              fileName: Monthly Report.pdf
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendDocumentRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send document message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-edit-event:
    post:
      description: |
        Sends an update to an existing event message, modifying its details.

        **Features:**
        - Update event name, description, location
        - Change start and end times
        - Cancel the event
        - Optional typing simulation before sending

        **Note:** You must have created the original event or have permission to edit it.
      operationId: sendEditEvent
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              description: Weekly sync moved to new time
              endTime: "2024-01-15T15:00:00Z"
              eventId: 3EB047ED70306656281B34
              location: Conference Room B
              name: Team Meeting - Updated
              phone: "5511999999999"
              startTime: "2024-01-15T14:00:00Z"
            schema:
              $ref: '#/components/schemas/SendEditEventRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEditEventResponse'
          description: Event updated successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Edit an event
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-event:
    post:
      description: |
        Sends a scheduled event message to a WhatsApp group.

        **Features:**
        - ✅ Event name and description
        - ✅ Date and time scheduling (ISO 8601)
        - ✅ Location support (name and coordinates)
        - ✅ Call link type (voice/video)
        - ✅ Event cancellation support
        - ✅ Custom message ID for tracking
        - ✅ FIFO queue with per-recipient ordering


        - Nested `event` object with all event details
        - `dateTime` in ISO 8601 format (e.g., "2024-04-29T09:30:53.309Z")
        - `location` object with name and optional coordinates
        - `callLinkType` can be "voice" or "video"

        **Restrictions:**
        - Events can only be sent to groups
        - Sender must be group admin for some event features
      operationId: sendEventMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              basicEvent:
                description: Simple event with name, description and date
                summary: Basic event
                value:
                  event:
                    dateTime: "2024-04-29T14:00:00.000Z"
                    description: Reuniao semanal para alinhamento de projetos
                    name: Reuniao de Equipe
                  phone: 120363356737170752@g.us
              canceledEvent:
                description: Event marked as canceled
                summary: Canceled event
                value:
                  event:
                    canceled: true
                    dateTime: "2024-04-30T09:00:00.000Z"
                    description: Este evento foi cancelado
                    name: Evento Cancelado
                  phone: 120363356737170752@g.us
              completeEventExample:
                description: Event with all available options configured
                summary: Complete event with all fields
                value:
                  delayMessage: 5
                  delayTyping: 3
                  event:
                    callLinkType: video
                    dateTime: "2024-07-01T16:00:00.000Z"
                    description: Evento de exemplo com todas as opcoes
                    location:
                      degreesLatitude: -23.5489
                      degreesLongitude: -46.6388
                      name: Centro de Convencoes - Rua Principal, 500
                    name: Evento Completo
                  messageId: 3EB047ED70306656281B34
                  phone: 120363356737170752@g.us
              eventReply:
                description: Event sent as reply to another message
                summary: Event as reply
                value:
                  event:
                    dateTime: "2024-06-05T14:00:00.000Z"
                    description: Conforme solicitado, agendamos o evento
                    name: Agenda Confirmada
                  messageId: 3EB047ED70306656281B34
                  phone: 120363356737170752@g.us
              eventWithDelay:
                description: Event sent with delay for typing simulation
                summary: Event with delay
                value:
                  delayMessage: 3
                  delayTyping: 2
                  event:
                    dateTime: "2024-06-01T10:00:00.000Z"
                    description: Discussao sobre novos projetos
                    name: Reuniao Importante
                  phone: 120363356737170752@g.us
              eventWithLocationCoordinates:
                description: Event with physical location and GPS coordinates
                summary: Event with location and coordinates
                value:
                  event:
                    dateTime: "2024-05-15T18:30:00.000Z"
                    description: Confraternizacao mensal
                    location:
                      degreesLatitude: -23.5505
                      degreesLongitude: -46.6333
                      name: Bar do Ze - Rua das Flores, 123
                    name: Happy Hour da Empresa
                  phone: 120363356737170752@g.us
              eventWithLocationName:
                description: Event with location name but no coordinates
                summary: Event with location name only
                value:
                  event:
                    dateTime: "2024-05-10T09:00:00.000Z"
                    description: Encontro do grupo no escritorio
                    location:
                      name: Escritorio Central - Av. Paulista, 1000, Sao Paulo
                    name: Encontro Presencial
                  phone: 120363356737170752@g.us
              eventWithVideoCall:
                description: Online event with video call link
                summary: Event with video call
                value:
                  event:
                    callLinkType: video
                    dateTime: "2024-05-20T10:00:00.000Z"
                    description: Treinamento online de tecnicas de vendas
                    name: Workshop de Vendas
                  phone: 120363356737170752@g.us
              eventWithVoiceCall:
                description: Online event with voice call link
                summary: Event with voice call
                value:
                  event:
                    callLinkType: voice
                    dateTime: "2024-05-22T15:00:00.000Z"
                    description: Chamada rapida para alinhar pendencias
                    name: Call de Alinhamento
                  phone: 120363356737170752@g.us
            schema:
              $ref: '#/components/schemas/SendEventRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Event message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                invalidDateTime:
                  summary: Invalid date/time format
                  value:
                    error: invalid dateTime format, expected ISO 8601
                missingDateTime:
                  summary: Missing event date/time
                  value:
                    error: event dateTime is required
                missingEvent:
                  summary: Missing event object
                  value:
                    error: event object is required
                missingName:
                  summary: Missing event name
                  value:
                    error: event name is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send event message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-event-response:
    post:
      description: |
        Sends a response to an event invitation (RSVP).

        **Response Types:**
        - `going` - Confirm attendance
        - `not_going` - Decline invitation
        - `maybe` - Tentative response

        **Features:**
        - Specify additional guests count
        - Optional typing simulation before sending

        **Note:** Event responses are encrypted and require the original event's message secret.
        This endpoint sends an encrypted response referencing the original event.
      operationId: sendEventResponse
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              eventId: 3EB047ED70306656281B34
              extraGuestCount: 2
              phone: "5511999999999"
              response: going
            schema:
              $ref: '#/components/schemas/SendEventResponseRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEventResponseResponse'
          description: Event response sent successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Respond to an event invitation
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-gif:
    post:
      description: |
        Sends a GIF message via WhatsApp with optional caption.

        **Features:**
        - ✅ GIF URL or base64 data URI support
        - ✅ Animated GIFs
        - ✅ Optional caption/text
        - ✅ View once support (disappears after viewing)
        - ✅ Reply-to message support
        - ✅ Typing indicator and delayed sending
        - ✅ Ephemeral/disappearing messages support
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)
        - ✅ Private reply in groups (privateAnswer)
        - ✅ FIFO queue with per-recipient ordering
        - ✅ Non-blocking (returns immediately with zaapId)

        **GIF Format:**
        - GIF format (animated or static)
        - Any aspect ratio (auto-adjusted by WhatsApp)
        - Max 16MB recommended
        - Supports caption with @mentions

        **Supported Formats:**
        - URL: `https://media.giphy.com/media/3o7abKhOpu0NwenH3O/giphy.gif`
        - Base64: `data:image/gif;base64,R0lGODlhAQABAIAAAP...`
      operationId: sendGifMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              caption: "Check this out! \U0001F389"
              delayMessage: 3
              delayTyping: 2
              gif: https://media.giphy.com/media/3o7abKhOpu0NwenH3O/giphy.gif
              phone: "5511999999999"
              viewOnce: false
            schema:
              $ref: '#/components/schemas/SendGifRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                id: 39BB1684570F00E91090F6BBC7EE7646
                messageId: 39BB1684570F00E91090F6BBC7EE7646
                status: queued
                zaapId: 39BB1684570F00E91090F6BBC7EE7646
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              example:
                error: gif must be a valid URL or base64 data URI
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing phone or gif, invalid format)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send GIF message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-image:
    post:
      description: |+
        Sends an image message via WhatsApp with optional caption.

        **Features:**
        - ✅ Image URL or base64 data URI support
        - ✅ Optional caption/title
        - ✅ View once support (disappears after viewing)
        - ✅ Reply-to message support
        - ✅ Typing indicator and delayed sending
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)
        - ✅ FIFO queue with per-recipient ordering

        **Supported Formats:**
        - Image URL: `https://picsum.photos/600/400.jpg`
        - Base64: `data:image/png;base64,iVBORw0KG...`



      operationId: sendImageMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              caption: Check out this image!
              image: https://picsum.photos/600/400.jpg
              phone: "5511999999999"
              viewOnce: false
            schema:
              $ref: '#/components/schemas/SendImageRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send image message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-image-status:
    post:
      description: |
        Sends an image to WhatsApp Status/Stories with optional caption.

        **Status Broadcasting**: The image is automatically broadcast to all contacts
        who can view your status based on your privacy settings. No phone number
        is required - the message is sent to `status@broadcast`.

        **Key Features**:
        - Image URL or base64 data URI support
        - Optional caption/text overlay
        - Automatic thumbnail generation
        - FIFO queue with non-blocking response
        - Optional custom message ID for tracking

        **Supported Formats**: JPEG, PNG, WebP, GIF (static)

        **Recommended Dimensions**: 1080x1920 pixels (9:16 aspect ratio for Stories)

        **Working Image URLs for Testing**:
        | Source | URL | Description |
        |--------|-----|-------------|
        | Picsum | https://picsum.photos/1080/1920 | Random HD image |
        | Unsplash | https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=1080 | Mountain landscape |
        | Placeholder | https://placehold.co/1080x1920/3498DB/FFFFFF/png?text=Status | Custom placeholder |
        | Lorem Flickr | https://loremflickr.com/1080/1920/nature | Random nature image |
      operationId: sendImageStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              city_skyline:
                description: Urban photography from Unsplash
                summary: City skyline
                value:
                  caption: City lights
                  image: https://images.unsplash.com/photo-1477959858617-67f85cf4f1df?w=1080&q=80
                  messageId: city-status-001
              food_photo:
                description: Delicious food image
                summary: Food photography
                value:
                  caption: Bon appetit!
                  image: https://images.unsplash.com/photo-1546069901-ba9599a7e63c?w=1080&q=80
              landscape_photo:
                description: High-quality mountain landscape from Unsplash
                summary: Unsplash landscape photo
                value:
                  caption: Nature at its finest
                  image: https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=1080&q=80
              nature_image:
                description: Random nature photography from Lorem Flickr
                summary: Random nature image
                value:
                  caption: Exploring the world
                  image: https://loremflickr.com/1080/1920/nature,landscape
              no_caption:
                description: Simple image status without text overlay
                summary: Image without caption
                value:
                  image: https://picsum.photos/seed/status/1080/1920
              placeholder_branded:
                description: Custom branded placeholder for testing
                summary: Branded placeholder image
                value:
                  image: https://placehold.co/1080x1920/3498DB/FFFFFF/png?text=My+Status
              random_image:
                description: Uses Picsum Photos service for random high-quality images
                summary: Random HD image from Picsum
                value:
                  caption: Beautiful moment captured!
                  image: https://picsum.photos/1080/1920
              sunset_photo:
                description: Beautiful sunset photography
                summary: Sunset photo from Unsplash
                value:
                  caption: Golden hour vibes
                  delayMessage: 3
                  image: https://images.unsplash.com/photo-1495616811223-4d98c6e9c869?w=1080&q=80
            schema:
              $ref: '#/components/schemas/SendImageStatusRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    id: b2c3d4e5-f6a7-8901-bcde-f23456789012
                    messageId: 3EB0F4326B5A8C92D4E3
                    status: QUEUED
                    zaapId: BAE5F4326B5A8C92
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Status message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                invalid_url:
                  summary: Invalid image URL
                  value:
                    code: VALIDATION_ERROR
                    error: invalid image URL or base64 data
                missing_image:
                  summary: Missing image field
                  value:
                    code: VALIDATION_ERROR
                    error: image is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing image or invalid URL)
        "401":
          content:
            application/json:
              example:
                code: UNAUTHORIZED
                error: invalid client token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized - Invalid or missing Client-Token
        "404":
          content:
            application/json:
              example:
                code: NOT_FOUND
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                code: SERVICE_UNAVAILABLE
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send image to WhatsApp Status
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-link:
    post:
      description: |
        Sends a text message with a customized link preview.

        **Features:**
        - ✅ Custom link preview title
        - ✅ Custom link preview description
        - ✅ Custom preview image
        - ✅ Message text before the link
        - ✅ Automatic URL validation
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering


        - `linkUrl` is the URL to preview (required)
        - `title` overrides the default link title
        - `linkDescription` overrides the default description
        - `image` provides a custom preview thumbnail
        - `message` adds text before the link preview

        **Preview Image:**
        - Must be a valid image URL (JPEG, PNG, WebP)
        - Will be downloaded and used as thumbnail
        - Falls back to default Open Graph image if download fails
      operationId: sendLinkMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              basicLink:
                description: Link with custom title and description
                summary: Basic link with custom preview
                value:
                  linkDescription: O melhor produto do mercado com desconto especial
                  linkUrl: https://www.example.com/produto
                  message: Confira nosso novo produto!
                  phone: "5511999999999"
                  title: Produto Incrivel
              completeLinkExample:
                description: Link with all available options configured
                summary: Complete link with all fields
                value:
                  delayMessage: 5
                  delayTyping: 3
                  image: https://picsum.photos/600/400.jpg
                  linkDescription: Acesse agora e aproveite esta oportunidade unica
                  linkUrl: https://www.example.com/conteudo-especial
                  message: Confira este conteudo incrivel que separei para voce!
                  messageId: 3EB047ED70306656281B34
                  phone: "5511999999999"
                  title: Conteudo Especial
              linkAsReply:
                description: Send link as reply to another message
                summary: Link as reply
                value:
                  image: https://picsum.photos/600/400.jpg
                  linkDescription: Trailer do filme Sintel em 480p
                  linkUrl: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
                  message: Aqui esta o video que voce pediu
                  messageId: 3EB047ED70306656281B34
                  phone: "5511999999999"
                  title: Sintel Trailer
              linkToGroup:
                description: Send link with preview to a WhatsApp group
                summary: Link to group
                value:
                  image: https://picsum.photos/600/400.jpg
                  linkDescription: Baixe o documento em PDF para o proximo encontro
                  linkUrl: https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf
                  message: Material para estudo do grupo
                  phone: 120363356737170752@g.us
                  title: Documento PDF
              linkWithDelay:
                description: Link with delay message and typing indicator
                summary: Link with delay
                value:
                  delayMessage: 3
                  delayTyping: 2
                  linkDescription: Visite-nos e conheca nossos servicos
                  linkUrl: https://www.example.com
                  message: Acesse nosso site
                  phone: "5511999999999"
                  title: Nosso Site Oficial
              linkWithImage:
                description: Link with custom preview image using real image URL
                summary: Link with custom image
                value:
                  image: https://picsum.photos/600/400.jpg
                  linkDescription: 50% de desconto em todos os produtos
                  linkUrl: https://www.example.com/oferta
                  message: Veja esta oferta especial
                  phone: "5511999999999"
                  title: Super Oferta
              minimalLink:
                description: Just the URL with auto-fetched metadata
                summary: Minimal link
                value:
                  linkUrl: https://github.com
                  phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendLinkRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Link message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                invalidUrl:
                  summary: Invalid URL format
                  value:
                    error: linkUrl must be a valid URL
                missingUrl:
                  summary: Missing link URL
                  value:
                    error: linkUrl is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send link with preview
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-location:
    post:
      description: Sends a location pin via WhatsApp with GPS coordinates, optional
        name/address, replies, mentions, and ephemeral support..
      operationId: sendLocationMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              address: Av. Paulista, 1578 - São Paulo, SP
              latitude: -23.55052
              longitude: -46.633308
              name: Paulista Avenue
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendLocationRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send location message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-newsletter-admin-invite:
    post:
      description: Sends an invitation to a participant to become channel administrator
        via direct message.
      operationId: sendNewsletterAdminInvite
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 123456789@newsletter
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendNewsletterAdminInviteRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Admin invitation sent successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send channel admin invitation
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/send-option-list:
    post:
      description: |
        Sends an interactive message with a simple list of options.
        Similar to button list but without sections (flat list).

        **Features:**
        - ✅ Simple flat list of options
        - ✅ Up to 10 options
        - ✅ Title and description for each option
        - ✅ Button to open options
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering

        **Limits:**
        - Max 10 options
        - Title: max 60 characters
        - Option title: max 24 characters
        - Option description: max 72 characters
        - Button text: max 20 characters

        **Use Cases:**
        - Simple surveys
        - Quick polls
        - Rating selection
        - Single-level menus
      operationId: sendOptionListMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              appointmentSlots:
                description: Select available appointment time
                summary: Appointment time slots
                value:
                  buttonLabel: Select Time
                  footer: All times in local timezone
                  message: Select your preferred time slot
                  messageId: appointment-booking-12345
                  phone: "5511999999999"
                  sections:
                  - rows:
                    - description: Early morning
                      id: slot_9am
                      title: 9:00 AM
                    - description: Late morning
                      id: slot_11am
                      title: 11:00 AM
                    title: Morning
                  - rows:
                    - description: Early afternoon
                      id: slot_2pm
                      title: 2:00 PM
                    - description: Late afternoon
                      id: slot_4pm
                      title: 4:00 PM
                    title: Afternoon
                  title: Available Appointments
              customerSupport:
                description: Service selection with sections
                summary: Customer support options
                value:
                  buttonLabel: Select Option
                  message: How can we help you today?
                  phone: "5511999999999"
                  sections:
                  - rows:
                    - description: Get help with installation
                      id: tech_install
                      title: Installation Help
                    - description: Report technical issues
                      id: tech_bug
                      title: Report a Bug
                    title: Technical Support
                  - rows:
                    - description: Questions about your bill
                      id: bill_invoice
                      title: Invoice Questions
                    - description: Update payment info
                      id: bill_payment
                      title: Payment Methods
                    title: Billing
                  title: Customer Support
              restaurantMenu:
                description: Menu organized by food categories
                summary: Restaurant menu with sections
                value:
                  buttonLabel: View Menu
                  footer: Tap to view options
                  message: Choose your meal from our delicious options
                  phone: "5511999999999"
                  sections:
                  - rows:
                    - description: Classic cheese pizza with basil
                      id: dish_pizza
                      title: Pizza Margherita
                    - description: Beef burger with cheese
                      id: dish_burger
                      title: Classic Burger
                    - description: Creamy pasta with bacon
                      id: dish_pasta
                      title: Spaghetti Carbonara
                    title: Main Dishes
                  - rows:
                    - description: Coca-Cola, Sprite, Fanta
                      id: drink_soda
                      title: Soda
                    - description: Orange, Apple, Mango
                      id: drink_juice
                      title: Fresh Juice
                    title: Drinks
                  title: Our Menu
              withDelay:
                description: Option list with typing delay
                summary: With message delay
                value:
                  buttonLabel: Rate Us
                  delayMessage: 5
                  delayTyping: 3
                  message: Please share your feedback
                  phone: "5511999999999"
                  sections:
                  - rows:
                    - description: Very satisfied
                      id: rate_good
                      title: Excellent
                    - description: Satisfied
                      id: rate_ok
                      title: Good
                    - description: Not satisfied
                      id: rate_bad
                      title: Poor
                    title: Rating
                  title: Quick Survey
            schema:
              $ref: '#/components/schemas/SendOptionListRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                missingButtonLabel:
                  summary: Missing button label
                  value:
                    error: buttonLabel is required
                missingSections:
                  summary: Missing sections
                  value:
                    error: At least one section is required
                tooManySections:
                  summary: Too many sections
                  value:
                    error: sections cannot have more than 10 items
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send simple option list message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-poll:
    post:
      description: |
        Sends a poll (voting/survey) message to a WhatsApp user or group.

        **Features:**
        - ✅ 2-12 poll options
        - ✅ Single or multiple choice voting
        - ✅ Custom message ID for tracking
        - ✅ Delay message support
        - ✅ FIFO queue with per-recipient ordering


        - `message` field contains the poll question
        - `poll` array contains options with `name` field
        - `pollMaxOptions` controls voting: 0 or 1 = single choice, >1 = multiple choice

        **Limits:**
        - Min 2 options, max 12 options
        - Option text: max 100 characters each
        - Question text: max 256 characters
      operationId: sendPollMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              completeExample:
                description: Poll with all available options configured
                summary: Complete poll with all fields
                value:
                  delayMessage: 3
                  delayTyping: 2
                  message: Como voce avalia nosso atendimento?
                  messageId: 3EB047ED70306656281B34
                  phone: "5511999999999"
                  poll:
                  - name: Excelente
                  - name: Bom
                  - name: Regular
                  - name: Ruim
                  pollMaxOptions: 1
              groupPoll:
                description: Send poll to a WhatsApp group
                summary: Poll to group
                value:
                  message: Qual dia fica melhor para a reuniao?
                  phone: 120363356737170752@g.us
                  poll:
                  - name: Segunda-feira
                  - name: Terca-feira
                  - name: Quarta-feira
                  - name: Quinta-feira
                  - name: Sexta-feira
                  pollMaxOptions: 1
              multipleChoice:
                description: Poll where user can select multiple options
                summary: Multiple choice poll
                value:
                  message: Quais redes sociais voce usa?
                  phone: "5511999999999"
                  poll:
                  - name: WhatsApp
                  - name: Instagram
                  - name: Twitter
                  - name: TikTok
                  - name: Facebook
                  pollMaxOptions: 3
              replyPoll:
                description: Poll sent as reply to another message
                summary: Poll as reply
                value:
                  message: Respondendo sua pergunta, qual voce prefere?
                  messageId: 3EB047ED70306656281B34
                  phone: "5511999999999"
                  poll:
                  - name: Opcao A
                  - name: Opcao B
                  - name: Opcao C
                  pollMaxOptions: 1
              singleChoice:
                description: Poll where user can select only one option
                summary: Single choice poll
                value:
                  message: Qual o melhor sabor de pizza?
                  phone: "5511999999999"
                  poll:
                  - name: Calabresa
                  - name: Marguerita
                  - name: Portuguesa
                  - name: Frango
                  pollMaxOptions: 1
            schema:
              $ref: '#/components/schemas/SendPollRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                data:
                  messageId: 39BB1684570F00E91090F6BBC7EE7646
                  status: queued
                  zaapId: 39BB1684570F00E91090F6BBC7EE7646
                message: Message queued successfully
                success: true
              schema:
                $ref: '#/components/schemas/MessageQueuedResponse'
          description: Poll message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                missingOptions:
                  summary: Missing poll options
                  value:
                    error: poll options are required
                missingQuestion:
                  summary: Missing poll question
                  value:
                    error: message (poll question) is required
                tooFewOptions:
                  summary: Too few options
                  value:
                    error: poll must have at least 2 options
                tooManyOptions:
                  summary: Too many options
                  value:
                    error: poll cannot have more than 12 options
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (validation error)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send poll message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-poll-vote:
    post:
      description: |
        Submits a vote on an existing poll message.

        **Features:**
        - Vote for one or multiple options (depending on poll settings)
        - Options are specified by name (exact match)
        - FIFO queue with per-recipient ordering
      operationId: sendPollVote
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              options:
              - Option A
              - Option B
              phone: "5511999999999"
              pollId: 3EB047ED70306656281B34
            schema:
              $ref: '#/components/schemas/SendPollVoteRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Poll vote sent successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Vote on a poll
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-ptv:
    post:
      description: |
        Sends a PTV (Push-To-Talk Video) message via WhatsApp with format.

        **What is PTV?**
        PTV messages are circular video notes, displayed similarly to voice notes but with video content.
        They appear as circular thumbnails in the chat and play inline when tapped.

        **Features:**
        - ✅ Circular video notes (like voice notes with video)
        - ✅ Video URL or base64 data URI support
        - ✅ Optional caption/text
        - ✅ Reply-to message support
        - ✅ Typing indicator and delayed sending
        - ✅ Ephemeral/disappearing messages support
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)
        - ✅ Private reply in groups (privateAnswer)
        - ✅ FIFO queue with per-recipient ordering
        - ✅ Non-blocking (returns immediately with zaapId)

        **Video Format:**
        - MP4, 3GP, MOV (auto-converted if needed)
        - Max duration: 60 seconds recommended
        - Displayed as circular video in WhatsApp

        **Supported Formats:**
        - URL: `https://example.com/video.mp4`
        - Base64: `data:video/mp4;base64,AAAAIGZ0eXBpc29t...`
      operationId: sendPTVMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              base64:
                summary: Base64 encoded PTV
                value:
                  caption: Video note from base64
                  phone: "5511999999999"
                  video: data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc28yYXZjMW1wNDEAAAAIZnJlZQ...
              basic:
                summary: Basic PTV message
                value:
                  phone: "5511999999999"
                  video: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
              replyTo:
                summary: PTV as reply
                value:
                  caption: Here's my response
                  messageId: 3EB0796DC1B61E519
                  phone: "5511999999999"
                  video: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
              withCaption:
                summary: PTV with caption
                value:
                  caption: Check out this video note!
                  delayMessage: 3
                  delayTyping: 2
                  phone: "5511999999999"
                  video: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
            schema:
              $ref: '#/components/schemas/SendPTVRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                id: 39BB1684570F00E91090F6BBC7EE7646
                messageId: 39BB1684570F00E91090F6BBC7EE7646
                status: queued
                zaapId: 39BB1684570F00E91090F6BBC7EE7646
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              example:
                error: video must be a valid URL or base64 data URI
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing phone or video, invalid format)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send PTV (circular video) message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-reaction:
    post:
      description: |
        Sends an emoji reaction to a specific message.

        **Features:**
        - React with any emoji
        - Works on individual and group messages
        - FIFO queue with per-recipient ordering
      operationId: sendReaction
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              messageId: 3EB047ED70306656281B34
              phone: "5511999999999"
              reaction: "\U0001F44D"
            schema:
              $ref: '#/components/schemas/SendReactionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Reaction sent successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send reaction to message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-remove-reaction:
    post:
      description: |
        Removes a previously sent reaction from a message.

        **Features:**
        - Remove your reaction from any message
        - Works on individual and group messages
      operationId: sendRemoveReaction
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              messageId: 3EB047ED70306656281B34
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendRemoveReactionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Reaction removed successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Remove reaction from message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-sticker:
    post:
      description: |
        Sends a sticker message via WhatsApp with format.

        **Features:**
        - ✅ Sticker URL or base64 data URI support
        - ✅ Animated stickers (WebP format)
        - ✅ Reply-to message support
        - ✅ Typing indicator and delayed sending
        - ✅ Ephemeral/disappearing messages support
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)
        - ✅ Private reply in groups (privateAnswer)
        - ✅ FIFO queue with per-recipient ordering
        - ✅ Non-blocking (returns immediately with zaapId)

        **Sticker Format:**
        - WebP format (animated or static)
        - 512x512 pixels recommended
        - Max 100KB for animated, 500KB for static
        - No caption support (stickers don't have text)

        **Supported Formats:**
        - URL: `https://www.gstatic.com/webp/gallery/1.webp`
        - Base64: `data:image/webp;base64,UklGRiQAAABXRUJQ...`
      operationId: sendStickerMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              delayMessage: 3
              delayTyping: 2
              phone: "5511999999999"
              sticker: https://www.gstatic.com/webp/gallery/1.webp
            schema:
              $ref: '#/components/schemas/SendStickerRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                id: 39BB1684570F00E91090F6BBC7EE7646
                messageId: 39BB1684570F00E91090F6BBC7EE7646
                status: queued
                zaapId: 39BB1684570F00E91090F6BBC7EE7646
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              example:
                error: sticker must be a valid URL or base64 data URI
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing phone or sticker, invalid format)
        "401":
          content:
            application/json:
              example:
                error: unauthorized
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized (invalid Client-Token or instance token)
        "404":
          content:
            application/json:
              example:
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send sticker message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-text:
    post:
      description: |+
        Sends a text message via WhatsApp with format.

        **Features:**
        - ✅ Text message with optional reply-to
        - ✅ Typing indicator simulation (delayTyping)
        - ✅ Delayed sending (delayMessage)
        - ✅ Ephemeral/disappearing messages support
        - ✅ Private reply in groups (privateAnswer)
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)
        - ✅ FIFO queue with per-recipient ordering
        - ✅ Non-blocking (returns immediately with zaapId)



      operationId: sendTextMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              delayMessage: 5
              delayTyping: 3
              message: Hello from Zé da API!
              phone: "5511999999999"
            schema:
              $ref: '#/components/schemas/SendTextRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                id: 39BB1684570F00E91090F6BBC7EE7646
                messageId: 39BB1684570F00E91090F6BBC7EE7646
                zaapId: 39BB1684570F00E91090F6BBC7EE7646
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing phone or message)
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send text message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-text-status:
    post:
      description: |
        Sends a text message to WhatsApp Status/Stories.

        **Status Broadcasting**: The text is automatically broadcast to all contacts
        who can view your status based on your privacy settings. No phone number
        is required - the message is sent to `status@broadcast`.

        **Key Features**:
        - Custom background color (hex #RRGGBB or ARGB 0xAARRGGBB)
        - Multiple font styles (0-5)
        - FIFO queue with non-blocking response
        - Optional custom message ID for tracking
        - Delayed sending and scheduled delivery support (delayMessage or scheduledFor)

        **Font Styles**:
        | Value | Font Name | Description |
        |-------|-----------|-------------|
        | 0 | Sans-serif | Default clean font |
        | 1 | Serif | Classic serif font |
        | 2 | Norican Script | Elegant cursive script |
        | 3 | Bryndan Write | Handwritten style |
        | 4 | Bebasneue Regular | Bold condensed |
        | 5 | Oswald Heavy | Strong impact font |

        **Background Color Examples**:
        | Color | Hex Code | Description |
        |-------|----------|-------------|
        | Red | #FF5733 | Vibrant red-orange |
        | Blue | #3498DB | Sky blue |
        | Green | #2ECC71 | Emerald green |
        | Purple | #9B59B6 | Amethyst purple |
        | Orange | #F39C12 | Warm orange |
        | Pink | #E91E63 | Hot pink |
        | Teal | #1ABC9C | Turquoise |
        | Dark | #2C3E50 | Dark blue-gray |
      operationId: sendTextStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              bold_announcement:
                description: Using Oswald Heavy font for impact
                summary: Bold announcement style
                value:
                  backgroundColor: '#F39C12'
                  font: 5
                  text: SALE STARTS NOW - 50% OFF!
              colored_background:
                description: Text status with custom red-orange background
                summary: Text with colored background
                value:
                  backgroundColor: '#FF5733'
                  text: Big announcement coming soon!
              custom_font:
                description: Text status using Norican Script cursive font
                summary: Text with custom font
                value:
                  backgroundColor: '#E91E63'
                  font: 2
                  text: Love and peace to all
              elegant_quote:
                description: Using serif font for quotes
                summary: Elegant quote style
                value:
                  backgroundColor: '#2C3E50'
                  font: 1
                  text: The only way to do great work is to love what you do. - Steve
                    Jobs
              full_options:
                description: Text status with all options configured
                summary: Full options example
                value:
                  backgroundColor: '#3498DB'
                  delayMessage: 5
                  font: 4
                  messageId: custom-promo-status-001
                  text: Check out our new product launch!
              simple_text:
                description: Basic text status with default styling
                summary: Simple text status
                value:
                  text: Hello everyone! Having a great day!
            schema:
              $ref: '#/components/schemas/SendTextStatusRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    messageId: 3EB0F4326B5A8C91D4E2
                    status: QUEUED
                    zaapId: BAE5F4326B5A8C91
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Status message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                invalid_font:
                  summary: Invalid font value
                  value:
                    code: VALIDATION_ERROR
                    error: font must be between 0 and 5
                missing_text:
                  summary: Missing text field
                  value:
                    code: VALIDATION_ERROR
                    error: text is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing text or invalid parameters)
        "401":
          content:
            application/json:
              example:
                code: UNAUTHORIZED
                error: invalid client token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized - Invalid or missing Client-Token
        "404":
          content:
            application/json:
              example:
                code: NOT_FOUND
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                code: SERVICE_UNAVAILABLE
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send text to WhatsApp Status
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-video:
    post:
      description: |+
        Sends a video message via WhatsApp with optional caption.

        **Features:**
        - ✅ Video URL or base64 data URI support
        - ✅ Optional caption/title
        - ✅ View once support
        - ✅ Reply-to message support
        - ✅ Typing indicator and delayed sending
        - ✅ Mentions support (mentioned, groupMentioned, mentionedAll)

        **Supported Formats:** MP4, 3GP, AVI, MOV



      operationId: sendVideoMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              caption: Check out this video!
              phone: "5511999999999"
              video: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
            schema:
              $ref: '#/components/schemas/SendVideoRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Message enqueued successfully
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Send video message
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/send-video-status:
    post:
      description: |
        Sends a video to WhatsApp Status/Stories with optional caption.

        **Status Broadcasting**: The video is automatically broadcast to all contacts
        who can view your status based on your privacy settings. No phone number
        is required - the message is sent to `status@broadcast`.

        **Key Features**:
        - Video URL or base64 data URI support
        - Optional caption/text overlay
        - Automatic thumbnail generation
        - FIFO queue with non-blocking response
        - Optional custom message ID for tracking

        **Supported Formats**: MP4, 3GP, MOV, AVI, WebM
        **Duration Limit**: WhatsApp status videos are limited to 30 seconds
        **Recommended Resolution**: 720p or 1080p vertical (9:16 aspect ratio)

        **Working Video URLs for Testing**:
        | Source | URL | Description |
        |--------|-----|-------------|
        | Blender | https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4 | Big Buck Bunny (small) |
        | Sample Videos | https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4 | 720p 1MB sample |
        | File Samples | https://filesamples.com/samples/video/mp4/sample_640x360.mp4 | 640x360 sample |
        | Test Videos | https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4 | 10s test video |

        **Video Processing Pipeline**:
        1. Download video from URL or decode base64
        2. Validate format and duration (max 30s for status)
        3. Generate thumbnail frame
        4. Upload to WhatsApp servers
        5. Send to status@broadcast
      operationId: sendVideoStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              big_buck_bunny_small:
                description: Classic open-source animated short, small file size
                summary: Big Buck Bunny (small file)
                value:
                  caption: Check out this animation!
                  video: https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4
              delayed_video:
                description: Video with 5-second delay before sending
                summary: Delayed video send
                value:
                  caption: Coming soon...
                  delayMessage: 5
                  video: https://sample-videos.com/video321/mp4/360/big_buck_bunny_360p_1mb.mp4
              file_sample:
                description: Standard file samples MP4
                summary: Standard MP4 sample
                value:
                  video: https://filesamples.com/samples/video/mp4/sample_640x360.mp4
              no_caption:
                description: Simple video status without text
                summary: Video without caption
                value:
                  video: https://sample-videos.com/video321/mp4/480/big_buck_bunny_480p_1mb.mp4
              sample_720p:
                description: Quick loading 720p sample video
                summary: 720p sample video (1MB)
                value:
                  caption: HD quality status
                  video: https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4
              sintel_trailer:
                description: Blender's Sintel animated short trailer
                summary: Sintel trailer (larger file)
                value:
                  caption: Epic adventure
                  video: https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4
              test_10_seconds:
                description: Short 10-second video perfect for status
                summary: 10-second test video
                value:
                  caption: Quick clip!
                  video: https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4
              with_tracking:
                description: Video status with custom message ID for tracking
                summary: Video with custom tracking ID
                value:
                  caption: Promo video
                  messageId: video-promo-campaign-001
                  video: https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/720/Big_Buck_Bunny_720_10s_1MB.mp4
            schema:
              $ref: '#/components/schemas/SendVideoStatusRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    id: d4e5f6a7-b8c9-0123-def0-456789012345
                    messageId: 3EB0F4326B5A8C94D4E5
                    status: QUEUED
                    zaapId: BAE5F4326B5A8C94
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
          description: Status message enqueued successfully
        "400":
          content:
            application/json:
              examples:
                download_failed:
                  summary: Failed to download video
                  value:
                    code: DOWNLOAD_ERROR
                    error: failed to download video from URL
                duration_exceeded:
                  summary: Video too long for status
                  value:
                    code: VALIDATION_ERROR
                    error: video duration exceeds 30 seconds limit for status
                invalid_format:
                  summary: Unsupported video format
                  value:
                    code: VALIDATION_ERROR
                    error: unsupported video format
                missing_video:
                  summary: Missing video field
                  value:
                    code: VALIDATION_ERROR
                    error: video is required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request (missing video, invalid format, or duration
            exceeded)
        "401":
          content:
            application/json:
              example:
                code: UNAUTHORIZED
                error: invalid client token
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized - Invalid or missing Client-Token
        "404":
          content:
            application/json:
              example:
                code: NOT_FOUND
                error: instance not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              example:
                code: SERVICE_UNAVAILABLE
                error: instance not connected
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected to WhatsApp
      security:
      - ClientTokenAuth: []
      summary: Send video to WhatsApp Status
      tags:
      - Messages
  /instances/{instanceId}/token/{instanceToken}/status:
    get:
      description: Mirrors Zé da API `/status`, returning live connectivity information
        for a provisioned instance.
      operationId: getInstanceStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceStatusResponse'
          description: Instance status snapshot
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Retrieve instance status
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/tags:
    get:
      description: Returns all label tags configured for this instance.
      operationId: listTags
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      responses:
        "200":
          content:
            application/json:
              schema:
                items:
                  properties:
                    color:
                      type: integer
                    id:
                      type: string
                    name:
                      type: string
                  type: object
                type: array
          description: Array of tags
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: List all tags
      tags:
      - Business
  /instances/{instanceId}/token/{instanceToken}/unfollow-newsletter:
    put:
      description: Stops following a channel.
      operationId: unfollowNewsletter
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
            schema:
              $ref: '#/components/schemas/NewsletterIdRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel unfollowed successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Unfollow channel
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/unmute-newsletter:
    put:
      description: Unmutes notifications for a channel.
      operationId: unmuteNewsletter
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
            schema:
              $ref: '#/components/schemas/NewsletterIdRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel unmuted successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Unmute channel
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/update-auto-read-message:
    put:
      description: Mirrors Zé da API `/update-auto-read-message`, enabling or disabling
        automatic marking of messages as read.
      operationId: updateAutoReadMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoolValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueResponse'
          description: Setting updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Toggle automatic message reading
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-call-reject-auto:
    put:
      description: Mirrors Zé da API `/update-call-reject-auto`, enabling or disabling
        automatic rejection of incoming calls.
      operationId: updateCallRejectAuto
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoolValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueResponse'
          description: Setting updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Toggle automatic call rejection
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-call-reject-message:
    put:
      description: Mirrors Zé da API `/update-call-reject-message`, setting the message
        sent when rejecting calls.
      operationId: updateCallRejectMessage
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StringValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueResponse'
          description: Setting updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Update call rejection message
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-community-description:
    post:
      description: Updates the textual description of a community.
      operationId: updateCommunityDescription
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              communityDescription: descrição da comunidade
              communityId: "120363565656565656"
            schema:
              $ref: '#/components/schemas/CommunityDescriptionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Description updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or community not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update community description
      tags:
      - Communities
  /instances/{instanceId}/token/{instanceToken}/update-every-webhooks:
    put:
      description: Mirrors Zé da API `/update-every-webhooks`, applying the same HTTPS
        endpoint to every webhook type.
      operationId: updateEveryWebhooks
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEveryRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhooks updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update all webhooks at once
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-group-description:
    post:
      description: Updates the description text of a group.
      operationId: updateGroupDescription
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              groupDescription: Descrição do grupo
              groupId: 120363019502650977-group
            schema:
              $ref: '#/components/schemas/GroupDescriptionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Group description updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update group description
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/update-group-name:
    post:
      description: Updates the subject (name) of an existing group.
      operationId: updateGroupName
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              groupId: 120363019502650977-group
              groupName: Mudou o nome do meu grupo
            schema:
              $ref: '#/components/schemas/GroupUpdateNameRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Group name updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update group name
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/update-group-photo:
    post:
      description: Updates the profile picture of an existing group.
      operationId: updateGroupPhoto
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              groupId: 120363019502650977-group
              groupPhoto: https://api.whatsgo.wa-api.io/wp-content/themes/funnelchat/dist/images/logo.svg
            schema:
              $ref: '#/components/schemas/GroupUpdatePhotoRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Group photo updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update group photo
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/update-group-settings:
    post:
      description: Updates group preferences such as admin-only messaging and approvals.
      operationId: updateGroupSettings
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              adminOnlyAddMember: true
              adminOnlyMessage: true
              adminOnlySettings: true
              phone: 120363019502650977-group
              requireAdminApproval: false
            schema:
              $ref: '#/components/schemas/GroupSettingsRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Group settings updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or group not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update group settings
      tags:
      - Groups
  /instances/{instanceId}/token/{instanceToken}/update-newsletter-description:
    post:
      description: Updates the description of a channel.
      operationId: updateNewsletterDescription
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              description: Nova descrição do canal
              id: 120363336258908380@newsletter
            schema:
              $ref: '#/components/schemas/NewsletterUpdateDescriptionRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel description updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update channel description
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/update-newsletter-name:
    post:
      description: Updates the display name of a channel.
      operationId: updateNewsletterName
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
              name: Novo nome do canal
            schema:
              $ref: '#/components/schemas/NewsletterUpdateNameRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel name updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update channel name
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/update-newsletter-picture:
    post:
      description: Updates the profile picture of an existing channel.
      operationId: updateNewsletterPicture
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            example:
              id: 120363336258908380@newsletter
              pictureUrl: https://api.whatsgo.wa-api.io/wp-content/themes/funnelchat/dist/images/logo.svg
            schema:
              $ref: '#/components/schemas/NewsletterUpdatePictureRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanStatusResponse'
          description: Channel picture updated successfully.
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance or channel not found
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not connected
      security:
      - ClientTokenAuth: []
      summary: Update channel picture
      tags:
      - Channels
  /instances/{instanceId}/token/{instanceToken}/update-notify-sent-by-me:
    put:
      description: Mirrors Zé da API `/update-notify-sent-by-me`, enabling or disabling
        callbacks for messages sent by the instance.
      operationId: updateNotifySentByMe
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifySentByMeRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Setting updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Toggle notify-sent-by-me
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-proxy:
    put:
      description: |
        Configures a proxy for this instance's WhatsApp connection.
        Supports HTTP, HTTPS, and SOCKS5 proxies.
        The proxy is applied to the live client if connected.
      operationId: updateProxy
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            examples:
              http_proxy:
                summary: HTTP proxy
                value:
                  proxyUrl: http://proxy.example.com:8080
              media_only:
                summary: Proxy only for media, not websocket
                value:
                  noWebsocket: true
                  proxyUrl: http://media-proxy.example.com:8080
              socks5_proxy:
                summary: SOCKS5 proxy with auth
                value:
                  proxyUrl: socks5://user:pass@proxy.example.com:1080
            schema:
              $ref: '#/components/schemas/ProxyUpdateRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  proxy:
                    $ref: '#/components/schemas/ProxyConfig'
                  value:
                    type: boolean
                type: object
          description: Proxy configuration updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid proxy URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Instance not found
      security:
      - ClientTokenAuth: []
      summary: Set or update proxy configuration
      tags:
      - Proxy
  /instances/{instanceId}/token/{instanceToken}/update-webhook-chat-presence:
    put:
      description: Mirrors Zé da API `/update-webhook-chat-presence`, configuring
        the typing/presence webhook endpoint.
      operationId: updateWebhookChatPresence
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update chat presence webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-connected:
    put:
      description: Mirrors Zé da API `/update-webhook-connected`, configuring the
        connection notification endpoint.
      operationId: updateWebhookConnected
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update connected webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-delivery:
    put:
      description: Mirrors Zé da API `/update-webhook-delivery`, configuring the sent-message
        webhook endpoint.
      operationId: updateWebhookDelivery
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update delivery webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-disconnected:
    put:
      description: Mirrors Zé da API `/update-webhook-disconnected`, configuring the
        disconnect notification endpoint.
      operationId: updateWebhookDisconnected
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update disconnected webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-history-sync:
    put:
      description: Configures a dedicated webhook endpoint for WhatsApp history sync
        events. History sync events contain batches of historical messages and are
        forwarded separately from other event types.
      operationId: updateWebhookHistorySync
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update history sync webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-message-status:
    put:
      description: Mirrors Zé da API `/update-webhook-message-status`, configuring
        delivery-read status updates.
      operationId: updateWebhookMessageStatus
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update message status webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-received:
    put:
      description: Mirrors Zé da API `/update-webhook-received`, configuring the incoming
        message webhook endpoint.
      operationId: updateWebhookReceived
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update received webhook
      tags:
      - Instances
  /instances/{instanceId}/token/{instanceToken}/update-webhook-received-delivery:
    put:
      description: Mirrors Zé da API `/update-webhook-received-delivery`, configuring
        the webhook used when `notifySentByMe` is enabled.
      operationId: updateWebhookReceivedDelivery
      parameters:
      - $ref: '#/components/parameters/InstanceId'
      - $ref: '#/components/parameters/InstanceToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookValueRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookUpdateResponse'
          description: Webhook updated
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload or non-HTTPS URL
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - ClientTokenAuth: []
      summary: Update received+delivery webhook
      tags:
      - Instances
  /instances/integrator/on-demand:
    post:
      description: Mirrors Zé da API partner endpoint for provisioning instances via
        integrator credentials.
      operationId: partnerCreateInstance
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerInstanceCreateRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerInstanceCreateResponse'
          description: Instance created for partner
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid payload
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
      security:
      - PartnerBearer: []
      summary: Partner creates an instance on demand
      tags:
      - Partner
  /media/{instanceId}/{filepath}:
    get:
      description: |
        Serves a media file with HMAC signature validation for secure access.
        URLs are time-limited and must include valid signature parameters.

        **URL Format:**
        `/media/{instanceId}/{filepath}?sig={signature}&exp={expiration}`

        **Security:**
        - HMAC-SHA256 signature validation
        - Time-limited URLs (configurable expiration)
        - Instance-scoped access control

        **Supported Media Types:**
        - Images (JPEG, PNG, WebP, GIF)
        - Audio (MP3, OGG, M4A)
        - Video (MP4, MOV)
        - Documents (PDF, DOC, etc.)
      operationId: serveMedia
      parameters:
      - description: Instance identifier that owns the media
        in: path
        name: instanceId
        required: true
        schema:
          format: uuid
          type: string
      - description: Path to the media file within instance storage
        example: images/photo_123.jpg
        in: path
        name: filepath
        required: true
        schema:
          type: string
      - description: HMAC-SHA256 signature for URL validation
        example: a1b2c3d4e5f6...
        in: query
        name: sig
        required: true
        schema:
          type: string
      - description: Unix timestamp when the URL expires
        example: 1704067200
        in: query
        name: exp
        required: true
        schema:
          format: int64
          type: integer
      responses:
        "200":
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
            audio/*:
              schema:
                format: binary
                type: string
            image/*:
              schema:
                format: binary
                type: string
            video/*:
              schema:
                format: binary
                type: string
          description: Media file served successfully
        "400":
          content:
            application/json:
              example:
                error: missing signature parameter
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Missing or invalid signature parameters
        "403":
          content:
            application/json:
              example:
                error: invalid signature
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid signature or expired URL
        "404":
          content:
            application/json:
              example:
                error: file not found
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Media file not found
        "410":
          content:
            application/json:
              example:
                error: URL expired
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: URL has expired
      security: []
      summary: Serve media file
      tags:
      - Media
  /media/stats:
    get:
      description: |
        Returns statistics about the media storage system.

        **Statistics Include:**
        - Total number of stored files
        - Total storage size in bytes
        - Base storage path configuration
        - URL expiration settings
        - Public base URL for media access

        **Use Cases:**
        - Monitor storage usage
        - Capacity planning
        - Debug media configuration
      operationId: getMediaStats
      responses:
        "200":
          content:
            application/json:
              example:
                base_path: /data/media
                public_base_url: https://api.example.com/media
                total_bytes: 1073741824
                total_files: 1234
                url_expiry: 24h0m0s
              schema:
                $ref: '#/components/schemas/MediaStatsResponse'
          description: Media statistics retrieved successfully
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
      - PartnerBearer: []
      summary: Get media storage statistics
      tags:
      - Media
  /metrics:
    get:
      description: |
        Exposes application metrics in Prometheus exposition format.
        Includes HTTP request counts, message queue statistics, WhatsApp connection status,
        and event processing metrics.

        **Available Metric Categories:**
        - `http_*`: HTTP request counts and latencies
        - `message_queue_*`: Message queue depth and processing rates
        - `whatsapp_*`: WhatsApp connection and message statistics
        - `event_*`: Event processing metrics
      operationId: prometheusMetrics
      responses:
        "200":
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PrometheusMetrics'
          description: Prometheus metrics in text exposition format
      security: []
      summary: Prometheus metrics endpoint
      tags:
      - System
  /ready:
    get:
      description: |
        Checks critical dependencies (Postgres, Redis lock manager). The service is considered ready when all reported components are `healthy`. Any `degraded` or `unhealthy` status results in a `503` response.
      operationId: healthReadiness
      responses:
        "200":
          content:
            application/json:
              examples:
                ready:
                  value:
                    checks:
                      database:
                        duration_ms: 12
                        status: healthy
                      redis:
                        circuit_state: CLOSED
                        duration_ms: 8
                        status: healthy
                    observed_at: "2024-05-28T10:59:00Z"
                    ready: true
              schema:
                $ref: '#/components/schemas/ReadinessResponse'
          description: Service is ready to receive traffic.
        "503":
          content:
            application/json:
              examples:
                degraded:
                  value:
                    checks:
                      database:
                        duration_ms: 3
                        error: database not configured
                        status: unhealthy
                      redis:
                        circuit_state: OPEN
                        duration_ms: 7
                        error: fallback lock in use
                        status: degraded
                    observed_at: "2024-05-28T11:01:00Z"
                    ready: false
              schema:
                $ref: '#/components/schemas/ReadinessResponse'
          description: At least one dependency is degraded or unavailable.
      security: []
      summary: Readiness probe
      tags:
      - System
servers:
- description: API Server
  url: https://api.whatsgo.wa-api.io
- description: Local development
  url: http://localhost:8080
