{"openapi":"3.1.0","info":{"description":"Production WhatsApp Business API built on Whatsmeow.\nFull-featured REST API for sending messages, managing instances, configuring webhooks, and handling WhatsApp events.\n","title":"Zé da API (Whatsmeow Bridge)","version":"v3.38.0"},"servers":[{"url":"https://api.whatsgo.wa-api.io","description":"API Server"},{"url":"http://localhost:8080","description":"Local development"}],"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/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"]}},"/instances/{instanceId}":{"delete":{"description":"**⚠️ IRREVERSIBLE OPERATION ⚠️**\n\nPermanently deletes a WhatsApp instance including all associated data from both databases.\n\n**Complete Cleanup Operations:**\n- ✅ Disconnects the WhatsApp client immediately\n- ✅ Disables auto-reconnect to prevent reconnection\n- ✅ **Deletes device store from whatsmeow_store database**\n- ✅ Stops lock refresh goroutine\n- ✅ Releases Redis distributed lock\n- ✅ Removes client from in-memory registry\n- ✅ **Deletes instance record from api_core database**\n- ✅ **Deletes all webhook configurations (CASCADE)**\n- ✅ **Deletes all webhook outbox entries (CASCADE)**\n- ✅ **Deletes all webhook DLQ entries (manual deletion)**\n- ✅ **Deletes all instance event logs (manual deletion)**\n\n**Database Deletion Strategy:**\n- Uses transaction to ensure ACID compliance\n- Manually deletes tables without CASCADE constraints (webhook_dlq, instance_events_log)\n- Relies on CASCADE for webhook_configs and webhook_outbox\n- Deletes device credentials from separate whatsmeow_store database\n\n**Authentication:**\n- Requires Partner Bearer token only (no instance token needed)\n- This is a Partner-level administrative operation\n\n**Use Cases:**\n- Cleanup of test/development instances\n- Customer offboarding and data removal\n- GDPR/data deletion compliance requests\n- Freeing resources from inactive instances\n\n**Important Notes:**\n- **This operation cannot be undone or reversed**\n- All data associated with the instance is permanently lost\n- The instance cannot be recovered or reconnected after deletion\n- Consider using `/disconnect` if you need to preserve the instance record\n","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.\n","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/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/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/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/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}/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}/chats":{"get":{"description":"Returns a paginated list of WhatsApp chats (conversations) for the instance.\n\n**Features:**\n- ✅ Pagination support (page, pageSize)\n- ✅ Individual, group, and community chats\n- ✅ Unread message counts\n- ✅ Last message timestamp\n- ✅ Mute status and expiry\n- ✅ Archive, pin, and spam status\n- ✅ X-Total-Count header for total count\n- ✅ Ordered by lastMessageTime (most recent first)\n\n**Chat Types:**\n- Individual chats (person-to-person)\n- Group chats (multiple participants)\n- Community announcement channels\n\n**Data Sources:**\n- WhatsApp chat metadata (from store)\n- Message history (last message timestamp)\n- Chat settings (mute, archive, pin, spam status)\n\n**Ordering:** Chats are ordered by lastMessageTime descending (most recent first).\n\n**Unread Counts:** Both `unread` and `messagesUnread` fields represent the same count.\n","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 \u003e= 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/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}/communities/{communityId}":{"delete":{"description":"Mirrors Zé da API `DELETE /communities/{communityId}`, permanently deleting a community.\n\n**Important**: This action is irreversible. All linked groups will be unlinked but not deleted.\n","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}/contacts":{"get":{"description":"Returns a paginated list of WhatsApp contacts from the instance's device.\n\n**Features:**\n- ✅ Pagination support (page, pageSize)\n- ✅ Device contacts integration (name, short name)\n- ✅ WhatsApp profile data (notify/push name)\n- ✅ VCard information (if shared)\n- ✅ Privacy-aware (respects WhatsApp privacy settings)\n- ✅ X-Total-Count header for total count\n\n**Data Sources:**\n- Device address book (name, short, vname fields)\n- WhatsApp profile (notify field from push name)\n- VCard sharing (vname field)\n\n**Field Availability:**\n- `phone`: Always present (WhatsApp JID)\n- `name`, `short`, `vname`: Only if in address book\n- `notify`: Only if user has interacted with contact\n\n**Privacy Notes:** Contact data respects WhatsApp privacy settings.\nUsers who hide their profile will only show notify field.\n","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 \u003e= 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.\n\n**Data Returned:**\n- `name` — Full name (only if saved in contacts)\n- `phone` — Phone number\n- `notify` — WhatsApp display name\n- `short` — First name (only if saved in contacts)\n- `imgUrl` — Full-quality profile picture URL (expires after 48h)\n- `about` — Status/about text\n","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.\n\n**Note:** Returns empty or error if contact has privacy settings\nthat hide their profile picture from you.\n","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.\n\n**This operation performs the following actions:**\n\n- ✅ Disables auto-reconnect to prevent automatic reconnection\n- ✅ Disconnects WebSocket connection immediately\n- ✅ **Deletes device store from whatsmeow_store database**\n- ✅ Stops lock refresh goroutine\n- ✅ Releases Redis distributed lock\n- ✅ Removes client from in-memory registry\n- ✅ Clears store_jid in api_core database (sets to NULL)\n\n**Important Notes:**\n\n- The instance record remains in the database (status becomes \"disconnected\")\n- To permanently delete the instance, use `DELETE /partner/instances/{instanceId}`\n- After disconnect, you can reconnect by calling `/qrcode` or `/pairphone`\n- All webhook configurations are preserved\n\n**Use Cases:**\n\n- User logout from WhatsApp\n- Switching to a different phone number\n- Temporary disconnection for maintenance\n- Resetting a stuck connection\n\n**Comparison with DELETE endpoint:**\n\n- Disconnect: Keeps instance record, allows reconnection\n- Delete: Permanent removal, cannot be recovered\n","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.\n\n**This operation performs the following actions:**\n- ✅ Disables auto-reconnect to prevent automatic reconnection\n- ✅ Disconnects WebSocket connection immediately\n- ✅ **Deletes device store from whatsmeow_store database**\n- ✅ Stops lock refresh goroutine\n- ✅ Releases Redis distributed lock\n- ✅ Removes client from in-memory registry\n- ✅ Clears store_jid in api_core database (sets to NULL)\n\n**Important Notes:**\n- The instance record remains in the database (status becomes \"disconnected\")\n- To permanently delete the instance, use `DELETE /partner/instances/{instanceId}`\n- After disconnect, you can reconnect by calling `/qrcode` or `/pairphone`\n- All webhook configurations are preserved\n\n**Use Cases:**\n- User logout from WhatsApp\n- Switching to a different phone number\n- Temporary disconnection for maintenance\n- Resetting a stuck connection\n\n**Comparison with DELETE endpoint:**\n- Disconnect: Keeps instance record, allows reconnection\n- Delete: Permanent removal, cannot be recovered\n","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.\n\n**Features:**\n- Forward any message type (text, media, etc.)\n- Preserves original message metadata\n- Shows \"Forwarded\" label on recipient's device\n- FIFO queue with per-recipient ordering\n","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\nability to authenticate with their per-instance token.\n\nAfter deletion, **only** the global `CLIENT_AUTH_TOKEN` will be accepted for this instance.\nThis effectively revokes direct API access for the subscriber while preserving the\nManager's (dashboard) ability to operate the instance via the global token.\n\n**Use cases:**\n- Revoking a subscriber's direct API access after subscription cancellation.\n- Security incident response — immediately invalidate a compromised per-instance token.\n- Resetting token state before assigning a new one via PUT.\n\n**Behavior:**\n- Sets `client_auth_token` to `NULL` in the database.\n- Idempotent: calling DELETE when no per-instance token exists succeeds with the same response.\n- Does not affect the global `CLIENT_AUTH_TOKEN`.\n","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\n(subscriber) to authenticate instance-scoped API calls with their own token instead of\nthe global `CLIENT_AUTH_TOKEN`.\n\n**Authentication model:**\n- The API validates the `Client-Token` header on every instance-scoped request.\n- Two values are accepted: the global token (from `CLIENT_AUTH_TOKEN` env var) **or**\n  the per-instance token stored in the database.\n- Setting a per-instance token does **not** invalidate the global token — both remain valid.\n\n**Use cases:**\n- SaaS platforms generating unique tokens per subscriber so each subscriber only has\n  access to their own instances.\n- Revoking a subscriber's access by deleting their per-instance token (see DELETE endpoint).\n- Rotating a subscriber's token without affecting other instances.\n\n**Validation:**\n- `clientAuthToken` must be a non-empty string.\n- The instance is identified by both `instanceId` and `instanceToken` in the URL path.\n- Requires Partner Bearer authentication.\n","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.\n\n**Features:**\n- ✅ Delete own messages (sender = you)\n- ✅ Delete others' messages (group admin only)\n- ✅ Works in private chats and groups\n- ✅ query parameters\n\n\nUses query parameters instead of request body:\n- `phone` - The chat phone number (recipient)\n- `messageId` - The WhatsApp message ID to delete\n- `owner` - \"true\" for own messages, \"false\" for others (admin delete)\n\n**Behavior:**\n- For `owner=true`: Message is deleted for everyone (\"Delete for Everyone\")\n- For `owner=false`: Admin delete in groups (removes message sent by others)\n- Deleted messages show \"This message was deleted\" placeholder\n\n**Restrictions:**\n- Own messages: Can be deleted within ~1 hour of sending\n- Admin delete: Requires group admin privileges\n- Once deleted, the message cannot be recovered\n","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:\n- \"true\" = your own message (Delete for Everyone)\n- \"false\" = someone else's message (admin delete in groups)\n","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\n(sent, delivered, read, played) for messages, especially useful for group messages\nwhere tracking individual participant statuses is important.\n\n**Important:** This endpoint works independently of webhook configuration.\nYou can use Status Cache in API-only mode (pull) without configuring any webhooks.\n\n**Query Types:**\n- **No filter**: Get ALL cached statuses for the instance (paginated)\n- By `messageId`: Get status for a specific message\n- By `groupId`: Get all message statuses for a group\n- By `phone`: Get all message statuses for a phone number\n\n**Response Formats:**\n- `aggregated` (default): Returns aggregated counts and optionally participant details\n- `raw`: Returns data in Zé da API webhook format for compatibility\n\n**Use Cases:**\n- Check if a message was read by all group participants\n- Get delivery statistics for messages to a specific contact\n- Retrieve batch status updates for UI dashboards\n- Poll for status updates without webhook configuration\n\n**Note:** Status data is cached with a configurable TTL (default 24h).\n\n**Requirements:**\n- `STATUS_CACHE_ENABLED=true` environment variable\n- `STATUS_CACHE_SCOPE` must include the message type (groups, direct, or both)\n","operationId":"getMessagesStatus","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"$ref":"#/components/parameters/InstanceToken"},{"description":"Query status for a specific message. When provided, returns detailed status\nfor that message including all participant statuses.\n","example":"3EB0A1B2C3D4E5F6","in":"query","name":"messageId","required":false,"schema":{"type":"string"}},{"description":"Query all message statuses for a group. Returns paginated results.\nThe groupId should be the numeric part of the WhatsApp JID (without @g.us).\n","example":"120363182823169824","in":"query","name":"groupId","required":false,"schema":{"type":"string"}},{"description":"Query all message statuses for messages to/from a phone number.\nUse E.164 format without the + prefix.\n","example":"5511999999999","in":"query","name":"phone","required":false,"schema":{"type":"string"}},{"description":"Response format:\n- `aggregated`: Returns aggregated counts with optional participant details\n- `raw`: Returns data in Zé da API MessageStatusCallback webhook format\n","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\nparticipant statuses in the response. Useful for detailed analysis\nbut increases response size significantly for groups.\n","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.\n\n**Options:**\n- Clear by `messageId`: Removes cache for a specific message\n- Clear all (`all=true`): Removes all cached entries for the instance\n\n**Warning:** Clearing cache is irreversible. Cached status data and pending\nwebhooks for cleared entries will be permanently deleted.\n\n**Use Cases:**\n- Free up cache storage space\n- Remove obsolete message status data\n- Reset cache after testing\n","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.\n\nWhen `STATUS_CACHE_SUPPRESS_WEBHOOKS=true`, status webhooks are not immediately\nsent but stored for later delivery. This endpoint allows manual triggering\nof those pending webhooks.\n\n**Webhook Requirement:** This endpoint REQUIRES a webhook to be configured:\n- Primary: `messageStatusCallbackUrl`\n- Fallback: `deliveryCallbackUrl`\n\nIf no webhook is configured, flush will succeed but no data will be delivered.\nIn API-only mode, use `/messages-status` GET endpoint instead.\n\n**Use Cases:**\n- Force immediate delivery of status updates to webhook endpoints\n- Recover from webhook endpoint downtime\n- Batch process status updates at specific intervals\n\n**Options:**\n- Flush by specific `messageId`: Delivers webhooks for one message\n- Flush all (`all: true`): Delivers all pending webhooks for the instance\n\n**Note:** Flushing is idempotent - already-flushed webhooks won't be re-sent.\n","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.\n\n**Important:** This endpoint works independently of webhook configuration.\nUse it to verify that Status Cache is receiving and storing events.\n\n**Metrics included:**\n- Total cached entries\n- Entries breakdown by instance\n- Number of pending webhooks awaiting flush\n\n**Use Cases:**\n- Monitor cache usage and storage\n- Determine if flush is needed\n- Debug cache behavior\n- Verify Status Cache is working (totalEntries \u003e 0)\n\n**Troubleshooting:**\nIf `totalEntries` is 0, check:\n1. `STATUS_CACHE_ENABLED=true` is set\n2. `STATUS_CACHE_SCOPE` matches your message types (groups/direct)\n3. `STATUS_CACHE_TYPES` includes the receipt types you expect (read,delivered,played,sent)\n","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.\n\n**Actions:**\n- `block`: Block the contact (they can't message you)\n- `unblock`: Unblock a previously blocked contact\n","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.\n\n**Supported Actions:**\n- `read` - Mark chat as read\n- `archive` - Archive the chat\n- `unarchive` - Unarchive the chat\n- `pin` - Pin the chat to top\n- `unpin` - Unpin the chat\n- `mute` - Mute chat notifications\n- `unmute` - Unmute chat notifications\n- `clear` - Clear all messages in chat\n- `delete` - Delete the entire chat\n\n\nRequest body with `phone` and `action` fields.\n\n**Behavior:**\n- `read`: Marks all messages in chat as read (blue checkmarks)\n- `archive/unarchive`: Moves chat to/from archive\n- `pin/unpin`: Pins/unpins chat to top of chat list\n- `mute/unmute`: Enables/disables notifications\n- `clear`: Removes all messages but keeps chat\n- `delete`: Completely removes the chat\n","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.\n\n**Use Cases:**\n- Bulk contact validation before marketing campaigns\n- CRM data cleansing and enrichment\n- Lead qualification at scale\n- Form validation with multiple numbers\n\n**Important Notes:**\n- Maximum batch size: 50,000 numbers per request\n- Use for validation purposes, not before sending messages\n- Not designed for spam - use responsibly\n\n**Phone Format:**\n- International format: DDI + DDD + NUMBER\n- Numbers only (no formatting, spaces, or masks)\n- Example: `551199999999` (Brazil mobile)\n\n**Response Fields:**\n- `exists`: Whether the phone has WhatsApp\n- `inputPhone`: The number as you sent it\n- `outputPhone`: The number formatted by WhatsApp (may include 9th digit)\n","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.\n\n**Use Cases:**\n- Form validation (verify phone before saving)\n- Contact verification before sending messages\n- Lead qualification in CRM systems\n\n**Important Notes:**\n- Use this API for form validation purposes\n- Do NOT use before sending messages (Zé da API validates automatically)\n- Using for message validation creates duplicate checks\n- Not designed for spam - use responsibly\n\n**Phone Format:**\n- International format: DDI + DDD + NUMBER\n- Numbers only (no formatting, spaces, or masks)\n- Example: `551199999999` (Brazil mobile)\n","operationId":"phoneExists","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"$ref":"#/components/parameters/InstanceToken"},{"description":"Phone number in international format (DDI DDD NUMBER).\nNumbers only - no formatting, spaces, or masks.\n","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.\n\n**Note:** This pins/unpins the entire chat, not individual messages.\n\n**Features:**\n- Pin important conversations to top of chat list\n- Unpin to remove from pinned section\n","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.\n\n**Settings Returned:**\n- `groupAdd`: Who can add you to groups (all, contacts, contact_blacklist)\n- `lastSeen`: Who can see your last seen (all, contacts, contact_blacklist, none)\n- `status`: Who can see your status (all, contacts, contact_blacklist, none)\n- `profile`: Who can see your profile photo (all, contacts, contact_blacklist, none)\n- `readReceipts`: Read receipts setting (all, none)\n- `online`: Online status visibility (all, match_last_seen)\n- `callAdd`: Who can call you (all, known)\n","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.\n\n**Values:**\n- `all`: Anyone can call you\n- `known`: Only known contacts can call you\n","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.\n\n**Values:**\n- `all`: Anyone can add you\n- `contacts`: Only contacts can add you\n- `contact_blacklist`: Contacts except blocked\n","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.\n\n**Values:**\n- `all`: Everyone can see\n- `contacts`: Only contacts can see\n- `contact_blacklist`: Contacts except blocked\n- `none`: Nobody can see\n","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.\n\n**Values:**\n- `all`: Everyone can see when you're online\n- `match_last_seen`: Match your last seen setting\n","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.\n\n**Values:**\n- `all`: Everyone can see\n- `contacts`: Only contacts can see\n- `contact_blacklist`: Contacts except blocked\n- `none`: Nobody can see\n","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.\n\n**Values:**\n- `all`: Send and receive read receipts\n- `none`: Disable read receipts (you won't see others' either)\n","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.\n\n**Values:**\n- `all`: Everyone can see\n- `contacts`: Only contacts can see\n- `contact_blacklist`: Contacts except blocked\n- `none`: Nobody can see\n","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.\n\n**Note:** This is the text that appears in your profile's \"About\" section.\nCan be empty to clear the description.\n","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.\n\n**Note:** This is the name that appears to other users in their\nchat list and message notifications.\n","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.\n\n**Image Format:**\n- Base64-encoded JPEG image\n- Image URL (http/https)\n- Empty string to remove profile picture\n\n**Requirements:**\n- JPEG format recommended\n- Other formats may be rejected\n","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.\nThe client reverts to direct connection (or environment proxy).\n","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.\nUseful for monitoring proxy reliability and diagnosing connectivity issues.\n","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.\nThe new proxy is tested before applying. The client is disconnected\nfrom the current proxy and immediately reconnected through the new one.\nThe WhatsApp session is preserved - only the transport changes.\n\n**Important:** The proxy is validated before swap. If the new proxy\nis unreachable, the swap is rejected and the current connection is maintained.\n","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.\nDoes NOT apply the proxy - use update-proxy to apply it.\nReturns reachability status and latency.\n","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.\n\n**Behavior:**\n- ✅ Removes messages in state: `available`, `scheduled`\n- ❌ Does NOT affect messages: `running`, `completed`, `failed`, `discarded`\n\n**Use Cases:**\n- Emergency stop of all pending messages\n- Queue cleanup during maintenance\n- Cancel all scheduled messages at once\n\n\n\n","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.\n\n\n\n- Uses `page` and `pageSize` parameters\n- Returns direct array of messages (not wrapped in object)\n- Field names in camelCase\n- Delays in seconds (not milliseconds)\n- Created timestamp in milliseconds\n\n**Response Format:**\n- Direct array: `[{message1}, {message2}, ...]`\n- NOT wrapped: `{data: [{message1}]}` ❌\n\n**Pagination:**\n- `page`: Page number starting from 1\n- `pageSize`: Messages per page (default 100, max 1000)\n","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/count":{"get":{"description":"Returns the total number of messages in the queue for a specific instance.\n\n\n\n","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}/queue/{zaapId}":{"delete":{"description":"Cancels a pending message by its zaapId (returned when message was enqueued).\n\n**Behavior:**\n- ✅ Cancels messages in state: `available`, `scheduled`, `retryable`\n- ❌ Returns error if message already processed or doesn't exist\n\n\n\n","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}/read-message":{"post":{"description":"Marks one or more messages as read (sends read receipts/blue ticks).\n\n**Features:**\n- Mark single or multiple messages as read\n- Works for both individual and group chats\n- Immediate execution (not queued)\n","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.\n","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.\n\nAfter WhatsApp's LID migration, some contacts are stored with @lid JIDs instead\nof phone-based JIDs. This endpoint resolves those LIDs to actual phone numbers\nwhen a mapping is available in the local store.\n\n**Important Notes:**\n- Resolution depends on existing LID mappings in the store\n- Mappings are populated when IsOnWhatsApp or GetUserInfo are called\n- New instances may have empty LID stores until contacts are queried\n- Maximum batch size: 1,000 LIDs per request\n","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.\n\n**Features:**\n- ✅ Audio URL or base64 data URI support\n- ✅ Voice note (PTT) detection\n- ✅ \"Recording audio\" indicator (delayTyping)\n- ✅ View once support\n- ✅ Reply-to message support\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n\n**Supported Formats:** OGG, MP3, WAV\n\n\n\n","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.\n\n**Status Broadcasting**: The audio is automatically broadcast to all contacts\nwho can view your status based on your privacy settings. No phone number\nis required - the message is sent to `status@broadcast`.\n\n**Key Features**:\n- Audio URL or base64 data URI support\n- **Automatic waveform generation** (64 samples for visual bars - \"ondinhas\")\n- Voice note (PTT) format with waveform visualization\n- Automatic conversion to Opus/OGG if needed\n- FIFO queue with non-blocking response\n- Optional custom message ID for tracking\n\n**Waveform Visualization**: The audio is processed to generate\n64 amplitude samples (0-100 range) that WhatsApp displays as\nthe classic wave bars in the voice note player. This creates the\nfamiliar \"ondinhas\" (little waves) visualization.\n\n**Supported Formats**: OGG (Opus), MP3, WAV, M4A, AAC, FLAC\n\n**Working Audio URLs for Testing**:\n| Source | URL | Description |\n|--------|-----|-------------|\n| SoundHelix | https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3 | Electronic music |\n| SampleLib | https://samplelib.com/lib/preview/mp3/sample-3s.mp3 | 3-second sample |\n| File Examples | https://filesamples.com/samples/audio/mp3/sample1.mp3 | MP3 sample |\n| Internet Archive | https://archive.org/download/testmp3testfile/mpthreetest.mp3 | Test MP3 |\n\n**Audio Processing Pipeline**:\n1. Download audio from URL or decode base64\n2. Detect format and convert to Opus/OGG if needed\n3. Generate 64-sample waveform for visualization\n4. Calculate duration for progress bar\n5. Upload to WhatsApp servers\n6. Send as PTT (Push-To-Talk) voice note\n","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).\nSupports URL, call, copy, and quick reply buttons.\n\n**Button Types:**\n- `quick_reply` - Simple reply button (max 20 chars label)\n- `cta_url` - Opens a URL in browser\n- `cta_call` - Initiates a phone call\n- `cta_copy` - Copies text to clipboard\n- `payment_info` - Payment information button\n- `review_and_pay` - Review and pay action\n\n**Features:**\n- ✅ Up to 3 action buttons\n- ✅ Optional header image\n- ✅ Title, message body, and footer\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n\n**Limits:**\n- Max 3 buttons per message\n- Label: max 25 characters (20 for quick_reply)\n- Title: max 60 characters\n- Message: max 1024 characters\n- Footer: max 60 characters\n","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.\nThe recipient can tap a button to respond.\n\n**Features:**\n- ✅ Up to 3 quick reply buttons\n- ✅ Header title and message body\n- ✅ Footer text\n- ✅ Optional image or video header\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n- ✅ Non-blocking (returns immediately with zaapId)\n\n**Limits:**\n- Max 3 buttons\n- Title: max 60 characters\n- Message: max 1024 characters\n- Footer: max 60 characters\n- Button title: max 20 characters\n\n**Use Cases:**\n- Quick response options (Yes/No/Maybe)\n- Survey responses\n- Confirmation dialogs\n- Simple navigation\n","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.\nThe recipient can easily copy the code with one tap.\n\n**Use Cases:**\n- Account verification\n- Two-factor authentication (2FA)\n- Password reset codes\n- Login verification\n- Transaction confirmation\n\n**Features:**\n- ✅ Prominent OTP code display\n- ✅ One-tap copy button\n- ✅ Custom button text\n- ✅ Expiration message support\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n\n**Security Notes:**\n- OTP codes should have limited validity (typically 5-10 minutes)\n- Messages automatically include security warnings\n- Never log or store OTP codes in plain text\n","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).\nIncludes QR code generation and copy-paste PIX code button.\n\n**PIX Key Types:**\n- `CPF` - Brazilian individual taxpayer ID (11 digits)\n- `CNPJ` - Brazilian company taxpayer ID (14 digits)\n- `EMAIL` - Email address\n- `PHONE` - Phone number with country code\n- `EVP` - Random PIX key (UUID format)\n\n**Features:**\n- ✅ Automatic PIX QR code generation\n- ✅ Copy PIX code button\n- ✅ Payment amount and description\n- ✅ Beneficiary name display\n- ✅ Transaction ID for reconciliation\n- ✅ Additional action buttons\n- ✅ Custom message ID for tracking\n- ✅ FIFO queue with per-recipient ordering\n\n**Required Fields:**\n- `phone` - Recipient WhatsApp number\n- `payment.keyType` - Type of PIX key\n- `payment.key` - The PIX key value\n- `payment.name` - Beneficiary name\n- `payment.amount` - Payment amount in BRL\n","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.\nEach card can have an image/video header, body text, and action buttons.\n\n**Features:**\n- ✅ 1-10 cards per carousel\n- ✅ Image or video header per card\n- ✅ Body text per card\n- ✅ Up to 2 action buttons per card\n- ✅ Horizontal swipe navigation\n- ✅ Introduction message before carousel\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n\n**Limits:**\n- Min 1 card, max 10 cards\n- Max 2 buttons per card\n- Body text: max 1024 characters per card\n- Header media: image or video URL\n\n**Use Cases:**\n- Product catalogs\n- Image galleries\n- Service showcases\n- Portfolio presentations\n- Tutorial sequences\n\n**Media Formats:**\n- Images: JPEG, PNG, WebP\n- Videos: MP4 (recommended), 3GP\n","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\n\nCaptured 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\n\nSwiss Alps in winter","buttons":[{"id":"btn_mountains","label":"Like","type":"quick_reply"}],"mediaUrl":"https://picsum.photos/id/11/600/400.jpg"},{"body":"Ocean Waves\n\nMaldives crystal clear waters","buttons":[{"id":"btn_ocean","label":"Like","type":"quick_reply"}],"mediaUrl":"https://picsum.photos/id/12/600/400.jpg"},{"body":"Forest Path\n\nRedwood National Park","buttons":[{"id":"btn_forest","label":"Like","type":"quick_reply"}],"mediaUrl":"https://picsum.photos/id/13/600/400.jpg"},{"body":"City Lights\n\nNew 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\n\nOur flagship product with advanced features.\n\n$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\n\nPerfect for everyday use.\n\n$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\n\nCompact and portable design.\n\n$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\n\n4 bed | 3 bath | 2,500 sqft\nPacific Heights, SF\n\n$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\n\n2 bed | 2 bath | 1,200 sqft\nSoMa District\n\n$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\n\n3 bed | 2.5 bath | 1,800 sqft\nMission District\n\n$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\n\n12oz USDA Prime, grilled to perfection\nServed with seasonal vegetables\n\n$45.00","buttons":[{"id":"order_steak","label":"Order Now","type":"quick_reply"}],"mediaUrl":"https://picsum.photos/id/292/600/400.jpg"},{"body":"Atlantic Salmon\n\nFresh salmon with lemon butter sauce\nAsparagus and rice pilaf\n\n$32.00","buttons":[{"id":"order_salmon","label":"Order Now","type":"quick_reply"}],"mediaUrl":"https://picsum.photos/id/493/600/400.jpg"},{"body":"Truffle Pasta\n\nFresh fettuccine with black truffle\nParmesan and cream sauce\n\n$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\n\nOnly 50 units available worldwide.\nGet 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\n\nLearn 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\n\nUnlock 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 \u0026 Tricks\n\nBoost 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.\n\n**Features:**\n- ✅ Document URL or base64 data URI support\n- ✅ Custom filename support\n- ✅ Optional caption/description\n- ✅ Reply-to message support\n- ✅ Typing indicator and delayed sending\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n\n**Supported Formats:** PDF, DOC, DOCX, XLS, XLSX, TXT, CSV, ZIP, RAR\n\n\n\n","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.\n\n**Features:**\n- Update event name, description, location\n- Change start and end times\n- Cancel the event\n- Optional typing simulation before sending\n\n**Note:** You must have created the original event or have permission to edit it.\n","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.\n\n**Features:**\n- ✅ Event name and description\n- ✅ Date and time scheduling (ISO 8601)\n- ✅ Location support (name and coordinates)\n- ✅ Call link type (voice/video)\n- ✅ Event cancellation support\n- ✅ Custom message ID for tracking\n- ✅ FIFO queue with per-recipient ordering\n\n\n- Nested `event` object with all event details\n- `dateTime` in ISO 8601 format (e.g., \"2024-04-29T09:30:53.309Z\")\n- `location` object with name and optional coordinates\n- `callLinkType` can be \"voice\" or \"video\"\n\n**Restrictions:**\n- Events can only be sent to groups\n- Sender must be group admin for some event features\n","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).\n\n**Response Types:**\n- `going` - Confirm attendance\n- `not_going` - Decline invitation\n- `maybe` - Tentative response\n\n**Features:**\n- Specify additional guests count\n- Optional typing simulation before sending\n\n**Note:** Event responses are encrypted and require the original event's message secret.\nThis endpoint sends an encrypted response referencing the original event.\n","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.\n\n**Features:**\n- ✅ GIF URL or base64 data URI support\n- ✅ Animated GIFs\n- ✅ Optional caption/text\n- ✅ View once support (disappears after viewing)\n- ✅ Reply-to message support\n- ✅ Typing indicator and delayed sending\n- ✅ Ephemeral/disappearing messages support\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n- ✅ Private reply in groups (privateAnswer)\n- ✅ FIFO queue with per-recipient ordering\n- ✅ Non-blocking (returns immediately with zaapId)\n\n**GIF Format:**\n- GIF format (animated or static)\n- Any aspect ratio (auto-adjusted by WhatsApp)\n- Max 16MB recommended\n- Supports caption with @mentions\n\n**Supported Formats:**\n- URL: `https://media.giphy.com/media/3o7abKhOpu0NwenH3O/giphy.gif`\n- Base64: `data:image/gif;base64,R0lGODlhAQABAIAAAP...`\n","operationId":"sendGifMessage","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"$ref":"#/components/parameters/InstanceToken"}],"requestBody":{"content":{"application/json":{"example":{"caption":"Check this out! 🎉","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.\n\n**Features:**\n- ✅ Image URL or base64 data URI support\n- ✅ Optional caption/title\n- ✅ View once support (disappears after viewing)\n- ✅ Reply-to message support\n- ✅ Typing indicator and delayed sending\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n- ✅ FIFO queue with per-recipient ordering\n\n**Supported Formats:**\n- Image URL: `https://picsum.photos/600/400.jpg`\n- Base64: `data:image/png;base64,iVBORw0KG...`\n\n\n\n","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.\n\n**Status Broadcasting**: The image is automatically broadcast to all contacts\nwho can view your status based on your privacy settings. No phone number\nis required - the message is sent to `status@broadcast`.\n\n**Key Features**:\n- Image URL or base64 data URI support\n- Optional caption/text overlay\n- Automatic thumbnail generation\n- FIFO queue with non-blocking response\n- Optional custom message ID for tracking\n\n**Supported Formats**: JPEG, PNG, WebP, GIF (static)\n\n**Recommended Dimensions**: 1080x1920 pixels (9:16 aspect ratio for Stories)\n\n**Working Image URLs for Testing**:\n| Source | URL | Description |\n|--------|-----|-------------|\n| Picsum | https://picsum.photos/1080/1920 | Random HD image |\n| Unsplash | https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=1080 | Mountain landscape |\n| Placeholder | https://placehold.co/1080x1920/3498DB/FFFFFF/png?text=Status | Custom placeholder |\n| Lorem Flickr | https://loremflickr.com/1080/1920/nature | Random nature image |\n","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\u0026q=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\u0026q=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\u0026q=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\u0026q=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.\n\n**Features:**\n- ✅ Custom link preview title\n- ✅ Custom link preview description\n- ✅ Custom preview image\n- ✅ Message text before the link\n- ✅ Automatic URL validation\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n\n\n- `linkUrl` is the URL to preview (required)\n- `title` overrides the default link title\n- `linkDescription` overrides the default description\n- `image` provides a custom preview thumbnail\n- `message` adds text before the link preview\n\n**Preview Image:**\n- Must be a valid image URL (JPEG, PNG, WebP)\n- Will be downloaded and used as thumbnail\n- Falls back to default Open Graph image if download fails\n","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.\nSimilar to button list but without sections (flat list).\n\n**Features:**\n- ✅ Simple flat list of options\n- ✅ Up to 10 options\n- ✅ Title and description for each option\n- ✅ Button to open options\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n\n**Limits:**\n- Max 10 options\n- Title: max 60 characters\n- Option title: max 24 characters\n- Option description: max 72 characters\n- Button text: max 20 characters\n\n**Use Cases:**\n- Simple surveys\n- Quick polls\n- Rating selection\n- Single-level menus\n","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.\n\n**Features:**\n- ✅ 2-12 poll options\n- ✅ Single or multiple choice voting\n- ✅ Custom message ID for tracking\n- ✅ Delay message support\n- ✅ FIFO queue with per-recipient ordering\n\n\n- `message` field contains the poll question\n- `poll` array contains options with `name` field\n- `pollMaxOptions` controls voting: 0 or 1 = single choice, \u003e1 = multiple choice\n\n**Limits:**\n- Min 2 options, max 12 options\n- Option text: max 100 characters each\n- Question text: max 256 characters\n","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.\n\n**Features:**\n- Vote for one or multiple options (depending on poll settings)\n- Options are specified by name (exact match)\n- FIFO queue with per-recipient ordering\n","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.\n\n**What is PTV?**\nPTV messages are circular video notes, displayed similarly to voice notes but with video content.\nThey appear as circular thumbnails in the chat and play inline when tapped.\n\n**Features:**\n- ✅ Circular video notes (like voice notes with video)\n- ✅ Video URL or base64 data URI support\n- ✅ Optional caption/text\n- ✅ Reply-to message support\n- ✅ Typing indicator and delayed sending\n- ✅ Ephemeral/disappearing messages support\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n- ✅ Private reply in groups (privateAnswer)\n- ✅ FIFO queue with per-recipient ordering\n- ✅ Non-blocking (returns immediately with zaapId)\n\n**Video Format:**\n- MP4, 3GP, MOV (auto-converted if needed)\n- Max duration: 60 seconds recommended\n- Displayed as circular video in WhatsApp\n\n**Supported Formats:**\n- URL: `https://example.com/video.mp4`\n- Base64: `data:video/mp4;base64,AAAAIGZ0eXBpc29t...`\n","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.\n\n**Features:**\n- React with any emoji\n- Works on individual and group messages\n- FIFO queue with per-recipient ordering\n","operationId":"sendReaction","parameters":[{"$ref":"#/components/parameters/InstanceId"},{"$ref":"#/components/parameters/InstanceToken"}],"requestBody":{"content":{"application/json":{"example":{"messageId":"3EB047ED70306656281B34","phone":"5511999999999","reaction":"👍"},"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.\n\n**Features:**\n- Remove your reaction from any message\n- Works on individual and group messages\n","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.\n\n**Features:**\n- ✅ Sticker URL or base64 data URI support\n- ✅ Animated stickers (WebP format)\n- ✅ Reply-to message support\n- ✅ Typing indicator and delayed sending\n- ✅ Ephemeral/disappearing messages support\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n- ✅ Private reply in groups (privateAnswer)\n- ✅ FIFO queue with per-recipient ordering\n- ✅ Non-blocking (returns immediately with zaapId)\n\n**Sticker Format:**\n- WebP format (animated or static)\n- 512x512 pixels recommended\n- Max 100KB for animated, 500KB for static\n- No caption support (stickers don't have text)\n\n**Supported Formats:**\n- URL: `https://www.gstatic.com/webp/gallery/1.webp`\n- Base64: `data:image/webp;base64,UklGRiQAAABXRUJQ...`\n","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.\n\n**Features:**\n- ✅ Text message with optional reply-to\n- ✅ Typing indicator simulation (delayTyping)\n- ✅ Delayed sending (delayMessage)\n- ✅ Ephemeral/disappearing messages support\n- ✅ Private reply in groups (privateAnswer)\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n- ✅ FIFO queue with per-recipient ordering\n- ✅ Non-blocking (returns immediately with zaapId)\n\n\n\n","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.\n\n**Status Broadcasting**: The text is automatically broadcast to all contacts\nwho can view your status based on your privacy settings. No phone number\nis required - the message is sent to `status@broadcast`.\n\n**Key Features**:\n- Custom background color (hex #RRGGBB or ARGB 0xAARRGGBB)\n- Multiple font styles (0-5)\n- FIFO queue with non-blocking response\n- Optional custom message ID for tracking\n- Delayed sending and scheduled delivery support (delayMessage or scheduledFor)\n\n**Font Styles**:\n| Value | Font Name | Description |\n|-------|-----------|-------------|\n| 0 | Sans-serif | Default clean font |\n| 1 | Serif | Classic serif font |\n| 2 | Norican Script | Elegant cursive script |\n| 3 | Bryndan Write | Handwritten style |\n| 4 | Bebasneue Regular | Bold condensed |\n| 5 | Oswald Heavy | Strong impact font |\n\n**Background Color Examples**:\n| Color | Hex Code | Description |\n|-------|----------|-------------|\n| Red | #FF5733 | Vibrant red-orange |\n| Blue | #3498DB | Sky blue |\n| Green | #2ECC71 | Emerald green |\n| Purple | #9B59B6 | Amethyst purple |\n| Orange | #F39C12 | Warm orange |\n| Pink | #E91E63 | Hot pink |\n| Teal | #1ABC9C | Turquoise |\n| Dark | #2C3E50 | Dark blue-gray |\n","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.\n\n**Features:**\n- ✅ Video URL or base64 data URI support\n- ✅ Optional caption/title\n- ✅ View once support\n- ✅ Reply-to message support\n- ✅ Typing indicator and delayed sending\n- ✅ Mentions support (mentioned, groupMentioned, mentionedAll)\n\n**Supported Formats:** MP4, 3GP, AVI, MOV\n\n\n\n","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.\n\n**Status Broadcasting**: The video is automatically broadcast to all contacts\nwho can view your status based on your privacy settings. No phone number\nis required - the message is sent to `status@broadcast`.\n\n**Key Features**:\n- Video URL or base64 data URI support\n- Optional caption/text overlay\n- Automatic thumbnail generation\n- FIFO queue with non-blocking response\n- Optional custom message ID for tracking\n\n**Supported Formats**: MP4, 3GP, MOV, AVI, WebM\n**Duration Limit**: WhatsApp status videos are limited to 30 seconds\n**Recommended Resolution**: 720p or 1080p vertical (9:16 aspect ratio)\n\n**Working Video URLs for Testing**:\n| Source | URL | Description |\n|--------|-----|-------------|\n| Blender | https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4 | Big Buck Bunny (small) |\n| Sample Videos | https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4 | 720p 1MB sample |\n| File Samples | https://filesamples.com/samples/video/mp4/sample_640x360.mp4 | 640x360 sample |\n| Test Videos | https://test-videos.co.uk/vids/bigbuckbunny/mp4/h264/360/Big_Buck_Bunny_360_10s_1MB.mp4 | 10s test video |\n\n**Video Processing Pipeline**:\n1. Download video from URL or decode base64\n2. Validate format and duration (max 30s for status)\n3. Generate thumbnail frame\n4. Upload to WhatsApp servers\n5. Send to status@broadcast\n","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.\nSupports HTTP, HTTPS, and SOCKS5 proxies.\nThe proxy is applied to the live client if connected.\n","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"]}},"/media/stats":{"get":{"description":"Returns statistics about the media storage system.\n\n**Statistics Include:**\n- Total number of stored files\n- Total storage size in bytes\n- Base storage path configuration\n- URL expiration settings\n- Public base URL for media access\n\n**Use Cases:**\n- Monitor storage usage\n- Capacity planning\n- Debug media configuration\n","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"]}},"/media/{instanceId}/{filepath}":{"get":{"description":"Serves a media file with HMAC signature validation for secure access.\nURLs are time-limited and must include valid signature parameters.\n\n**URL Format:**\n`/media/{instanceId}/{filepath}?sig={signature}\u0026exp={expiration}`\n\n**Security:**\n- HMAC-SHA256 signature validation\n- Time-limited URLs (configurable expiration)\n- Instance-scoped access control\n\n**Supported Media Types:**\n- Images (JPEG, PNG, WebP, GIF)\n- Audio (MP3, OGG, M4A)\n- Video (MP4, MOV)\n- Documents (PDF, DOC, etc.)\n","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"]}},"/metrics":{"get":{"description":"Exposes application metrics in Prometheus exposition format.\nIncludes HTTP request counts, message queue statistics, WhatsApp connection status,\nand event processing metrics.\n\n**Available Metric Categories:**\n- `http_*`: HTTP request counts and latencies\n- `message_queue_*`: Message queue depth and processing rates\n- `whatsapp_*`: WhatsApp connection and message statistics\n- `event_*`: Event processing metrics\n","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.\n","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"]}}},"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).\n\n**Supported Actions:**\n- Open URL (`cta_url`)\n- Make call (`cta_call`)\n- Copy text (`cta_copy`)\n- Quick reply (`quick_reply`)\n","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.\n\n**Limits:**\n- ID: max 256 characters\n- Title: max 20 characters\n","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.\n\n**Button Types:**\n- `quick_reply` - Simple reply button (max 20 chars label)\n- `cta_url` - Opens a URL in browser\n- `cta_call` - Initiates a phone call\n- `cta_copy` - Copies text to clipboard\n- `payment_info` - Shows payment information\n- `review_and_pay` - Review and pay action\n","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.\n\n**Structure:**\n- mediaUrl: URL for card image/video (required)\n- body: Text content (required, max 1024 chars)\n- buttons: Action buttons (required, 1-3 per card)\n- header: Optional header text (max 60 chars)\n- footer: Optional footer text (max 60 chars)\n\n**Limits:**\n- Body text: max 1024 characters\n- Buttons per card: 1-3\n- Header text: max 60 characters\n- Footer text: max 60 characters\n","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.\n\n**Chat Types**:\n- Individual chats (person-to-person)\n- Group chats (multiple participants)\n- Community announcement channels\n\n**Data Sources**:\n- WhatsApp chat metadata (from store)\n- Message history (last message timestamp)\n- Chat settings (mute, archive, pin, spam status)\n\n**Ordering**: By default, chats are ordered by lastMessageTime descending (most recent first).\n\n**Unread Counts**: Both `unread` and `messagesUnread` represent the same count.\n","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).\nCommunities are treated as groups.\n","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.\nUsed for sorting chats by recency.\n","example":"2025-01-11T14:30:00Z","format":"date-time","type":"string"},"messagesUnread":{"description":"Alternative unread count field.\nContains the same value as `unread`.\n","example":5,"minimum":0,"type":"integer"},"muteEndTime":{"description":"ISO 8601 timestamp when mute expires (if chat is muted).\nZero value if not muted or muted indefinitely.\n","example":"2025-01-12T14:30:00Z","format":"date-time","type":"string"},"name":{"description":"Chat display name.\n\n**For Individuals**: Contact name (from address book) or WhatsApp push name\n**For Groups**: Group subject/title\n**For Communities**: Community name\n","example":"João Silva","type":"string"},"phone":{"description":"WhatsApp JID (Java ID) for the chat.\n\n**Formats**:\n- Individual: `5511999999999@s.whatsapp.net`\n- Group: `120363047204807488@g.us`\n- Newsletter: `123456789@newsletter`\n","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\nthe `Client-Token` header when making instance-scoped API calls.\nMust be a non-empty string. UUIDs are recommended for uniqueness.\n","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.\n\n**Data Sources**:\n- Device contacts (if contact is in user's address book)\n- WhatsApp profile data (notify field from push name)\n- VCard information (if contact shared via vcard)\n\n**Field Availability**:\n- `phone`: Always present\n- `name`, `short`, `vname`: Only if contact is in address book\n- `notify`: Only if user has interacted with contact\n\n**Privacy Notes**: Contact data respects WhatsApp privacy settings.\nUsers who hide their profile will only show notify field.\n","properties":{"lid":{"description":"LID JID string if the contact is stored as a Linked ID (LID).\nPresent only for contacts that were stored with @lid JIDs after\nWhatsApp's LID migration.\n","example":"102473725436019:0@lid","type":"string"},"name":{"description":"Full contact name from device address book.\nOnly present if contact exists in user's phone contacts.\n","example":"João Silva Santos","type":["string","null"]},"notify":{"description":"Name from WhatsApp settings (push name).\nThis is how the user identifies themselves on WhatsApp.\nPresent if user has ever interacted with the contact.\n","example":"João S.","type":["string","null"]},"phone":{"description":"WhatsApp phone number in international format (without + prefix).\nThis is the WhatsApp JID user part.\n","example":"5511999999999","type":"string"},"resolvedPhone":{"description":"Resolved phone number from the LID mapping store.\nPresent only for LID contacts where a phone number mapping was found.\n","example":"5511999999999","type":"string"},"short":{"description":"First name or nickname from device address book.\nOnly present if contact exists in user's phone contacts.\n","example":"João","type":["string","null"]},"vname":{"description":"Full name from VCard if contact was shared via contact card.\nOnly present if contact was received through VCard sharing.\n","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.\n\n**Usage:**\n- For `quick_reply`: Only `id` and `label` required\n- For `cta_url`: Requires `url` field\n- For `cta_call`: Requires `phone` field\n- For `cta_copy`: Requires `copyCode` field\n\n**Label Limits:**\n- `quick_reply`: max 20 characters\n- Other types: max 25 characters\n","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.\nResolves WhatsApp Linked IDs (LIDs) to phone numbers using the local LID store.\n","properties":{"lids":{"description":"Array of LID strings to resolve.\nEach LID must be a valid WhatsApp LID JID (e.g. \"102473725436019:0@lid\").\n","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.\n\n**Limits:**\n- Title: max 24 characters\n- Description: max 72 characters\n","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.\n\n**Limits:**\n- Title: max 24 characters\n- Rows per section: max 10\n","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.\n\n**Supported Actions:**\n- read: Mark chat as read\n- archive: Archive the chat\n- unarchive: Unarchive the chat\n- pin: Pin the chat\n- unpin: Unpin the chat\n- mute: Mute notifications (8 hours default)\n- unmute: Unmute notifications\n- clear: Clear chat messages (not supported by whatsmeow)\n- delete: Delete the chat\n","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.\n\n**PIX Key Types:**\n- `CPF` - Brazilian individual taxpayer ID (11 digits)\n- `CNPJ` - Brazilian company taxpayer ID (14 digits)\n- `EMAIL` - Email address\n- `PHONE` - Phone number with country code\n- `EVP` - Random PIX key (UUID format)\n","enum":["CPF","CNPJ","EMAIL","PHONE","EVP"],"example":"CPF","type":"string"},"PIXPayment":{"additionalProperties":false,"description":"PIX payment information for Brazilian payment messages.\n\n**Required Fields:**\n- `keyType`: Type of PIX key\n- `key`: The PIX key value\n- `name`: Beneficiary name\n- `amount`: Payment amount in BRL\n\n**Optional Fields:**\n- `description`: Payment description\n- `merchantCity`: Merchant city for PIX\n- `merchantName`: Merchant name\n- `txId`: Transaction identifier\n","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\ninstance-scoped API calls using this token instead of the global CLIENT_AUTH_TOKEN.\nIf omitted, only the global token is accepted for this instance.\n","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.\nAllows validating up to 50,000 phone numbers in a single request.\n","properties":{"phones":{"description":"Array of phone numbers to validate.\nEach number must be in international format (DDI DDD NUMBER).\nNumbers only - no formatting, spaces, or masks.\n","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.\nContains the validation result for each phone number in the batch.\n","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.\nReflects the WhatsApp registration and includes ninth digit if applicable.\n","example":"554499999999","type":"string"}},"required":["exists","inputPhone","outputPhone"],"type":"object"},"PhoneExistsResponse":{"additionalProperties":false,"description":"response for phone number validation.\nReturns whether a phone number is registered on WhatsApp along with phone and LID.\n","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.\nContains application metrics including:\n- HTTP request counts and latencies\n- Message queue statistics\n- WhatsApp connection status\n- Event processing metrics\n","example":"# HELP http_requests_total Total HTTP requests\n# TYPE http_requests_total counter\nhttp_requests_total{method=\"GET\",path=\"/health\"} 1234\n","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.\n\n**Status Broadcasting**: Audio is automatically broadcast to all contacts\nwho can view your status based on your privacy settings.\n\n**Key Features**:\n- Audio URL or base64 data URI support\n- Automatic waveform generation (64 samples) for visual bars\n- Voice note (PTT) format with waveform visualization\n- Automatic conversion to Opus/OGG if needed\n- Optional custom message ID for tracking\n\n**Waveform Visualization**: The audio is processed to generate\n64 amplitude samples (0-100 range) that WhatsApp displays as\nthe classic \"ondinhas\" (wave bars) in the voice note player.\n\n**Supported Formats**: OGG (Opus), MP3, WAV, M4A, AAC\n","properties":{"audio":{"description":"Audio URL (http/https) or base64 data URI.\n\n**Examples**:\n- URL: `https://example.com/audio.mp3`\n- Base64: `data:audio/ogg;base64,T2dnUwACAA...`\n\n**Recommended**: OGG Opus format for best compatibility\n","example":"https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3","type":"string"},"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"messageId":{"description":"Optional custom message ID for tracking.\nIf not provided, WhatsApp generates one automatically.\n","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.\n\n**Features:**\n- CTA buttons (URL, Call, Copy)\n- Optional image header\n- Quick reply buttons\n\n**Button Types:**\n- `quick_reply` - Simple reply button\n- `cta_url` - Opens a URL\n- `cta_call` - Initiates a phone call\n- `cta_copy` - Copies text to clipboard\n\n**Limits:**\n- Max 3 buttons\n- Label: max 25 chars (20 for quick_reply)\n- Title: max 60 chars\n- Message: max 1024 chars\n- Footer: max 60 chars\n\n**Message Queue:** Messages are queued per recipient with FIFO ordering.\n","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.\n\n**Formats:**\n- URL: `https://picsum.photos/600/400.jpg`\n- Base64: `data:image/png;base64,...`\n","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.\n\n**Features:**\n- Simple reply buttons (1-3 buttons)\n- Optional header image/video\n- Quick selection callbacks\n\n**Limits:**\n- Max 3 buttons\n- Title: max 60 chars\n- Message: max 1024 chars\n- Footer: max 60 chars\n- Button title: max 20 chars\n\n**Message Queue:** Messages are queued per recipient with FIFO ordering.\n","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.\n\n**Formats:**\n- URL: `https://picsum.photos/600/400.jpg`\n- Base64: `data:image/png;base64,...`\n","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).\n\n**Examples:**\n- Individual: `5511999999999` (Brazil mobile)\n- Group: `120363047204807488@g.us`\n","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.\n\n**Formats:**\n- URL: `https://download.blender.org/durian/trailer/sintel_trailer-480p.mp4`\n- Base64: `data:video/mp4;base64,...`\n","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.\n\n**Features:**\n- One-tap copy button\n- Verification code display\n- 2FA/Authentication flows\n\n**Use Cases:**\n- Login verification\n- Password reset\n- Two-factor authentication\n- Account verification\n\n**Message Queue:** Messages are queued per recipient with FIFO ordering.\n","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.\n\n**Features:**\n- PIX QR code generation\n- Copy-paste PIX code\n- Multiple PIX key types\n\n**PIX Key Types:**\n- `CPF` - Brazilian individual taxpayer ID\n- `CNPJ` - Brazilian company taxpayer ID\n- `EMAIL` - Email address\n- `PHONE` - Phone number\n- `EVP` - Random PIX key (UUID format)\n\n**Message Queue:** Messages are queued per recipient with FIFO ordering.\n","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.\n\n**Features:**\n- Multiple swipeable cards with media\n- Action buttons per card (1-3)\n- Optional card type selection\n\n**Limits:**\n- Cards: 1-10 per carousel\n- Buttons per card: 1-3\n- Body text: max 1024 chars per card\n\n**Card Types:**\n- HSCROLL_CARDS: Horizontal scrolling cards (default)\n- ALBUM_IMAGE: Image album format\n\n**Use Cases:**\n- Product catalogs\n- Image galleries\n- Multi-option presentations\n- Tutorial sequences\n\n**Message Queue:** Messages are queued per recipient with FIFO ordering.\n","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.\nThis is the main message that appears before the carousel cards.\n","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.\n\n**Features:**\n- Send calendar events to groups\n- Support for location and call links\n- Event cancellation support\n","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:\n- `going` - Confirm attendance\n- `not_going` - Decline invitation\n- `maybe` - Tentative response\n","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.\n\n**GIF Format**: Accepts URL (http/https) or base64 data URI (data:image/gif;base64,...).\n\n**Key Features**:\n- Animated GIFs supported\n- Optional caption/text\n- Reply to messages via messageId\n- Schedule delivery with delayMessage or scheduledFor (ISO 8601)\n- Show typing indicator with delayTyping (1-15s)\n- View-once messages with viewOnce flag\n- Ephemeral messages with duration (0, 86400, 604800, 7776000)\n- Mention users (@mentions)\n- Mention groups/communities\n- Mention all participants (@everyone)\n- Private reply in groups\n\n**Message Queue**: Messages are queued per recipient with FIFO ordering.\n\n**WhatsApp Compatibility**: Uses whatsmeow library with full WhatsApp Web protocol support.\n","properties":{"caption":{"description":"Optional text caption for the GIF.\nSupports @mentions via mentioned/groupMentioned arrays.\n","example":"Check this out! 🎉","type":["string","null"]},"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"delayTyping":{"description":"Optional typing indicator duration in seconds (1-15 seconds).\nShows \"typing...\" to recipient before message is sent.\n","example":2,"maximum":15,"minimum":1,"type":["integer","null"]},"duration":{"description":"Optional ephemeral message duration (view-once timer).\n\n**Values**:\n- `0`: Permanent (default)\n- `86400`: 24 hours (1 day)\n- `604800`: 7 days (1 week)\n- `7776000`: 90 days (3 months)\n","enum":[0,86400,604800,7776000],"example":0,"type":["integer","null"]},"gif":{"description":"GIF file URL or base64 data URI.\n\n**Supported Formats**:\n- URL: `https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDd2MXRxbTN1NjN5cXBqYjZ0c2swY3EyNmRxaGJxODRnOGxqcjR2MyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3o7abKhOpu0NwenH3O/giphy.gif`\n- Base64: `data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==`\n\n**Requirements**:\n- Format: GIF (animated or static)\n- Max size: 16MB recommended\n- Aspect ratio: Any (auto-adjusted by WhatsApp)\n","example":"https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExcDd2MXRxbTN1NjN5cXBqYjZ0c2swY3EyNmRxaGJxODRnOGxqcjR2MyZlcD12MV9pbnRlcm5hbF9naWZfYnlfaWQmY3Q9Zw/3o7abKhOpu0NwenH3O/giphy.gif","type":"string"},"groupMentioned":{"description":"Optional array of groups/communities to mention.\nUsed for cross-community mentions and notifications.\n","items":{"$ref":"#/components/schemas/GroupMention"},"type":["array","null"]},"mentioned":{"description":"Optional array of phone numbers to mention (@mention).\nUsers will be notified and text will show @mentions.\n","items":{"example":"5511888888888","type":["string","null"]},"type":"array"},"mentionedAll":{"default":false,"description":"Mention all participants in group (@everyone).\nOnly works in groups where user has admin permissions.\n","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).\n\n**Examples**:\n- Individual: `5511999999999` (Brazil mobile)\n- Group: `120363047204807488@g.us`\n- Community: `123456789@newsletter`\n","example":"5511999999999","type":"string"},"privateAnswer":{"default":false,"description":"Send message as private reply in group context.\nOnly recipient will see the message, others see \"private reply\".\n","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).\nRecipient can only view the GIF once.\n","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.\n\n**Status Broadcasting**: Image is automatically broadcast to all contacts\nwho can view your status based on your privacy settings.\n\n**Key Features**:\n- Image URL or base64 data URI support\n- Optional caption/text overlay\n- Automatic thumbnail generation\n- Optional custom message ID for tracking\n\n**Supported Formats**: JPEG, PNG, WebP, GIF (static)\n","properties":{"caption":{"description":"Optional caption/text to display with the image.\nSupports emoji and unicode characters.\n","example":"Check out this view! 🌅","type":["string","null"]},"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"image":{"description":"Image URL (http/https) or base64 data URI.\n\n**Examples**:\n- URL: `https://example.com/image.jpg`\n- Base64: `data:image/jpeg;base64,/9j/4AAQSkZ...`\n","example":"https://picsum.photos/600/400.jpg","type":"string"},"messageId":{"description":"Optional custom message ID for tracking.\nIf not provided, WhatsApp generates one automatically.\n","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.\n\n**Features:**\n- Custom link preview title and description\n- Custom preview image\n- Optional message text before the link\n- Reply-to support\n","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.\n\n**Features:**\n- Multiple sections with rows\n- Expandable list menu\n- Selection callbacks\n\n**Limits:**\n- Max 10 sections\n- Max 10 rows per section\n- Title: max 60 chars\n- Message: max 4096 chars\n- Footer: max 60 chars\n- Button label: max 20 chars\n- Section title: max 24 chars\n- Row title: max 24 chars\n- Row description: max 72 chars\n\n**Message Queue:** Messages are queued per recipient with FIFO ordering.\n","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.\n\n**PTV Format**: Circular video notes displayed similarly to voice notes but with video content.\n\n**Key Features**:\n- Circular video notes (like voice notes with video)\n- Video URL or base64 data URI support\n- Optional caption/text\n- Reply to messages via messageId\n- Schedule delivery with delayMessage or scheduledFor (ISO 8601)\n- Show typing indicator with delayTyping (1-15s)\n- Ephemeral messages with duration (0, 86400, 604800, 7776000)\n- Mention users (@mentions)\n- Mention groups/communities\n- Mention all participants (@everyone)\n- Private reply in groups\n\n**Message Queue**: Messages are queued per recipient with FIFO ordering.\n\n**WhatsApp Compatibility**: Uses whatsmeow library with full WhatsApp Web protocol support.\n","properties":{"caption":{"description":"Optional text caption for the PTV video.\nSupports @mentions via mentioned/groupMentioned arrays.\n","example":"Check out this video note!","type":["string","null"]},"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"delayTyping":{"description":"Optional typing indicator duration in seconds (1-15 seconds).\nShows \"recording...\" to recipient before message is sent.\n","example":2,"maximum":15,"minimum":1,"type":["integer","null"]},"duration":{"description":"Optional ephemeral message duration (view-once timer).\n\n**Values**:\n- `0`: Permanent (default)\n- `86400`: 24 hours (1 day)\n- `604800`: 7 days (1 week)\n- `7776000`: 90 days (3 months)\n","enum":[0,86400,604800,7776000],"example":0,"type":["integer","null"]},"groupMentioned":{"description":"Optional array of groups/communities to mention.\nUsed for cross-community mentions and notifications.\n","items":{"$ref":"#/components/schemas/GroupMention"},"type":["array","null"]},"mentioned":{"description":"Optional array of phone numbers to mention (@mention).\nUsers will be notified and text will show @mentions.\n","items":{"example":"5511888888888","type":["string","null"]},"type":"array"},"mentionedAll":{"default":false,"description":"Mention all participants in group (@everyone).\nOnly works in groups where user has admin permissions.\n","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).\n\n**Examples**:\n- Individual: `5511999999999` (Brazil mobile)\n- Group: `120363047204807488@g.us`\n- Community: `123456789@newsletter`\n","example":"5511999999999","type":"string"},"privateAnswer":{"default":false,"description":"Send message as private reply in group context.\nOnly recipient will see the message, others see \"private reply\".\n","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.\n\n**Supported Formats**:\n- URL: `https://example.com/video.mp4`\n- Base64: `data:video/mp4;base64,AAAAIGZ0eXBpc29t...`\n\n**Requirements**:\n- Format: MP4, 3GP, MOV (auto-converted if needed)\n- Max duration: 60 seconds recommended for PTV\n- Circular display in WhatsApp\n","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.\nAfter viewing, the message disappears from the chat.\n","example":false,"type":"boolean"}},"required":["phone","video"],"type":"object"},"SendPollRequest":{"additionalProperties":false,"description":"Request body for sending poll messages.\n\n**Features:**\n- Create polls with 2-12 options\n- Single or multiple choice selection\n- Optional reply-to support\n- Typing indicator and delay support\n","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":"👍","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.\n\n**Sticker Format**: Accepts URL (http/https) or base64 data URI (data:image/webp;base64,...).\n\n**Key Features**:\n- Animated stickers supported (WebP format)\n- No caption support (stickers are sent without text)\n- Reply to messages via messageId\n- Schedule delivery with delayMessage or scheduledFor (ISO 8601)\n- Show typing indicator with delayTyping (1-15s)\n- Ephemeral messages with duration (0, 86400, 604800, 7776000)\n- Mention users (@mentions)\n- Mention groups/communities\n- Mention all participants (@everyone)\n- Private reply in groups\n\n**Message Queue**: Messages are queued per recipient with FIFO ordering.\n\n**WhatsApp Compatibility**: Uses whatsmeow library with full WhatsApp Web protocol support.\n","properties":{"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"delayTyping":{"description":"Optional typing indicator duration in seconds (1-15 seconds).\nShows \"typing...\" to recipient before message is sent.\n","example":2,"maximum":15,"minimum":1,"type":["integer","null"]},"duration":{"description":"Optional ephemeral message duration (view-once timer).\n\n**Values**:\n- `0`: Permanent (default)\n- `86400`: 24 hours (1 day)\n- `604800`: 7 days (1 week)\n- `7776000`: 90 days (3 months)\n","enum":[0,86400,604800,7776000],"example":0,"type":["integer","null"]},"groupMentioned":{"description":"Optional array of groups/communities to mention.\nUsed for cross-community mentions and notifications.\n","items":{"$ref":"#/components/schemas/GroupMention"},"type":["array","null"]},"mentioned":{"description":"Optional array of phone numbers to mention (@mention).\nUsers will be notified and text will show @mentions.\n","items":{"example":"5511888888888","type":["string","null"]},"type":"array"},"mentionedAll":{"default":false,"description":"Mention all participants in group (@everyone).\nOnly works in groups where user has admin permissions.\n","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).\n\n**Examples**:\n- Individual: `5511999999999` (Brazil mobile)\n- Group: `120363047204807488@g.us`\n- Community: `123456789@newsletter`\n","example":"5511999999999","type":"string"},"privateAnswer":{"default":false,"description":"Send message as private reply in group context.\nOnly recipient will see the message, others see \"private reply\".\n","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.\n\n**Supported Formats**:\n- URL: `https://www.gstatic.com/webp/gallery/1.webp`\n- Base64: `data:image/webp;base64,UklGRiQAAABXRUJQVlA4IBgAAAAwAQCdASoBAAEAAwA0JaQAA3AA/vuUAAA=`\n\n**Requirements**:\n- Format: WebP (animated or static)\n- Max size: 100KB recommended for animated, 500KB for static\n- Dimensions: 512x512 pixels recommended\n","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.\n\n**Status Broadcasting**: Text is automatically broadcast to all contacts\nwho can view your status based on your privacy settings.\n\n**Key Features**:\n- Custom background color (hex or ARGB format)\n- Multiple font styles (0-5)\n- Optional custom message ID for tracking\n- Delayed sending and scheduled delivery support (delayMessage or scheduledFor)\n\n**Note**: Unlike regular messages, status messages don't require a phone number.\nThey broadcast to status@broadcast automatically.\n","properties":{"backgroundColor":{"description":"Background color for text status.\n\n**Supported Formats**:\n- Hex: `#FF5733` (RGB)\n- ARGB: `0xFF5733FF` (with alpha)\n\n**Default**: WhatsApp default gradient\n","example":"#FF5733","type":["string","null"]},"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"font":{"description":"Font style for text status.\n\n**Font Options**:\n- 0: Default (Sans-serif)\n- 1: Serif\n- 2: Norican Script\n- 3: Bryndan Write\n- 4: Bebasneue Regular\n- 5: Oswald Heavy\n","example":0,"maximum":5,"minimum":0,"type":["integer","null"]},"messageId":{"description":"Optional custom message ID for tracking.\nIf not provided, WhatsApp generates one automatically.\n","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.\nMaximum length depends on WhatsApp limits (typically ~700 characters).\n","example":"Hello from my status! 🎉","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.\n\n**Status Broadcasting**: Video is automatically broadcast to all contacts\nwho can view your status based on your privacy settings.\n\n**Key Features**:\n- Video URL or base64 data URI support\n- Optional caption/text overlay\n- Automatic thumbnail generation\n- Optional custom message ID for tracking\n\n**Supported Formats**: MP4, 3GP, MOV, AVI\n**Duration Limit**: WhatsApp status videos are typically limited to 30 seconds\n","properties":{"caption":{"description":"Optional caption/text to display with the video.\nSupports emoji and unicode characters.\n","example":"Amazing video! 🎬","type":["string","null"]},"delayMessage":{"description":"Delay in seconds before sending. Any positive integer accepted.\nFor longer scheduling, prefer scheduledFor with an ISO 8601 timestamp.\n","example":3,"minimum":1,"type":["integer","null"]},"messageId":{"description":"Optional custom message ID for tracking.\nIf not provided, WhatsApp generates one automatically.\n","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.\n\n**Examples**:\n- URL: `https://example.com/video.mp4`\n- Base64: `data:video/mp4;base64,AAAAIGZ0eXBpc29t...`\n","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\nacross all recipients (for groups) or the single recipient (for direct messages).\n","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.\nFor groups: group JID or identifier.\n","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.\nSpecify either `messageId` for a single message or `all: true` for all pending.\n","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.\n- `sent`: Message sent to WhatsApp servers\n- `delivered`: Message delivered to participant's device\n- `read`: Message read by participant\n- `played`: Audio/video/PTT played by participant\n","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.\nReturns processed data with participant counts by status type.\n","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.\nUse format=raw to retrieve this format.\n","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.\nUseful for debugging or when exact original data is needed.\n","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"}}}}