{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"SeeZap WhatsApp Integration API","version":"1.1.0","description":"Consumer integration contract. Existing /v1 routes remain compatible. Read capabilities before use. This contract covers WhatsApp integration and its API keys; dashboard authentication, billing and administrative APIs are separate product surfaces. Source build does not imply production deployment."},"servers":[{"url":"/","description":"Current SeeZap deployment"}],"security":[{"BearerAuth":[]},{"SessionBearer":[]}],"paths":{"/v1/capabilities":{"get":{"summary":"Discover channel capabilities, feature flags, limits and retention","x-required-scopes":["capabilities:read"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/capabilities":{"get":{"summary":"Discover effective capabilities for this instance and key","x-required-scopes":["capabilities:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceCapabilities"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances":{"get":{"summary":"List authorized instances","x-required-scopes":["instances:read"],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Instance"}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create an instance","x-required-scopes":["instances:write"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"channel":{"type":"string","enum":["qr","official","mock"]}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}":{"get":{"summary":"Read instance and live status","x-required-scopes":["instances:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete instance and its stored data","x-required-scopes":["instances:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/connect":{"post":{"summary":"Request connection","x-required-scopes":["instances:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"connecting":{"type":"boolean"}},"required":["connecting"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/disconnect":{"post":{"summary":"Log out and clear pairing","x-required-scopes":["instances:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"disconnected":{"type":"boolean"}},"required":["disconnected"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/qr":{"get":{"summary":"Read current QR image (sensitive credential)","x-required-scopes":["instances:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"qr":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["status","qr"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/pairing-code":{"post":{"summary":"Request an eight-character pairing code; max 5/minute","x-required-scopes":["instances:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","maxLength":32,"description":"10–15 digits including country code; optional +, whitespace and phone punctuation. Brazilian normalized numbers require 12 or 13 digits."}},"required":["phoneNumber"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","pattern":"^[A-Z0-9]{8}$"}},"required":["code"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/cloud":{"put":{"summary":"Configure official Graph API channel (only when enabled)","x-required-scopes":["instances:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumberId":{"type":"string"},"accessToken":{"type":"string"},"wabaId":{"type":"string"}},"required":["phoneNumberId","accessToken"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-feature-flag":"FEATURE_OFFICIAL_CHANNEL"}},"/v1/conversations":{"get":{"summary":"List known conversations independent of stored messages","x-required-scopes":["conversations:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Required for a key restricted to specific instances."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096},"description":"Opaque cursor. Repeat the same filters. Conversation and new message cursors return 409 cursor_stale after synchronized state changes; discard partial collection and restart. End of pagination is not proof of WhatsApp completeness."},{"name":"order","in":"query","required":false,"schema":{"type":"string","enum":["alphabetical","whatsapp"],"default":"whatsapp"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["all","main","archived"],"default":"all"}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["individual","group","other"]}},{"name":"removed","in":"query","required":false,"schema":{"type":"string","enum":["include","exclude","only"],"default":"exclude"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","enum":["known","unknown"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"pinned","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"unread","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationPage"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/contacts":{"get":{"summary":"List observed contact identities (does not imply active conversation)","x-required-scopes":["contacts:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Required for a key restricted to specific instances."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096},"description":"Opaque cursor. Repeat the same filters. Conversation and new message cursors return 409 cursor_stale after synchronized state changes; discard partial collection and restart. End of pagination is not proof of WhatsApp completeness."},{"name":"search","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"hasMore":{"type":"boolean"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["data","hasMore","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/history":{"post":{"summary":"Request older history asynchronously; max 3/minute","x-required-scopes":["history:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Required for operation writes; optional for message sends and history requests. Reuse unchanged to retrieve prior result. Retention bounds the guarantee."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messageId":{"type":"string","minLength":1},"count":{"type":"integer","minimum":1,"maximum":100,"default":50}},"required":["messageId"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HistoryRequested"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/sync":{"get":{"summary":"Read sync progress, observed ranges, gaps and batches","x-required-scopes":["history:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096},"description":"Opaque cursor. Repeat the same filters. Conversation and new message cursors return 409 cursor_stale after synchronized state changes; discard partial collection and restart. End of pagination is not proof of WhatsApp completeness."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncStatus"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/history-requests":{"get":{"summary":"Page historical fetch requests and their outcomes","x-required-scopes":["history:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096},"description":"Opaque cursor. Repeat the same filters. Conversation and new message cursors return 409 cursor_stale after synchronized state changes; discard partial collection and restart. End of pagination is not proof of WhatsApp completeness."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HistoryRequest"}},"hasMore":{"type":"boolean"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["data","hasMore","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/diagnostics":{"get":{"summary":"Read connection, sync and delivery health","x-required-scopes":["instances:read","history:read","webhooks:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Diagnostics"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/messages":{"get":{"summary":"Page stored messages by original chronology","x-required-scopes":["messages:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Required for a key restricted to specific instances."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048}},{"name":"conversationJid","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Inclusive sentAt bound."},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Exclusive sentAt bound."},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["inbound","outbound"]}},{"name":"type","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["api","whatsapp","history"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"hasMore":{"type":"boolean"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"snapshotAt":{"type":"string","format":"date-time"},"databaseExhausted":{"type":"boolean"},"historyCompleteness":{"const":"unverified"}},"required":["data","hasMore","nextCursor","snapshotAt","databaseExhausted","historyCompleteness"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Queue a message; max 120/minute; 202 does not confirm delivery","x-required-scopes":["messages:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Required for operation writes; optional for message sends and history requests. Reuse unchanged to retrieve prior result. Retention bounds the guarantee."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInput"}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"status":{"type":"string","enum":["queued","sending","sent","delivered","read","failed","uncertain","received"]}},"required":["id","status"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-conditional-scopes":{"quotedMessageId":["messages:read"]}}},"/v1/messages/{id}/media":{"get":{"summary":"Download retained encrypted-cache attachment","x-required-scopes":["messages:read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Attachment bytes. MIME type reflects stored validated media type. Missing/expired media returns 404.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/messages/stats":{"get":{"summary":"Aggregate stored message counts by commercial calendar period","x-required-scopes":["messages:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Required for a key restricted to specific instances."},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["month","last-month","today","yesterday"],"default":"month"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"timezone":{"const":"America/Sao_Paulo"},"data":{"type":"array","items":{"type":"object","properties":{"direction":{"type":"string","enum":["inbound","outbound"]},"type":{"type":"string"},"status":{"type":"string","enum":["queued","sending","sent","delivered","read","failed","uncertain","received"]},"count":{"type":"integer"}},"required":["direction","type","status","count"],"additionalProperties":false}}},"required":["from","to","timezone","data"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}/operations":{"post":{"summary":"Perform an explicit QR action or query; max 60/minute","x-required-scopes":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":128},"description":"Required for operation writes; optional for message sends and history requests. Reuse unchanged to retrieve prior result. Retention bounds the guarantee."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationInput"}}}},"responses":{"200":{"description":"Read result or confirmed operation.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Operation"},{"$ref":"#/components/schemas/OperationReadResult"}]}}}},"202":{"description":"Persisted operation result; inspect requested/failed/uncertain, not only HTTP status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-operation-scopes":{"group.list":["groups:read"],"group.metadata":["groups:read"],"group.create":["groups:write"],"group.subject":["groups:write"],"group.description":["groups:write"],"group.participants":["groups:write"],"group.setting":["groups:write"],"group.leave":["groups:write"],"group.invite-code":["groups:read"],"group.revoke-invite":["groups:write"],"group.join":["groups:write"],"profile.picture":["contacts:read"],"profile.status":["contacts:read"],"profile.update-name":["instances:write"],"profile.update-status":["instances:write"],"profile.update-picture":["instances:write"],"profile.remove-picture":["instances:write"],"presence.update":["presence:write"],"presence.subscribe":["presence:read"],"chat.archive":["conversations:write"],"chat.pin":["conversations:write"],"chat.mute":["conversations:write"],"chat.read":["conversations:write"],"chat.disappearing":["conversations:write"],"message.react":["messages:write"],"message.edit":["messages:write"],"message.delete":["messages:write"],"message.forward":["messages:write","messages:read"],"message.read":["messages:write"],"message.star":["messages:write"],"call.reject":["instances:write"]}}},"/v1/instances/{id}/operations/{operationId}":{"get":{"summary":"Read persisted write outcome; requires corresponding resource read scope","x-required-scopes":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"operationId","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Operation"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-operation-scopes":{"group.list":["groups:read"],"group.metadata":["groups:read"],"group.create":["groups:read"],"group.subject":["groups:read"],"group.description":["groups:read"],"group.participants":["groups:read"],"group.setting":["groups:read"],"group.leave":["groups:read"],"group.invite-code":["groups:read"],"group.revoke-invite":["groups:read"],"group.join":["groups:read"],"profile.picture":["contacts:read"],"profile.status":["contacts:read"],"profile.update-name":["instances:read"],"profile.update-status":["instances:read"],"profile.update-picture":["instances:read"],"profile.remove-picture":["instances:read"],"presence.update":["presence:read"],"presence.subscribe":["presence:read"],"chat.archive":["conversations:read"],"chat.pin":["conversations:read"],"chat.mute":["conversations:read"],"chat.read":["conversations:read"],"chat.disappearing":["conversations:read"],"message.react":["messages:read"],"message.edit":["messages:read"],"message.delete":["messages:read"],"message.forward":["messages:read"],"message.read":["messages:read"],"message.star":["messages:read"],"call.reject":["instances:read"]}}},"/v1/webhooks":{"get":{"summary":"List subscriptions permitted by payload read scopes; restricted keys do not receive secrets","x-required-scopes":["webhooks:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Required for a key restricted to specific instances."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create/reactivate an identical webhook subscription","x-required-scopes":["webhooks:write"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public HTTP(S) URL; commercial production requires HTTPS."},"instanceId":{"type":"string","minLength":1},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["*","instance.status","message.inbound","message.status","message.receipt","message.own","message.history","message.updated","message.reaction","message.deleted","conversation.updated","conversation.deleted","contact.updated","contacts.snapshot","conversations.snapshot","history.sync","group.updated","presence.updated","call.updated","operation.requested","operation.updated"]},"default":["*"],"description":"* means only legacy instance.status/message.inbound/message.status. Subscribe to all other names explicitly. instance.status may include pairing QR and requires instances:write; wildcard also requires messages:read. Other events require their payload scopes.","x-event-required-scopes":{"*":["instances:write","messages:read"],"instance.status":["instances:write"],"message.inbound":["messages:read"],"message.status":["messages:read"],"message.receipt":["messages:read"],"message.own":["messages:read"],"message.history":["messages:read"],"message.updated":["messages:read"],"message.reaction":["messages:read"],"message.deleted":["messages:read"],"conversation.updated":["conversations:read"],"conversation.deleted":["conversations:read"],"contact.updated":["contacts:read"],"contacts.snapshot":["contacts:read"],"conversations.snapshot":["conversations:read"],"history.sync":["history:read"],"group.updated":["groups:read"],"presence.updated":["presence:read"],"call.updated":["instances:read"],"operation.requested":["instances:read","messages:read","conversations:read","contacts:read","history:read","groups:read","presence:read"],"operation.updated":["instances:read","messages:read","conversations:read","contacts:read","history:read","groups:read","presence:read"]}},"secret":{"type":"string","minLength":8}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{id}":{"delete":{"summary":"Delete subscription and its delivery history","x-required-scopes":["webhooks:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-deliveries":{"get":{"summary":"Recover retained event envelopes, including failed deliveries","x-required-scopes":["webhooks:read"],"parameters":[{"name":"instanceId","in":"query","required":false,"schema":{"type":"string","minLength":1},"description":"Required for a key restricted to specific instances."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4096},"description":"Opaque cursor. Repeat the same filters. Conversation and new message cursors return 409 cursor_stale after synchronized state changes; discard partial collection and restart. End of pagination is not proof of WhatsApp completeness."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","delivered","failed"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"hasMore":{"type":"boolean"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["data","hasMore","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-deliveries/{id}/retry":{"post":{"summary":"Requeue retained envelope without changing event.id","x-required-scopes":["webhooks:write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":["queued"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/api-keys":{"get":{"summary":"List integration keys (dashboard session only)","x-required-scopes":[],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"prefix":{"type":"string"},"lastUsed":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"revokedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"permissions":{"anyOf":[{"$ref":"#/components/schemas/Permissions"},{"type":"null"}]}},"required":["id","name","prefix","lastUsed","revokedAt","createdAt","permissions"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"SessionBearer":[]}]},"post":{"summary":"Create key; omitted permissions retains legacy unrestricted access","x-required-scopes":[],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"default":"default"},"permissions":{"$ref":"#/components/schemas/Permissions"}},"required":[],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1},"name":{"type":"string"},"secret":{"type":"string"},"permissions":{"anyOf":[{"$ref":"#/components/schemas/Permissions"},{"type":"null"}]}},"required":["id","name","secret","permissions"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"SessionBearer":[]}]}},"/v1/api-keys/{id}":{"delete":{"summary":"Revoke integration key (dashboard session only)","x-required-scopes":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean"}},"required":["revoked"],"additionalProperties":false}}}},"400":{"description":"Structured error (HTTP 400). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Structured error (HTTP 401). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Structured error (HTTP 402). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Structured error (HTTP 403). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error (HTTP 404). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Structured error (HTTP 409). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Structured error (HTTP 422). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error (HTTP 429). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Structured error (HTTP 500). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error (HTTP 503). Inspect error.code and error.message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"SessionBearer":[]}]}},"/v1/features":{"get":{"summary":"Read public deployment feature flags","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"monitor":{"type":"boolean"},"channels":{"type":"object","properties":{"qr":{"type":"boolean"},"official":{"type":"boolean"},"mock":{"type":"boolean"}},"required":["qr","official","mock"],"additionalProperties":false}},"required":["monitor","channels"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}}}}},"/v1/health":{"get":{"summary":"Liveness (not connection readiness)","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"version":{"type":"string"},"env":{"type":"string"},"time":{"type":"string","format":"date-time"}},"required":["ok","service","version","env","time"],"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"SeeZap API key","description":"sk_live_ key. x-required-scopes lists application-level permissions, not OAuth scopes."},"SessionBearer":{"type":"http","scheme":"bearer","bearerFormat":"SeeZap dashboard session"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"description":"Validation field errors or actionable operation-specific details; omitted when absent.","anyOf":[{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"}},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["formErrors","fieldErrors"],"additionalProperties":false},{"type":"object","additionalProperties":true,"description":"Operation-specific diagnostic details"},{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}]}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"Permissions":{"type":"object","properties":{"scopes":{"type":"array","items":{"type":"string","enum":["instances:read","instances:write","messages:read","messages:write","conversations:read","conversations:write","contacts:read","groups:read","groups:write","presence:read","presence:write","history:read","history:write","webhooks:read","webhooks:write","capabilities:read"]},"maxItems":16},"instanceIds":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":100},{"type":"null"}]}},"required":["scopes","instanceIds"],"additionalProperties":false},"Instance":{"type":"object","properties":{"id":{"type":"string","minLength":1},"accountId":{"type":"string","minLength":1},"name":{"type":"string"},"channel":{"type":"string","enum":["qr","official","mock"]},"status":{"type":"string","enum":["created","connecting","connected","disconnected","banned"]},"phoneNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"desiredConnected":{"type":"boolean"},"lastQr":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastConnected":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"liveStatus":{"type":"string"},"pairing":{"type":"object","properties":{"state":{"type":"string","enum":["available","confirming","paired"]},"canGenerateCode":{"type":"boolean"}},"required":["state","canGenerateCode"],"additionalProperties":false}},"required":["id","accountId","name","channel","status","createdAt","updatedAt"],"additionalProperties":true},"MessageKey":{"type":"object","properties":{"id":{"type":"string","minLength":1},"remoteJid":{"type":"string"},"fromMe":{"type":"boolean"},"participant":{"type":"string"}},"required":["id","remoteJid","fromMe"],"additionalProperties":false},"Message":{"type":"object","properties":{"id":{"type":"string","minLength":1},"accountId":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"senderJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"participantJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"senderName":{"anyOf":[{"type":"string"},{"type":"null"}]},"senderPhone":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationName":{"anyOf":[{"type":"string"},{"type":"null"}]},"conversationPhone":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["inbound","outbound"]},"fromMe":{"type":"boolean"},"isGroup":{"type":"boolean"},"status":{"type":"string","enum":["queued","sending","sent","delivered","read","failed","uncertain","received"]},"type":{"type":"string"},"source":{"type":"string","enum":["api","whatsapp","history"]},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"toNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"sentAt":{"type":"string","format":"date-time"},"originalTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"receivedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"rawKey":{"anyOf":[{"$ref":"#/components/schemas/ProviderPayload"},{"type":"null"}]},"mediaUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"mediaMime":{"anyOf":[{"type":"string"},{"type":"null"}]},"mediaFilename":{"anyOf":[{"type":"string"},{"type":"null"}]},"mediaExpiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"payload":{"anyOf":[{"$ref":"#/components/schemas/ProviderPayload"},{"type":"null"}]},"dedupKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"usageCounted":{"type":"boolean"}},"required":["id","instanceId","direction","type","status","source","sentAt","createdAt"],"additionalProperties":true},"ProviderPayload":{"type":"object","additionalProperties":true,"description":"Preserved channel payload. Channel-specific fields are intentionally opaque and are not accepted as arbitrary executable operations."},"SendInput":{"type":"object","properties":{"to":{"type":"string","minLength":1,"maxLength":256},"type":{"type":"string","enum":["text","image","audio","video","document","sticker","location","contact","poll"]},"text":{"type":"string","minLength":1,"maxLength":65536},"mediaUrl":{"type":"string","format":"uri","maxLength":4096},"caption":{"type":"string","maxLength":4096},"filename":{"type":"string","minLength":1,"maxLength":255},"mimetype":{"type":"string","maxLength":128,"pattern":"^[\\w.+-]+\\/[\\w.+-]+(?:;[^\\r\\n]*)?$"},"ptt":{"type":"boolean"},"gifPlayback":{"type":"boolean"},"mentions":{"type":"array","items":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"maxItems":100},"quotedMessageId":{"type":"string","minLength":1,"maxLength":128},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"name":{"type":"string","minLength":1,"maxLength":255},"address":{"type":"string","maxLength":1024},"displayName":{"type":"string","minLength":1,"maxLength":255},"vcard":{"type":"string","minLength":1,"maxLength":16384},"values":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":2,"maxItems":12},"selectableCount":{"type":"integer","minimum":1,"maximum":12},"instanceId":{"type":"string","minLength":1}},"required":["to","instanceId"],"additionalProperties":true,"description":"QR supports every listed type. Official and mock accept only text/image/audio/video/document without QR-only options. Default type is text. Provider format limits apply. Mentions only on text/image/video/poll; unique poll values; selectableCount cannot exceed values.length; vCard must include BEGIN:VCARD and END:VCARD.","allOf":[{"if":{"properties":{"type":{"const":"text"}}},"then":{"required":["text"]}},{"if":{"required":["type"],"properties":{"type":{"enum":["image","audio","video","document","sticker"]}}},"then":{"required":["mediaUrl"]}},{"if":{"required":["type"],"properties":{"type":{"enum":["location"]}}},"then":{"required":["latitude","longitude"]}},{"if":{"required":["type"],"properties":{"type":{"enum":["contact"]}}},"then":{"required":["displayName","vcard"]}},{"if":{"required":["type"],"properties":{"type":{"enum":["poll"]}}},"then":{"required":["name","values"]}}]},"ContactIdentity":{"type":"object","properties":{"jid":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"pushName":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"lid":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneJid":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["jid","name","pushName","phoneNumber","lid","phoneJid"],"additionalProperties":false},"Contact":{"type":"object","properties":{"instanceId":{"type":"string","minLength":1},"jid":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"pushName":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"lid":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"isGroup":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}},"required":["instanceId","jid","name","pushName","phoneNumber","lid","phoneJid","avatarUrl","isGroup","updatedAt"],"additionalProperties":false},"LastMessage":{"type":"object","properties":{"id":{"type":"string","minLength":1},"externalId":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"type":"string"},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["inbound","outbound"]},"sentAt":{"type":"string","format":"date-time"},"originalTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"source":{"type":"string","enum":["api","whatsapp","history"]},"deletedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"editedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","externalId","type","text","direction","sentAt","originalTimestamp","source","deletedAt","editedAt"],"additionalProperties":false},"Conversation":{"type":"object","properties":{"id":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"jid":{"type":"string"},"type":{"type":"string","enum":["individual","group","other"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pinned":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pinnedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"pinPosition":{"anyOf":[{"type":"integer"},{"type":"null"}]},"pinPositionSource":{"anyOf":[{"type":"string","enum":["derived_from_pin_timestamp"]},{"type":"null"}]},"unreadCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"markedUnread":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"muteUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"readOnly":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"removed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"removedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"stateSource":{"type":"string"},"stateObservedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"contact":{"anyOf":[{"$ref":"#/components/schemas/ContactIdentity"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessage":{"anyOf":[{"$ref":"#/components/schemas/LastMessage"},{"type":"null"}]},"visibility":{"type":"string","enum":["removed","known","unverified"]}},"required":["id","instanceId","jid","type","name","archived","pinned","pinnedAt","pinPosition","pinPositionSource","unreadCount","markedUnread","muteUntil","readOnly","removed","removedAt","stateSource","stateObservedAt","lastActivityAt","lastMessageId","lastMessageAt","createdAt","updatedAt","contact","avatarUrl","lastMessage","visibility"],"additionalProperties":false},"ConversationPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"hasMore":{"type":"boolean"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"ordering":{"type":"object","properties":{"mode":{"type":"string","enum":["alphabetical","whatsapp"]},"exactWhatsAppOrder":{"const":false},"reason":{"type":"string"},"paginationConsistency":{"type":"string"}},"required":["mode","exactWhatsAppOrder","reason"],"additionalProperties":false},"historyCompleteness":{"const":"unverified"}},"required":["data","hasMore","nextCursor","ordering","historyCompleteness"],"additionalProperties":false},"HistoryBatch":{"type":"object","properties":{"id":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"state":{"type":"string","enum":["receiving","received","partial","failed","interrupted"]},"progress":{"anyOf":[{"type":"integer"},{"type":"null"}]},"syncType":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerRequestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"isLatest":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"receivedMessages":{"type":"integer"},"processedMessages":{"type":"integer"},"failedMessages":{"type":"integer"},"oldestTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"newestTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"startedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completeness":{"const":"unverified"},"rangeMeaning":{"const":"observed_messages_only"},"unprocessedMessages":{"type":"integer"}},"required":["id","instanceId","state","progress","syncType","providerRequestId","isLatest","receivedMessages","processedMessages","failedMessages","oldestTimestamp","newestTimestamp","error","startedAt","updatedAt","completeness"],"additionalProperties":false},"HistoryRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"messageId":{"type":"string","minLength":1},"count":{"type":"integer"},"idempotencyKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"providerRequestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string","enum":["requested","dispatching","accepted","failed","uncertain"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","instanceId","messageId","count","idempotencyKey","providerRequestId","state","error","createdAt","updatedAt"],"additionalProperties":false},"HistoryRequested":{"type":"object","properties":{"id":{"type":"string","minLength":1},"requestId":{"anyOf":[{"type":"string"},{"type":"null"}]},"requested":{"type":"boolean"},"state":{"type":"string","enum":["requested","dispatching","accepted","failed","uncertain"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"historyCompleteness":{"const":"unverified"},"message":{"type":"string"}},"required":["id","requestId","requested","state","error","historyCompleteness","message"],"additionalProperties":false},"SyncStatus":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HistoryBatch"}},"hasMore":{"type":"boolean"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string","enum":["not_observed","receiving","received","partial","failed","interrupted"]},"progress":{"anyOf":[{"type":"integer"},{"type":"null"}]},"connection":{"type":"string"},"completeness":{"const":"unverified"},"storedMessages":{"type":"integer"},"observedMessageRange":{"type":"object","properties":{"from":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"to":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"contiguous":{"const":false}},"required":["from","to","contiguous"],"additionalProperties":false},"knownFailures":{"type":"integer"},"gaps":{"type":"object","properties":{"verified":{"const":false},"reason":{"type":"string"}},"required":["verified","reason"],"additionalProperties":false},"paginationMeaning":{"type":"string"}},"required":["data","hasMore","nextCursor","state","progress","connection","completeness","storedMessages","observedMessageRange","knownFailures","gaps","paginationMeaning"],"additionalProperties":false},"OperationInput":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"group.list"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.metadata"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.create"},"subject":{"type":"string","minLength":1,"maxLength":100},"participants":{"type":"array","items":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"minItems":1,"maxItems":50}},"required":["kind","subject","participants"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.subject"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"subject":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","jid","subject"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.description"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"description":{"type":"string","maxLength":2048}},"required":["kind","jid","description"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.participants"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"participants":{"type":"array","items":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"minItems":1,"maxItems":50},"action":{"type":"string","enum":["add","remove","promote","demote"]}},"required":["kind","jid","participants","action"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.setting"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"setting":{"type":"string","enum":["announcement","not_announcement","locked","unlocked"]}},"required":["kind","jid","setting"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.leave"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.invite-code"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.revoke-invite"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group.join"},"code":{"type":"string","minLength":10,"maxLength":128,"pattern":"^[a-zA-Z0-9_-]+$"}},"required":["kind","code"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"profile.picture"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"size":{"type":"string","enum":["preview","image"]}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"profile.status"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"profile.update-name"},"name":{"type":"string","minLength":1,"maxLength":100}},"required":["kind","name"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"profile.update-status"},"status":{"type":"string","maxLength":139}},"required":["kind","status"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"profile.update-picture"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"mediaUrl":{"type":"string","format":"uri","maxLength":4096}},"required":["kind","mediaUrl"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"profile.remove-picture"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"presence.update"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"presence":{"type":"string","enum":["available","unavailable","composing","recording","paused"]}},"required":["kind","presence"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"presence.subscribe"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","jid"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"chat.archive"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"archive":{"type":"boolean"},"lastMessages":{"type":"array","items":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"remoteJid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"fromMe":{"type":"boolean"},"participant":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["id","remoteJid","fromMe"],"additionalProperties":false},"timestamp":{"type":"integer","exclusiveMinimum":0,"maximum":9999999999}},"required":["key","timestamp"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["kind","jid","archive","lastMessages"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"chat.pin"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"pin":{"type":"boolean"}},"required":["kind","jid","pin"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"chat.mute"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"until":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["kind","jid","until"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"chat.read"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"read":{"type":"boolean"},"lastMessages":{"type":"array","items":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":256},"remoteJid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"fromMe":{"type":"boolean"},"participant":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["id","remoteJid","fromMe"],"additionalProperties":false},"timestamp":{"type":"integer","exclusiveMinimum":0,"maximum":9999999999}},"required":["key","timestamp"],"additionalProperties":false},"minItems":1,"maxItems":50}},"required":["kind","jid","read","lastMessages"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"chat.disappearing"},"jid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"},"seconds":{"anyOf":[{"type":"number","const":0},{"type":"number","const":86400},{"type":"number","const":604800},{"type":"number","const":7776000}]}},"required":["kind","jid","seconds"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"message.react"},"messageId":{"type":"string","minLength":1,"maxLength":128},"text":{"type":"string","maxLength":32}},"required":["kind","messageId","text"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"message.edit"},"messageId":{"type":"string","minLength":1,"maxLength":128},"text":{"type":"string","minLength":1,"maxLength":65536}},"required":["kind","messageId","text"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"message.delete"},"messageId":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","messageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"message.forward"},"messageId":{"type":"string","minLength":1,"maxLength":128},"to":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","messageId","to"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"message.read"},"messageId":{"type":"string","minLength":1,"maxLength":128}},"required":["kind","messageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"message.star"},"messageId":{"type":"string","minLength":1,"maxLength":128},"star":{"type":"boolean"}},"required":["kind","messageId","star"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"call.reject"},"callId":{"type":"string","minLength":1,"maxLength":256},"callerJid":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[^\\s@]+@(s\\.whatsapp\\.net|lid|g\\.us)$"}},"required":["kind","callId","callerJid"],"additionalProperties":false}],"discriminator":{"propertyName":"kind"},"description":"QR only. Strict discriminated request. Writes require Idempotency-Key. See x-operation-scopes for per-kind permissions. lastMessages timestamps are Unix seconds; mute until is Unix milliseconds."},"Operation":{"type":"object","properties":{"id":{"type":"string","minLength":1},"accountId":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"kind":{"type":"string"},"idempotencyKey":{"type":"string"},"request":{"anyOf":[{"$ref":"#/components/schemas/OperationInput"},{"type":"object","properties":{"expired":{"const":true},"fingerprint":{"type":"string"}},"required":["expired","fingerprint"],"additionalProperties":false}]},"status":{"type":"string","enum":["requested","confirmed","failed","uncertain"]},"result":{"anyOf":[{"$ref":"#/components/schemas/OperationData"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]},"requestedAt":{"type":"string","format":"date-time"},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"payloadExpired":{"type":"boolean"}},"required":["id","accountId","instanceId","kind","idempotencyKey","request","status","result","error","requestedAt","completedAt","payloadExpired"],"additionalProperties":false},"GroupParticipant":{"type":"object","properties":{"id":{"type":"string"},"admin":{"anyOf":[{"type":"string","enum":["admin","superadmin"]},{"type":"null"}]},"lid":{"type":"string"},"phoneNumber":{"type":"string"}},"required":["id"],"additionalProperties":true},"GroupMetadata":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"owner":{"type":"string"},"subjectOwner":{"type":"string"},"subjectTime":{"type":"integer"},"creation":{"type":"integer"},"desc":{"type":"string"},"descId":{"type":"string"},"size":{"type":"integer"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/GroupParticipant"}},"announce":{"type":"boolean"},"restrict":{"type":"boolean"},"ephemeralDuration":{"type":"integer"},"isCommunity":{"type":"boolean"},"linkedParent":{"type":"string"}},"required":["id","subject","participants"],"additionalProperties":true},"OperationData":{"description":"Result depends on kind: groups metadata/map, profile query or per-participant results. Protocol extensions may add metadata fields.","anyOf":[{"$ref":"#/components/schemas/GroupMetadata"},{"type":"array","items":{"$ref":"#/components/schemas/GroupMetadata"}},{"type":"object","additionalProperties":{"$ref":"#/components/schemas/GroupMetadata"}},{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"jid":{"type":"string"},"content":{"$ref":"#/components/schemas/ProviderPayload"}},"required":["status","jid"],"additionalProperties":true}},{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"setAt":{"type":"string","format":"date-time"},"code":{"anyOf":[{"type":"string"},{"type":"null"}]},"jid":{"anyOf":[{"type":"string"},{"type":"null"}]},"externalId":{"type":"string"},"expired":{"type":"boolean"}},"required":[],"additionalProperties":true},{"type":"string"}]},"OperationReadResult":{"type":"object","properties":{"status":{"type":"string","enum":["requested","confirmed","failed"]},"data":{"$ref":"#/components/schemas/OperationData"}},"required":["status"],"additionalProperties":false},"EventEnvelope":{"type":"object","properties":{"id":{"type":"string","pattern":"^evt_"},"event":{"type":"string","enum":["instance.status","message.inbound","message.status","message.receipt","message.own","message.history","message.updated","message.reaction","message.deleted","conversation.updated","conversation.deleted","contact.updated","contacts.snapshot","conversations.snapshot","history.sync","group.updated","presence.updated","call.updated","operation.requested","operation.updated"]},"version":{"const":1},"instanceId":{"type":"string","minLength":1},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/EventData"}},"required":["id","event","version","instanceId","createdAt","data"],"additionalProperties":false,"allOf":[{"if":{"properties":{"event":{"const":"instance.status"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/InstanceStatusEvent"}}}},{"if":{"properties":{"event":{"const":"message.inbound"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageObservedEvent"}}}},{"if":{"properties":{"event":{"const":"message.status"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageStatusEvent"}}}},{"if":{"properties":{"event":{"const":"message.receipt"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageReceiptEvent"}}}},{"if":{"properties":{"event":{"const":"message.own"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageObservedEvent"}}}},{"if":{"properties":{"event":{"const":"message.history"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageObservedEvent"}}}},{"if":{"properties":{"event":{"const":"message.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageUpdatedEvent"}}}},{"if":{"properties":{"event":{"const":"message.reaction"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageReactionEvent"}}}},{"if":{"properties":{"event":{"const":"message.deleted"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/MessageDeletedEvent"}}}},{"if":{"properties":{"event":{"const":"conversation.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/ConversationUpdatedEvent"}}}},{"if":{"properties":{"event":{"const":"conversation.deleted"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/ConversationDeletedEvent"}}}},{"if":{"properties":{"event":{"const":"contact.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/ContactEvent"}}}},{"if":{"properties":{"event":{"const":"contacts.snapshot"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/ContactsSnapshotEvent"}}}},{"if":{"properties":{"event":{"const":"conversations.snapshot"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/ConversationsSnapshotEvent"}}}},{"if":{"properties":{"event":{"const":"history.sync"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/HistoryBatch"}}}},{"if":{"properties":{"event":{"const":"group.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/GroupUpdatedEvent"}}}},{"if":{"properties":{"event":{"const":"presence.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/PresenceUpdatedEvent"}}}},{"if":{"properties":{"event":{"const":"call.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/CallUpdatedEvent"}}}},{"if":{"properties":{"event":{"const":"operation.requested"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/OperationEvent"}}}},{"if":{"properties":{"event":{"const":"operation.updated"}}},"then":{"properties":{"data":{"$ref":"#/components/schemas/OperationEvent"}}}}]},"EventData":{"anyOf":[{"$ref":"#/components/schemas/InstanceStatusEvent"},{"$ref":"#/components/schemas/MessageObservedEvent"},{"$ref":"#/components/schemas/MessageStatusEvent"},{"$ref":"#/components/schemas/MessageUpdatedEvent"},{"$ref":"#/components/schemas/MessageDeletedEvent"},{"$ref":"#/components/schemas/MessageReactionEvent"},{"$ref":"#/components/schemas/MessageReceiptEvent"},{"$ref":"#/components/schemas/ConversationUpdatedEvent"},{"$ref":"#/components/schemas/ConversationDeletedEvent"},{"$ref":"#/components/schemas/ContactEvent"},{"$ref":"#/components/schemas/ContactsSnapshotEvent"},{"$ref":"#/components/schemas/ConversationsSnapshotEvent"},{"$ref":"#/components/schemas/HistoryBatch"},{"$ref":"#/components/schemas/GroupUpdatedEvent"},{"$ref":"#/components/schemas/PresenceUpdatedEvent"},{"$ref":"#/components/schemas/CallUpdatedEvent"},{"$ref":"#/components/schemas/OperationEvent"}],"description":"Exact event-to-data mapping is enforced by EventEnvelope; raw protocol content may contain channel extensions."},"Webhook":{"type":"object","properties":{"id":{"type":"string","minLength":1},"accountId":{"type":"string","minLength":1},"instanceId":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","format":"uri"},"secret":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"configKey":{"anyOf":[{"type":"string"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","accountId","instanceId","url","events","active","createdAt"],"additionalProperties":false},"Delivery":{"type":"object","properties":{"id":{"type":"string","minLength":1},"event":{"type":"string","enum":["instance.status","message.inbound","message.status","message.receipt","message.own","message.history","message.updated","message.reaction","message.deleted","conversation.updated","conversation.deleted","contact.updated","contacts.snapshot","conversations.snapshot","history.sync","group.updated","presence.updated","call.updated","operation.requested","operation.updated"]},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastStatusCode":{"anyOf":[{"type":"integer"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"envelope":{"anyOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"null"}]},"nextAttemptAt":{"type":"string","format":"date-time"}},"required":["id","event","status","attempts","lastError","lastStatusCode","createdAt","envelope"],"additionalProperties":true},"Capability":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["supported","partial","unavailable"]},"channelSupport":{"type":"string","enum":["supported","partial","unavailable"]},"available":{"type":"boolean"},"reason":{"type":"string"},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}]},"requiredScope":{"type":"string"},"requiredScopes":{"type":"array","items":{"type":"string"}},"requiresConnection":{"type":"boolean"}},"required":["id","status","channelSupport","available","reason","endpoint","requiredScope","requiredScopes","requiresConnection"],"additionalProperties":false},"CapabilityPolicy":{"type":"object","properties":{"apiVersion":{"const":"v1"},"contractVersion":{"type":"string"},"baileysVersion":{"type":"string"},"graphVersion":{"type":"string"},"retention":{"type":"object","properties":{"policy":{"const":"transit_only"},"messagesHours":{"type":"integer"},"mediaHours":{"type":"integer"},"eventsHours":{"type":"integer"},"messagesDays":{"type":"integer"},"mediaDays":{"type":"integer"},"eventsDays":{"type":"integer"},"basis":{"const":"createdAt"},"conversationMetadata":{"type":"string"},"historyCompleteness":{"const":"unverified"},"attachments":{"type":"string"}},"required":["policy","messagesHours","mediaHours","eventsHours","messagesDays","mediaDays","eventsDays","basis","conversationMetadata","historyCompleteness","attachments"],"additionalProperties":false},"limits":{"type":"object","properties":{"pageSizeMax":{"type":"integer"},"mediaBytesMax":{"type":"integer"},"sendRequestsPerMinute":{"type":"integer"},"historyRequestsPerMinute":{"type":"integer"},"historyBatchMax":{"type":"integer"},"pairingRequestsPerMinute":{"type":"integer"},"idempotencyKeyMinLength":{"type":"integer"},"idempotencyKeyMaxLength":{"type":"integer"},"webhookAttempts":{"type":"integer"},"webhookRetryWindowHours":{"type":"integer"}},"required":["pageSizeMax","mediaBytesMax","sendRequestsPerMinute","historyRequestsPerMinute","historyBatchMax","pairingRequestsPerMinute","idempotencyKeyMinLength","idempotencyKeyMaxLength","webhookAttempts","webhookRetryWindowHours"],"additionalProperties":false},"events":{"type":"array","items":{"type":"string","enum":["instance.status","message.inbound","message.status","message.receipt","message.own","message.history","message.updated","message.reaction","message.deleted","conversation.updated","conversation.deleted","contact.updated","contacts.snapshot","conversations.snapshot","history.sync","group.updated","presence.updated","call.updated","operation.requested","operation.updated"]}},"scopes":{"type":"array","items":{"type":"string","enum":["instances:read","instances:write","messages:read","messages:write","conversations:read","conversations:write","contacts:read","groups:read","groups:write","presence:read","presence:write","history:read","history:write","webhooks:read","webhooks:write","capabilities:read"]}}},"required":["apiVersion","contractVersion","baileysVersion","graphVersion","retention","limits","events","scopes"],"additionalProperties":true},"Capabilities":{"allOf":[{"$ref":"#/components/schemas/CapabilityPolicy"},{"type":"object","properties":{"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["qr","official","mock"]},"enabled":{"type":"boolean"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}}},"required":["channel","enabled","capabilities"],"additionalProperties":false}}},"required":["channels"],"additionalProperties":true}]},"InstanceCapabilities":{"allOf":[{"$ref":"#/components/schemas/CapabilityPolicy"},{"type":"object","properties":{"instanceId":{"type":"string","minLength":1},"channel":{"type":"string","enum":["qr","official","mock"]},"enabled":{"type":"boolean"},"connection":{"type":"string"},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}}},"required":["instanceId","channel","enabled","connection","capabilities"],"additionalProperties":true}]},"Diagnostics":{"type":"object","properties":{"instanceId":{"type":"string","minLength":1},"observedAt":{"type":"string","format":"date-time"},"connection":{"type":"object","properties":{"channel":{"type":"string"},"persistedStatus":{"type":"string"},"liveStatus":{"type":"string"},"desiredConnected":{"type":"boolean"},"lastConnected":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastError":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["channel","persistedStatus","liveStatus","desiredConnected","lastConnected","lastError"],"additionalProperties":false},"synchronization":{"type":"object","properties":{"completeness":{"const":"unverified"},"detailUrl":{"type":"string"},"storedMessages":{"type":"integer"},"earliestStoredTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"latestStoredTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"observedBoundsAreContinuousCoverage":{"const":false}},"required":["completeness","detailUrl","storedMessages","earliestStoredTimestamp","latestStoredTimestamp","observedBoundsAreContinuousCoverage"],"additionalProperties":false},"events":{"type":"object","properties":{"pending":{"type":"integer"},"exhausted":{"type":"integer"},"oldestPendingAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"scope":{"type":"string"},"replayUrl":{"type":"string"},"workersRunning":{"type":"boolean"},"lastDispatchAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["pending","exhausted","oldestPendingAt","scope","replayUrl","workersRunning","lastDispatchAt"],"additionalProperties":false},"operations":{"type":"object","properties":{"uncertainMessages":{"type":"integer"},"automaticRetryOfUncertain":{"const":false}},"required":["uncertainMessages","automaticRetryOfUncertain"],"additionalProperties":false},"retention":{"type":"object","properties":{"messagesDays":{"type":"integer"},"mediaDays":{"type":"integer"},"webhookDeliveryDays":{"type":"integer"},"messagesHours":{"type":"integer"},"mediaHours":{"type":"integer"},"webhookDeliveryHours":{"type":"integer"},"messagesCountedFrom":{"type":"string"},"mediaCountedFrom":{"type":"string"},"availability":{"type":"string"}},"required":["messagesDays","mediaDays","webhookDeliveryDays","messagesHours","mediaHours","webhookDeliveryHours","messagesCountedFrom","mediaCountedFrom","availability"],"additionalProperties":false}},"required":["instanceId","observedAt","connection","synchronization","events","operations","retention"],"additionalProperties":false},"InstanceStatusEvent":{"type":"object","properties":{"status":{"type":"string"},"phoneNumber":{"type":"string"},"qr":{"type":"string"},"error":{"type":"string"}},"required":["status"],"additionalProperties":true},"MessageObservedEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"externalId":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"type":{"type":"string"},"text":{"type":"string"},"timestamp":{"anyOf":[{"type":"number"},{"type":"null"}]},"conversationJid":{"type":"string"},"senderJid":{"type":"string"},"participantJid":{"type":"string"},"senderName":{"type":"string"},"isGroup":{"type":"boolean"},"fromMe":{"type":"boolean"},"historical":{"type":"boolean"},"source":{"type":"string","enum":["api","whatsapp","history"]},"rawKey":{"anyOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"remoteJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromMe":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"participant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":[],"additionalProperties":true},{"type":"null"}]},"originalTimestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"receivedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"mediaUrl":{"type":"string"},"mediaExpiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"mediaError":{"type":"string"}},"required":["externalId","type"],"additionalProperties":true},"MessageStatusEvent":{"type":"object","properties":{"id":{"type":"string"},"externalId":{"type":"string"},"status":{"type":"string","enum":["queued","sending","sent","delivered","read","failed","uncertain","received"]},"source":{"type":"string"}},"required":["externalId","status"],"additionalProperties":true},"MessageUpdatedEvent":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"remoteJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromMe":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"participant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":[],"additionalProperties":true},"update":{"type":"object","properties":{"message":{"anyOf":[{"$ref":"#/components/schemas/ProviderPayload"},{"type":"null"}]},"messageStubType":{"type":"integer"},"status":{"type":"integer"}},"required":[],"additionalProperties":true}},"required":["key","update"],"additionalProperties":true},"MessageDeletedEvent":{"anyOf":[{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"remoteJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromMe":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"participant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":[],"additionalProperties":true}}},"required":["keys"],"additionalProperties":false},{"type":"object","properties":{"jid":{"type":"string"},"all":{"const":true}},"required":["jid","all"],"additionalProperties":false}]},"MessageReactionEvent":{"type":"array","items":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"remoteJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromMe":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"participant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":[],"additionalProperties":true},"reaction":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"remoteJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromMe":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"participant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":[],"additionalProperties":true},"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"senderTimestampMs":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","properties":{"low":{"type":"integer"},"high":{"type":"integer"},"unsigned":{"type":"boolean"}},"required":["low","high","unsigned"],"additionalProperties":false}],"description":"Original Baileys/protobuf numeric field; milliseconds vs seconds follows the named provider field."},"groupingKey":{"type":"string"}},"required":[],"additionalProperties":true}},"required":["key","reaction"],"additionalProperties":false}},"MessageReceiptEvent":{"type":"array","items":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}]},"remoteJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"fromMe":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"participant":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":[],"additionalProperties":true},"receipt":{"type":"object","properties":{"userJid":{"type":"string"},"receiptTimestamp":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","properties":{"low":{"type":"integer"},"high":{"type":"integer"},"unsigned":{"type":"boolean"}},"required":["low","high","unsigned"],"additionalProperties":false}],"description":"Original Baileys/protobuf numeric field; milliseconds vs seconds follows the named provider field."},"readTimestamp":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","properties":{"low":{"type":"integer"},"high":{"type":"integer"},"unsigned":{"type":"boolean"}},"required":["low","high","unsigned"],"additionalProperties":false}],"description":"Original Baileys/protobuf numeric field; milliseconds vs seconds follows the named provider field."},"playedTimestamp":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"object","properties":{"low":{"type":"integer"},"high":{"type":"integer"},"unsigned":{"type":"boolean"}},"required":["low","high","unsigned"],"additionalProperties":false}],"description":"Original Baileys/protobuf numeric field; milliseconds vs seconds follows the named provider field."},"pendingDeviceJid":{"type":"array","items":{"type":"string"}},"deliveredDeviceJid":{"type":"array","items":{"type":"string"}}},"required":[],"additionalProperties":true}},"required":["key","receipt"],"additionalProperties":false}},"ConversationUpdatedEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"jid":{"type":"string"},"type":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pinned":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"pinnedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"unreadCount":{"anyOf":[{"type":"integer"},{"type":"null"}]},"markedUnread":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"muteUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"readOnly":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"removed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"removedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"stateSource":{"type":"string"},"stateObservedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastActivityAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastMessageId":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastMessageAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"source":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["instanceId","jid"],"additionalProperties":true},"ConversationDeletedEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"instanceId":{"type":"string","minLength":1},"jid":{"type":"string"},"removed":{"const":true},"removedAt":{"type":"string","format":"date-time"}},"required":["jid","removed","removedAt"],"additionalProperties":false},"ContactEvent":{"type":"object","properties":{"instanceId":{"type":"string","minLength":1},"jid":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"pushName":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneNumber":{"anyOf":[{"type":"string"},{"type":"null"}]},"lid":{"anyOf":[{"type":"string"},{"type":"null"}]},"phoneJid":{"anyOf":[{"type":"string"},{"type":"null"}]},"avatarUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"isGroup":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"},"source":{"type":"string"}},"required":["instanceId","jid","isGroup","updatedAt"],"additionalProperties":false},"ContactsSnapshotEvent":{"type":"object","properties":{"source":{"type":"string"},"total":{"type":"integer"},"offset":{"type":"integer"},"count":{"type":"integer"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactEvent"}}},"required":["source","total","offset","count","contacts"],"additionalProperties":false},"ConversationsSnapshotEvent":{"type":"object","properties":{"source":{"type":"string"},"total":{"type":"integer"},"offset":{"type":"integer"},"count":{"type":"integer"},"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationUpdatedEvent"}}},"required":["source","total","offset","count","conversations"],"additionalProperties":false},"GroupUpdatedEvent":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["groups.upsert","groups.update"]},"groups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/GroupParticipant"}},"desc":{"type":"string"}},"required":["id"],"additionalProperties":true}}},"required":["source","groups"],"additionalProperties":false},{"type":"object","properties":{"source":{"const":"group-participants.update"},"id":{"type":"string"},"author":{"type":"string"},"participants":{"type":"array","items":{"type":"string"}},"action":{"type":"string","enum":["add","remove","promote","demote","modify"]}},"required":["source","id","participants","action"],"additionalProperties":true}]},"PresenceUpdatedEvent":{"type":"object","properties":{"id":{"type":"string"},"presences":{"type":"object","additionalProperties":{"type":"object","properties":{"lastKnownPresence":{"type":"string","enum":["unavailable","available","composing","recording","paused"]},"lastSeen":{"type":"integer"}},"required":["lastKnownPresence"],"additionalProperties":true}}},"required":["id","presences"],"additionalProperties":false},"CallUpdatedEvent":{"type":"array","items":{"type":"object","properties":{"chatId":{"type":"string"},"from":{"type":"string"},"isGroup":{"type":"boolean"},"groupJid":{"type":"string"},"id":{"type":"string"},"date":{"type":"string","format":"date-time"},"isVideo":{"type":"boolean"},"status":{"type":"string","enum":["offer","ringing","timeout","reject","accept","terminate"]},"offline":{"type":"boolean"},"latencyMs":{"type":"integer"}},"required":["chatId","from","id","date","status","offline"],"additionalProperties":true}},"OperationEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1},"kind":{"type":"string"},"status":{"type":"string","enum":["requested","confirmed","failed","uncertain"]},"result":{"anyOf":[{"$ref":"#/components/schemas/OperationData"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","status"],"additionalProperties":true}}},"webhooks":{"seezapEvent":{"post":{"summary":"At-least-once delivery of a subscribed retained event","description":"Verify X-SeeZap-Signature t=<unix-milliseconds>,v1=<HMAC-SHA256(secret,t + \".\" + rawBody)> before parsing. Reject stale signatures (suggested 300 seconds), compare timing-safely, deduplicate envelope.id, persist before HTTP 2xx. Up to six attempts with exponential delays starting at 3 seconds; 10-second HTTP timeout. Manual replay keeps event.id. New events require explicit subscription; * preserves legacy three events.","security":[],"parameters":[{"name":"X-SeeZap-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-SeeZap-Event","in":"header","required":true,"schema":{"type":"string","enum":["instance.status","message.inbound","message.status","message.receipt","message.own","message.history","message.updated","message.reaction","message.deleted","conversation.updated","conversation.deleted","contact.updated","contacts.snapshot","conversations.snapshot","history.sync","group.updated","presence.updated","call.updated","operation.requested","operation.updated"]}},{"name":"X-SeeZap-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventEnvelope"}}}},"responses":{"200":{"description":"Durably received (duplicates may also return 2xx)."},"500":{"description":"Receiver failure; delivery is retried within retention and attempt limits."}}}}}}