{"openapi":"3.1.0","info":{"title":"Wathook WhatsApp API","version":"0.13.2","description":"Public integration reference for session-token WhatsApp operations and partner provisioning. Account, billing and configuration are managed in the dashboard and have no public integration endpoints. API examples do not establish real WhatsApp delivery or merchant settlement."},"servers":[{"url":"https://wathook.com"}],"tags":[{"name":"Sessions"},{"name":"Partner provisioning"},{"name":"Sending messages"},{"name":"Media"},{"name":"Chats"},{"name":"Messages and history"},{"name":"Labels"},{"name":"Groups"},{"name":"Contacts"}],"paths":{"/api/v1/sessions":{"get":{"operationId":"sessions-list","tags":["Sessions"],"summary":"Read this token's session reservation","description":"Return only the reservation bound to the session token. The response is an array with at most one item; the token cannot list another session.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nNo session selector is needed: the token fixes the scope. Invalid, expired or revoked tokens are rejected.\n\nStatus is last observed here; use GET /sessions/{sessionId}/health for live health. This endpoint does not broaden the token's permissions.","security":[{"SessionToken":[]}],"parameters":[],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"billingState":{"type":"string"},"paidUntil":{"type":"string"},"expiredAt":{"type":"null"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"}}}}}},"example":{"data":[{"id":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","name":"Support","status":"WORKING","phoneNumber":"15550001111","billingState":"paid","paidUntil":"2026-11-11T12:00:00.000Z","expiredAt":null,"createdAt":"2026-10-11T12:00:00.000Z","lastActivityAt":"2026-10-11T12:00:00.000Z"}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/health":{"get":{"operationId":"sessions-health","tags":["Sessions"],"summary":"Check live session health","description":"Check the WhatsApp service live and return safe session status with local billing metadata. healthy is true only for WORKING.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nReads the WhatsApp service directly. An existing local reservation whose service session does not exist returns HTTP 404; list responses can still show that reservation. Transport/service errors stay errors and never claim health. Other valid session states return healthy:false. Owned expired sessions remain readable; suspended accounts remain denied. Only safe session fields are returned.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"billingState":{"type":"string"},"paidUntil":{"type":"string"},"expiredAt":{"type":"null"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"},"healthy":{"type":"boolean"},"accountName":{"type":"string"}}}}},"example":{"data":{"id":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","name":"Support","status":"WORKING","phoneNumber":"15550001111","billingState":"paid","paidUntil":"2026-11-11T12:00:00.000Z","expiredAt":null,"createdAt":"2026-10-11T12:00:00.000Z","lastActivityAt":"2026-10-11T12:00:00.000Z","healthy":true,"accountName":"Support team"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/start":{"post":{"operationId":"sessions-start","tags":["Sessions"],"summary":"Start a session","description":"Request start through the session's fixed service and return its result.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nEach explicit route executes its documented service flow once. Service errors return directly; transport loss may mean the operation completed. There is no automatic retry, unknown hold or release workflow.\n\nResponses: start, stop, restart and logout return the session metadata (shown). qr returns {\"data\":{\"qr\":\"<raw QR text>\"}}; render the text as a QR code. pair returns {\"data\":{\"code\":\"ABCD-EFGH\"}}; enter it on the phone under Linked devices. Start initializes a session that has not connected yet.\n\nqr and pair need the session in SCAN_QR_CODE. The platform reads the live state first and otherwise answers at once with 409 and details {status, expected:[\"SCAN_QR_CODE\"]}: SESSION_INITIALIZING with Retry-After: 3 while STARTING; SESSION_NOT_STARTED when stopped or never started (start it first); SESSION_FAILED (restart it); SESSION_ALREADY_CONNECTED when WORKING; SESSION_PASSKEY_REQUIRED for passkey linking, which Wathook cannot complete (restart to try again with a QR code or pairing code). Right after a start, pair can meet STARTING: read the state and request again.\n\nWhatsApp's pairing window: the first QR code lasts 60 seconds and each later one 20 seconds, at most 6 codes (about 160 seconds); then the session becomes FAILED and needs a restart. Each session.patch with status SCAN_QR_CODE means a new QR code. A pairing code looks like ABCD-EFGH and works only within the same window. A QR code or pairing code is not proof that the number is linked; wait for WORKING.\n\npair: when WhatsApp refuses the number, the answer is 422 PAIRING_CODE_FAILED with details.reason (for example phone number too short). Pairing-code requests can return SESSION_BUSY while another operation is running.\n\nStarting a FAILED, PASSKEY_REQUIRED or PASSKEY_CONFIRMATION_REQUIRED session restarts its connection.\n\nlogout unlinks WhatsApp and then stops the session: two service calls, logout then stop, never retried. The answer is the session with status STOPPED and phoneNumber null; pair it again with a new QR code or pairing code. If the logout succeeded but the stop failed, the answer is still 200, with the status the WhatsApp service's logout reported (usually STARTING), phoneNumber null and stopError {code, message, details?} from the failed stop; stop the session again. A failed logout is returned as an error and no stop is sent. The service unpairs the device only for a connected (WORKING) session; for any other the logout only wipes the service's saved login, and the phone keeps listing the linked device until it is removed there.\n\nStart/restart/QR/pair require an active entitlement. Stop/logout remain available after expiry. A currently executing operation can return 409 SESSION_BUSY.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"billingState":{"type":"string"},"paidUntil":{"type":"string"},"expiredAt":{"type":"null"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"}}}}},"example":{"data":{"id":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","name":"Support","status":"STARTING","phoneNumber":"15550001111","billingState":"paid","paidUntil":"2026-11-11T12:00:00.000Z","expiredAt":null,"createdAt":"2026-10-11T12:00:00.000Z","lastActivityAt":"2026-10-11T12:00:00.000Z"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/stop":{"post":{"operationId":"sessions-stop","tags":["Sessions"],"summary":"Stop a session","description":"Request stop through the session's fixed service and return its result.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nEach explicit route executes its documented service flow once. Service errors return directly; transport loss may mean the operation completed. There is no automatic retry, unknown hold or release workflow.\n\nResponses: start, stop, restart and logout return the session metadata (shown). qr returns {\"data\":{\"qr\":\"<raw QR text>\"}}; render the text as a QR code. pair returns {\"data\":{\"code\":\"ABCD-EFGH\"}}; enter it on the phone under Linked devices. Start initializes a session that has not connected yet.\n\nqr and pair need the session in SCAN_QR_CODE. The platform reads the live state first and otherwise answers at once with 409 and details {status, expected:[\"SCAN_QR_CODE\"]}: SESSION_INITIALIZING with Retry-After: 3 while STARTING; SESSION_NOT_STARTED when stopped or never started (start it first); SESSION_FAILED (restart it); SESSION_ALREADY_CONNECTED when WORKING; SESSION_PASSKEY_REQUIRED for passkey linking, which Wathook cannot complete (restart to try again with a QR code or pairing code). Right after a start, pair can meet STARTING: read the state and request again.\n\nWhatsApp's pairing window: the first QR code lasts 60 seconds and each later one 20 seconds, at most 6 codes (about 160 seconds); then the session becomes FAILED and needs a restart. Each session.patch with status SCAN_QR_CODE means a new QR code. A pairing code looks like ABCD-EFGH and works only within the same window. A QR code or pairing code is not proof that the number is linked; wait for WORKING.\n\npair: when WhatsApp refuses the number, the answer is 422 PAIRING_CODE_FAILED with details.reason (for example phone number too short). Pairing-code requests can return SESSION_BUSY while another operation is running.\n\nStarting a FAILED, PASSKEY_REQUIRED or PASSKEY_CONFIRMATION_REQUIRED session restarts its connection.\n\nlogout unlinks WhatsApp and then stops the session: two service calls, logout then stop, never retried. The answer is the session with status STOPPED and phoneNumber null; pair it again with a new QR code or pairing code. If the logout succeeded but the stop failed, the answer is still 200, with the status the WhatsApp service's logout reported (usually STARTING), phoneNumber null and stopError {code, message, details?} from the failed stop; stop the session again. A failed logout is returned as an error and no stop is sent. The service unpairs the device only for a connected (WORKING) session; for any other the logout only wipes the service's saved login, and the phone keeps listing the linked device until it is removed there.\n\nStart/restart/QR/pair require an active entitlement. Stop/logout remain available after expiry. A currently executing operation can return 409 SESSION_BUSY.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"billingState":{"type":"string"},"paidUntil":{"type":"string"},"expiredAt":{"type":"null"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"}}}}},"example":{"data":{"id":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","name":"Support","status":"STOPPED","phoneNumber":"15550001111","billingState":"paid","paidUntil":"2026-11-11T12:00:00.000Z","expiredAt":null,"createdAt":"2026-10-11T12:00:00.000Z","lastActivityAt":"2026-10-11T12:00:00.000Z"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/restart":{"post":{"operationId":"sessions-restart","tags":["Sessions"],"summary":"Restart a session","description":"Request restart through the session's fixed service and return its result.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nEach explicit route executes its documented service flow once. Service errors return directly; transport loss may mean the operation completed. There is no automatic retry, unknown hold or release workflow.\n\nResponses: start, stop, restart and logout return the session metadata (shown). qr returns {\"data\":{\"qr\":\"<raw QR text>\"}}; render the text as a QR code. pair returns {\"data\":{\"code\":\"ABCD-EFGH\"}}; enter it on the phone under Linked devices. Start initializes a session that has not connected yet.\n\nqr and pair need the session in SCAN_QR_CODE. The platform reads the live state first and otherwise answers at once with 409 and details {status, expected:[\"SCAN_QR_CODE\"]}: SESSION_INITIALIZING with Retry-After: 3 while STARTING; SESSION_NOT_STARTED when stopped or never started (start it first); SESSION_FAILED (restart it); SESSION_ALREADY_CONNECTED when WORKING; SESSION_PASSKEY_REQUIRED for passkey linking, which Wathook cannot complete (restart to try again with a QR code or pairing code). Right after a start, pair can meet STARTING: read the state and request again.\n\nWhatsApp's pairing window: the first QR code lasts 60 seconds and each later one 20 seconds, at most 6 codes (about 160 seconds); then the session becomes FAILED and needs a restart. Each session.patch with status SCAN_QR_CODE means a new QR code. A pairing code looks like ABCD-EFGH and works only within the same window. A QR code or pairing code is not proof that the number is linked; wait for WORKING.\n\npair: when WhatsApp refuses the number, the answer is 422 PAIRING_CODE_FAILED with details.reason (for example phone number too short). Pairing-code requests can return SESSION_BUSY while another operation is running.\n\nStarting a FAILED, PASSKEY_REQUIRED or PASSKEY_CONFIRMATION_REQUIRED session restarts its connection.\n\nlogout unlinks WhatsApp and then stops the session: two service calls, logout then stop, never retried. The answer is the session with status STOPPED and phoneNumber null; pair it again with a new QR code or pairing code. If the logout succeeded but the stop failed, the answer is still 200, with the status the WhatsApp service's logout reported (usually STARTING), phoneNumber null and stopError {code, message, details?} from the failed stop; stop the session again. A failed logout is returned as an error and no stop is sent. The service unpairs the device only for a connected (WORKING) session; for any other the logout only wipes the service's saved login, and the phone keeps listing the linked device until it is removed there.\n\nStart/restart/QR/pair require an active entitlement. Stop/logout remain available after expiry. A currently executing operation can return 409 SESSION_BUSY.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"string"},"billingState":{"type":"string"},"paidUntil":{"type":"string"},"expiredAt":{"type":"null"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"}}}}},"example":{"data":{"id":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","name":"Support","status":"STARTING","phoneNumber":"15550001111","billingState":"paid","paidUntil":"2026-11-11T12:00:00.000Z","expiredAt":null,"createdAt":"2026-10-11T12:00:00.000Z","lastActivityAt":"2026-10-11T12:00:00.000Z"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/logout":{"post":{"operationId":"sessions-logout","tags":["Sessions"],"summary":"Log out a session","description":"Request logout through the session's fixed service and return its result.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nEach explicit route executes its documented service flow once. Service errors return directly; transport loss may mean the operation completed. There is no automatic retry, unknown hold or release workflow.\n\nResponses: start, stop, restart and logout return the session metadata (shown). qr returns {\"data\":{\"qr\":\"<raw QR text>\"}}; render the text as a QR code. pair returns {\"data\":{\"code\":\"ABCD-EFGH\"}}; enter it on the phone under Linked devices. Start initializes a session that has not connected yet.\n\nqr and pair need the session in SCAN_QR_CODE. The platform reads the live state first and otherwise answers at once with 409 and details {status, expected:[\"SCAN_QR_CODE\"]}: SESSION_INITIALIZING with Retry-After: 3 while STARTING; SESSION_NOT_STARTED when stopped or never started (start it first); SESSION_FAILED (restart it); SESSION_ALREADY_CONNECTED when WORKING; SESSION_PASSKEY_REQUIRED for passkey linking, which Wathook cannot complete (restart to try again with a QR code or pairing code). Right after a start, pair can meet STARTING: read the state and request again.\n\nWhatsApp's pairing window: the first QR code lasts 60 seconds and each later one 20 seconds, at most 6 codes (about 160 seconds); then the session becomes FAILED and needs a restart. Each session.patch with status SCAN_QR_CODE means a new QR code. A pairing code looks like ABCD-EFGH and works only within the same window. A QR code or pairing code is not proof that the number is linked; wait for WORKING.\n\npair: when WhatsApp refuses the number, the answer is 422 PAIRING_CODE_FAILED with details.reason (for example phone number too short). Pairing-code requests can return SESSION_BUSY while another operation is running.\n\nStarting a FAILED, PASSKEY_REQUIRED or PASSKEY_CONFIRMATION_REQUIRED session restarts its connection.\n\nlogout unlinks WhatsApp and then stops the session: two service calls, logout then stop, never retried. The answer is the session with status STOPPED and phoneNumber null; pair it again with a new QR code or pairing code. If the logout succeeded but the stop failed, the answer is still 200, with the status the WhatsApp service's logout reported (usually STARTING), phoneNumber null and stopError {code, message, details?} from the failed stop; stop the session again. A failed logout is returned as an error and no stop is sent. The service unpairs the device only for a connected (WORKING) session; for any other the logout only wipes the service's saved login, and the phone keeps listing the linked device until it is removed there.\n\nStart/restart/QR/pair require an active entitlement. Stop/logout remain available after expiry. A currently executing operation can return 409 SESSION_BUSY.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"shortId":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"phoneNumber":{"type":"null"},"billingState":{"type":"string"},"paidUntil":{"type":"string"},"expiredAt":{"type":"null"},"createdAt":{"type":"string"},"lastActivityAt":{"type":"string"}}}}},"example":{"data":{"id":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","name":"Support","status":"STOPPED","phoneNumber":null,"billingState":"paid","paidUntil":"2026-11-11T12:00:00.000Z","expiredAt":null,"createdAt":"2026-10-11T12:00:00.000Z","lastActivityAt":"2026-10-11T12:00:00.000Z"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/qr":{"get":{"operationId":"sessions-qr","tags":["Sessions"],"summary":"Read session QR","description":"Read the raw QR text from the WhatsApp service after explicitly starting the session.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nEach explicit route executes its documented service flow once. Service errors return directly; transport loss may mean the operation completed. There is no automatic retry, unknown hold or release workflow.\n\nResponses: start, stop, restart and logout return the session metadata (shown). qr returns {\"data\":{\"qr\":\"<raw QR text>\"}}; render the text as a QR code. pair returns {\"data\":{\"code\":\"ABCD-EFGH\"}}; enter it on the phone under Linked devices. Start initializes a session that has not connected yet.\n\nqr and pair need the session in SCAN_QR_CODE. The platform reads the live state first and otherwise answers at once with 409 and details {status, expected:[\"SCAN_QR_CODE\"]}: SESSION_INITIALIZING with Retry-After: 3 while STARTING; SESSION_NOT_STARTED when stopped or never started (start it first); SESSION_FAILED (restart it); SESSION_ALREADY_CONNECTED when WORKING; SESSION_PASSKEY_REQUIRED for passkey linking, which Wathook cannot complete (restart to try again with a QR code or pairing code). Right after a start, pair can meet STARTING: read the state and request again.\n\nWhatsApp's pairing window: the first QR code lasts 60 seconds and each later one 20 seconds, at most 6 codes (about 160 seconds); then the session becomes FAILED and needs a restart. Each session.patch with status SCAN_QR_CODE means a new QR code. A pairing code looks like ABCD-EFGH and works only within the same window. A QR code or pairing code is not proof that the number is linked; wait for WORKING.\n\npair: when WhatsApp refuses the number, the answer is 422 PAIRING_CODE_FAILED with details.reason (for example phone number too short). Pairing-code requests can return SESSION_BUSY while another operation is running.\n\nStarting a FAILED, PASSKEY_REQUIRED or PASSKEY_CONFIRMATION_REQUIRED session restarts its connection.\n\nlogout unlinks WhatsApp and then stops the session: two service calls, logout then stop, never retried. The answer is the session with status STOPPED and phoneNumber null; pair it again with a new QR code or pairing code. If the logout succeeded but the stop failed, the answer is still 200, with the status the WhatsApp service's logout reported (usually STARTING), phoneNumber null and stopError {code, message, details?} from the failed stop; stop the session again. A failed logout is returned as an error and no stop is sent. The service unpairs the device only for a connected (WORKING) session; for any other the logout only wipes the service's saved login, and the phone keeps listing the linked device until it is removed there.\n\nStart/restart/QR/pair require an active entitlement. Stop/logout remain available after expiry. A currently executing operation can return 409 SESSION_BUSY.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"qr":{"type":"string"}}}}},"example":{"data":{"qr":"2@EXAMPLE-QR-TEXT"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session"}},"/api/v1/sessions/{sessionId}/pair":{"post":{"operationId":"sessions-pair","tags":["Sessions"],"summary":"Request a pairing code","description":"Request a phone-number pairing code from the WhatsApp service.\n\nAuthentication and scope:\nSession token: Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing.\n\nA session Bearer token can access only its own session.\n\nEach explicit route executes its documented service flow once. Service errors return directly; transport loss may mean the operation completed. There is no automatic retry, unknown hold or release workflow.\n\nResponses: start, stop, restart and logout return the session metadata (shown). qr returns {\"data\":{\"qr\":\"<raw QR text>\"}}; render the text as a QR code. pair returns {\"data\":{\"code\":\"ABCD-EFGH\"}}; enter it on the phone under Linked devices. Start initializes a session that has not connected yet.\n\nqr and pair need the session in SCAN_QR_CODE. The platform reads the live state first and otherwise answers at once with 409 and details {status, expected:[\"SCAN_QR_CODE\"]}: SESSION_INITIALIZING with Retry-After: 3 while STARTING; SESSION_NOT_STARTED when stopped or never started (start it first); SESSION_FAILED (restart it); SESSION_ALREADY_CONNECTED when WORKING; SESSION_PASSKEY_REQUIRED for passkey linking, which Wathook cannot complete (restart to try again with a QR code or pairing code). Right after a start, pair can meet STARTING: read the state and request again.\n\nWhatsApp's pairing window: the first QR code lasts 60 seconds and each later one 20 seconds, at most 6 codes (about 160 seconds); then the session becomes FAILED and needs a restart. Each session.patch with status SCAN_QR_CODE means a new QR code. A pairing code looks like ABCD-EFGH and works only within the same window. A QR code or pairing code is not proof that the number is linked; wait for WORKING.\n\npair: when WhatsApp refuses the number, the answer is 422 PAIRING_CODE_FAILED with details.reason (for example phone number too short). Pairing-code requests can return SESSION_BUSY while another operation is running.\n\nStarting a FAILED, PASSKEY_REQUIRED or PASSKEY_CONFIRMATION_REQUIRED session restarts its connection.\n\nlogout unlinks WhatsApp and then stops the session: two service calls, logout then stop, never retried. The answer is the session with status STOPPED and phoneNumber null; pair it again with a new QR code or pairing code. If the logout succeeded but the stop failed, the answer is still 200, with the status the WhatsApp service's logout reported (usually STARTING), phoneNumber null and stopError {code, message, details?} from the failed stop; stop the session again. A failed logout is returned as an error and no stop is sent. The service unpairs the device only for a connected (WORKING) session; for any other the logout only wipes the service's saved login, and the phone keeps listing the linked device until it is removed there.\n\nStart/restart/QR/pair require an active entitlement. Stop/logout remain available after expiry. A currently executing operation can return 409 SESSION_BUSY.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"Your session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"code":{"type":"string"}}}}},"example":{"data":{"code":"ABCD-EFGH"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the WhatsApp session identified by this token. Any required sessionId must match that session; the token cannot access another session or account-wide billing."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumber":{"type":"string","pattern":"^[1-9]\\d{6,14}$"}},"required":["phoneNumber"],"additionalProperties":false},"example":{"phoneNumber":"15550001111"}}}}}},"/api/manager/sessions":{"post":{"operationId":"manager-session-create","tags":["Partner provisioning"],"summary":"Provision a session","description":"Provision a customer session. Standard partner keys require a purchased credit; the platform owner's key can omit creditId for a complimentary session with no expiry. Repeating the same requestId and payload returns the original allocation without creating another session.\n\nAuthentication and scope:\nPartner manager key: Only provisioning and deletion for this approved partner account. Standard partners require paid credit; the platform owner's key can create complimentary sessions without creditId. Keep it on your server; it grants no dashboard, owner-administration or session runtime access.\n\nRequires an approved active partner account and its Manager key. This key can only provision and delete its own partner sessions; it never grants owner administration or session runtime access.\n\nStandard partner keys require prepaid credits bought in the dashboard. Provisioning creates no checkout or charge. The first redemption starts the purchased month period. Deletion/reuse never resets that clock; only a verified dashboard paid renewal can extend the funded end date.\n\nThe platform owner's authenticated Manager key can omit creditId and send only requestId, name and optional externalCustomerId. This creates a complimentary session with paidUntil:null and creditId:null, without spending credit or starting an expiry period. Available service capacity still applies. The request cannot grant owner status or bypass capacity through extra fields.\n\nThe first successful creation returns 201 with a session token once. Save it immediately. An exact requestId replay returns 200 with the same sessionId/shortId/paidUntil/creditId and token:null; it does not reveal or rotate the token.\n\nReusing a requestId with a different payload returns 409. The same requestId cannot spend another credit, switch between complimentary and paid-credit provisioning, or create a replacement after deletion. An exact replay, including after deletion, returns its original identity and token:null; it is not a live health or renewal read. Reusing returned credit or creating another complimentary session requires a new requestId.\n\nOnly the listed fields are accepted. A supplied creditId always requires genuine paid funding, including for an owner-held key; the private credit-redemption form also remains paid. Pricing, billing mode, months, trial/Sandbox choices and owner/unlimited flags cannot be supplied through this route. The key can only provision or delete its own account's sessions; it grants no owner-administration access.\n\nUse the returned session token with the normal Session API at /api/v1 for health, start, QR/pairing and supported WhatsApp operations. Those outgoing messages still have no retry, replay or message idempotency.","security":[{"PartnerToken":[]}],"parameters":[],"responses":{"200":{"description":"The same requestId and payload were already completed. The identity is unchanged and token is null.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"shortId":{"type":"string"},"token":{"type":"null"},"paidUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"creditId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"replayed":{"type":"boolean","const":true}},"required":["sessionId","shortId","token","paidUntil","creditId","replayed"],"oneOf":[{"properties":{"paidUntil":{"type":"string","format":"date-time"},"creditId":{"type":"string","format":"uuid"}}},{"properties":{"paidUntil":{"type":"null"},"creditId":{"type":"null"}}}],"additionalProperties":false}},"additionalProperties":false},"example":{"data":{"sessionId":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","token":null,"paidUntil":"2026-11-11T12:00:00.000Z","creditId":"77777777-7777-4777-8777-777777777777","replayed":true}}}}},"201":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"shortId":{"type":"string"},"token":{"type":"string"},"paidUntil":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"creditId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"replayed":{"type":"boolean","const":false}},"required":["sessionId","shortId","token","paidUntil","creditId","replayed"],"oneOf":[{"properties":{"paidUntil":{"type":"string","format":"date-time"},"creditId":{"type":"string","format":"uuid"}}},{"properties":{"paidUntil":{"type":"null"},"creditId":{"type":"null"}}}],"additionalProperties":false}},"additionalProperties":false},"example":{"data":{"sessionId":"11111111-1111-4111-8111-111111111111","shortId":"k7m2q","token":"pc_YOUR_NEW_SESSION_TOKEN","paidUntil":"2026-11-11T12:00:00.000Z","creditId":"77777777-7777-4777-8777-777777777777","replayed":false}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Partner manager key","x-auth-scopes":{"partner":"Only provisioning and deletion for this approved partner account. Standard partners require paid credit; the platform owner's key can create complimentary sessions without creditId. Keep it on your server; it grants no dashboard, owner-administration or session runtime access."},"x-documentation-area":"partner","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"creditId":{"type":"string","format":"uuid"},"requestId":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":60},"externalCustomerId":{"type":"string","minLength":1,"maxLength":128}},"required":["requestId","name"],"additionalProperties":false},"example":{"creditId":"77777777-7777-4777-8777-777777777777","requestId":"88888888-8888-4888-8888-888888888888","name":"Support","externalCustomerId":"customer-001"}}}}}},"/api/manager/sessions/{sessionId}":{"delete":{"operationId":"manager-session-delete","tags":["Partner provisioning"],"summary":"Delete a provisioned session","description":"Delete an owned partner session and revoke its session tokens after confirmed completion. A credit-backed session returns only its unexpired funded period for later reuse.\n\nAuthentication and scope:\nPartner manager key: Only provisioning and deletion for this approved partner account. Standard partners require paid credit; the platform owner's key can create complimentary sessions without creditId. Keep it on your server; it grants no dashboard, owner-administration or session runtime access.\n\nRequires an approved active partner account and its Manager key. Another account's session is never accessible; a Manager key has no owner-administration power.\n\nThe reservation and its credit remain assigned until deletion is confirmed and recorded. A timeout or failure does not release either one or claim deletion succeeded.\n\nCredit return is not a money refund, wallet balance or new paid period. Only the remainder before the credit paidUntil is reusable; this includes verified paid renewal but never extra owner-granted time. An expired credit is unusable. A later provisioning request must use a new requestId.\n\nLegacy new/renew purchases keep their existing entitlement and no-refund rules. Deletion never invents credit for a legacy purchase. Renew the current undeleted credit-backed session through the dashboard, including during expiry grace: verified payment extends both its credit and current session. Manager keys cannot renew. An open renewal blocks deletion with RENEWAL_PENDING until payment or resolution. Any owner-granted extra time belongs only to that session and never expands the reusable credit.","security":[{"PartnerToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"An owned partner session's UUID or its 5-character short ID (shortId); both name the same session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}},"example":{"data":{"deleted":true}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Partner manager key","x-auth-scopes":{"partner":"Only provisioning and deletion for this approved partner account. Standard partners require paid credit; the platform owner's key can create complimentary sessions without creditId. Keep it on your server; it grants no dashboard, owner-administration or session runtime access."},"x-documentation-area":"partner"}},"/api/v1/whatsapp/{sessionId}/messages/text":{"post":{"operationId":"whatsapp-post-messages-text","tags":["Sending messages"],"summary":"Send a text message","description":"Send directly through this session's assigned WhatsApp service and return its result or error during the request.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nA request is sent once. Repeating a request sends another message. There is no automatic resend or permanent session hold after a failed request.\n\n201 means the service accepted the send. data contains its answer with id and sessionId; there is no platform message record or nested result ledger. Delivery and read receipts are separate events. A send timeout returns 504 SERVICE_TIMEOUT with details.mayHaveExecuted:true; the message may already have been sent. The send waits once for a bounded wait (normally 20 seconds) and is never retried.\n\nA disconnected session returns 409 SESSION_NOT_CONNECTED with details.status, details.expected and mayHaveExecuted:false; nothing was sent. WhatsApp account restrictions return 429 WHATSAPP_RESTRICTED; do not retry immediately. A timeout or interrupted connection can return 504 SERVICE_TIMEOUT or 502 SERVICE_OPERATION_FAILED with details.mayHaveExecuted:true. The message may have been sent. Other service failures return SERVICE_OPERATION_FAILED; inspect the error details before deciding what to do.\n\ndata.id is the service message ID, not a platform UUID. Preserve the full provider ID for message actions and receipts. IDs in distinct the WhatsApp service events can use different representations; Wathook stores no correlation ledger or cumulative ACK state.\n\nLink previews are not offered and the service never fetches URLs from message text: linkPreview:true on any send returns 400 LINK_PREVIEW_UNAVAILABLE and nothing is stored or sent.\n\nSelect the session in the URL. Do not include sessionId in the JSON body; unknown body fields are rejected. Every request is a new send, with no automatic retry.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"201":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"}}}}},"example":{"data":{"id":"true_15550001001@c.us_EXAMPLE001","sessionId":"11111111-1111-4111-8111-111111111111"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","maxLength":100,"minLength":6},"text":{"type":"string","maxLength":4096},"body":{"type":"string","maxLength":4096},"mentions":{"type":"array","maxItems":1024,"items":{"type":"string","maxLength":100}}},"required":["to"],"additionalProperties":false,"anyOf":[{"required":["body"],"properties":{"body":{"pattern":"\\S"}}},{"required":["text"],"not":{"required":["body"]},"properties":{"text":{"pattern":"\\S"}}}]},"example":{"to":"15550001001","text":"Your order is ready."}}}}}},"/api/v1/whatsapp/{sessionId}/messages/image":{"post":{"operationId":"whatsapp-post-messages-image","tags":["Sending messages"],"summary":"Send an image message","description":"Send directly through this session's assigned WhatsApp service and return its result or error during the request.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nA request is sent once. Repeating a request sends another message. There is no automatic resend or permanent session hold after a failed request.\n\n201 means the service accepted the send. data contains its answer with id and sessionId; there is no platform message record or nested result ledger. Delivery and read receipts are separate events. A send timeout returns 504 SERVICE_TIMEOUT with details.mayHaveExecuted:true; the message may already have been sent. The send waits once for a bounded media wait (normally 120 seconds), including conversion and upload and is never retried.\n\nA disconnected session returns 409 SESSION_NOT_CONNECTED with details.status, details.expected and mayHaveExecuted:false; nothing was sent. WhatsApp account restrictions return 429 WHATSAPP_RESTRICTED; do not retry immediately. A timeout or interrupted connection can return 504 SERVICE_TIMEOUT or 502 SERVICE_OPERATION_FAILED with details.mayHaveExecuted:true. The message may have been sent. Other service failures return SERVICE_OPERATION_FAILED; inspect the error details before deciding what to do.\n\ndata.id is the service message ID, not a platform UUID. Preserve the full provider ID for message actions and receipts. IDs in distinct the WhatsApp service events can use different representations; Wathook stores no correlation ledger or cumulative ACK state.\n\nLink previews are not offered and the service never fetches URLs from message text: linkPreview:true on any send returns 400 LINK_PREVIEW_UNAVAILABLE and nothing is stored or sent.\n\nSend JPEG images (image/jpeg). image/png and image/webp are accepted, but the WhatsApp service recommends JPEG and does not convert images, so they reach WhatsApp as uploaded.\n\nMedia URL errors: 400 INVALID_MEDIA_URL when the URL breaks the rules above; 422 MEDIA_FETCH_FAILED when it cannot be downloaded (DNS, non-200 answer or redirect, TLS, connection, interruption or the 30-second limit). Nothing is sent or stored. A data URI without type/subtype or ;base64 returns 400 INVALID_MEDIA.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"201":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"}}}}},"example":{"data":{"id":"true_15550001001@c.us_EXAMPLE001","sessionId":"11111111-1111-4111-8111-111111111111"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","maxLength":100,"minLength":6},"media":{"type":"string","maxLength":150000000},"filename":{"type":"string","maxLength":200},"mimetype":{"type":"string","maxLength":120},"convert":{"type":"boolean"},"caption":{"type":"string","maxLength":4096}},"required":["to","media"],"additionalProperties":false},"example":{"to":"15550001001","media":"https://example.com/example-file","caption":"Example attachment"}}}}}},"/api/v1/whatsapp/{sessionId}/messages/video":{"post":{"operationId":"whatsapp-post-messages-video","tags":["Sending messages"],"summary":"Send a video message","description":"Send directly through this session's assigned WhatsApp service and return its result or error during the request.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nA request is sent once. Repeating a request sends another message. There is no automatic resend or permanent session hold after a failed request.\n\n201 means the service accepted the send. data contains its answer with id and sessionId; there is no platform message record or nested result ledger. Delivery and read receipts are separate events. A send timeout returns 504 SERVICE_TIMEOUT with details.mayHaveExecuted:true; the message may already have been sent. The send waits once for a bounded media wait (normally 120 seconds), including conversion and upload and is never retried.\n\nA disconnected session returns 409 SESSION_NOT_CONNECTED with details.status, details.expected and mayHaveExecuted:false; nothing was sent. WhatsApp account restrictions return 429 WHATSAPP_RESTRICTED; do not retry immediately. A timeout or interrupted connection can return 504 SERVICE_TIMEOUT or 502 SERVICE_OPERATION_FAILED with details.mayHaveExecuted:true. The message may have been sent. Other service failures return SERVICE_OPERATION_FAILED; inspect the error details before deciding what to do.\n\ndata.id is the service message ID, not a platform UUID. Preserve the full provider ID for message actions and receipts. IDs in distinct the WhatsApp service events can use different representations; Wathook stores no correlation ledger or cumulative ACK state.\n\nLink previews are not offered and the service never fetches URLs from message text: linkPreview:true on any send returns 400 LINK_PREVIEW_UNAVAILABLE and nothing is stored or sent.\n\nVideo MIME types must start with video/. Send MP4 with H.264 video and AAC audio: it is sent as is. Other types are re-encoded by the WhatsApp service, which takes time within the send timeout and fails for files with timecode, data, subtitle or attachment tracks (common in camera and editing-software exports, and iPhone .MOV files).\n\nMedia URL errors: 400 INVALID_MEDIA_URL when the URL breaks the rules above; 422 MEDIA_FETCH_FAILED when it cannot be downloaded (DNS, non-200 answer or redirect, TLS, connection, interruption or the 30-second limit). Nothing is sent or stored. A data URI without type/subtype or ;base64 returns 400 INVALID_MEDIA.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"201":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"}}}}},"example":{"data":{"id":"true_15550001001@c.us_EXAMPLE001","sessionId":"11111111-1111-4111-8111-111111111111"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","maxLength":100,"minLength":6},"media":{"type":"string","maxLength":150000000},"filename":{"type":"string","maxLength":200},"mimetype":{"type":"string","maxLength":120},"convert":{"type":"boolean"},"caption":{"type":"string","maxLength":4096}},"required":["to","media"],"additionalProperties":false},"example":{"to":"15550001001","media":"https://example.com/example-file","caption":"Example attachment"}}}}}},"/api/v1/whatsapp/{sessionId}/messages/document":{"post":{"operationId":"whatsapp-post-messages-document","tags":["Sending messages"],"summary":"Send a document message","description":"Send directly through this session's assigned WhatsApp service and return its result or error during the request.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nA request is sent once. Repeating a request sends another message. There is no automatic resend or permanent session hold after a failed request.\n\n201 means the service accepted the send. data contains its answer with id and sessionId; there is no platform message record or nested result ledger. Delivery and read receipts are separate events. A send timeout returns 504 SERVICE_TIMEOUT with details.mayHaveExecuted:true; the message may already have been sent. The send waits once for a bounded media wait (normally 120 seconds), including conversion and upload and is never retried.\n\nA disconnected session returns 409 SESSION_NOT_CONNECTED with details.status, details.expected and mayHaveExecuted:false; nothing was sent. WhatsApp account restrictions return 429 WHATSAPP_RESTRICTED; do not retry immediately. A timeout or interrupted connection can return 504 SERVICE_TIMEOUT or 502 SERVICE_OPERATION_FAILED with details.mayHaveExecuted:true. The message may have been sent. Other service failures return SERVICE_OPERATION_FAILED; inspect the error details before deciding what to do.\n\ndata.id is the service message ID, not a platform UUID. Preserve the full provider ID for message actions and receipts. IDs in distinct the WhatsApp service events can use different representations; Wathook stores no correlation ledger or cumulative ACK state.\n\nLink previews are not offered and the service never fetches URLs from message text: linkPreview:true on any send returns 400 LINK_PREVIEW_UNAVAILABLE and nothing is stored or sent.\n\nDocuments accept file attachments; use the correct filename and MIME type.\n\nMedia URL errors: 400 INVALID_MEDIA_URL when the URL breaks the rules above; 422 MEDIA_FETCH_FAILED when it cannot be downloaded (DNS, non-200 answer or redirect, TLS, connection, interruption or the 30-second limit). Nothing is sent or stored. A data URI without type/subtype or ;base64 returns 400 INVALID_MEDIA.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"201":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"sessionId":{"type":"string"}}}}},"example":{"data":{"id":"true_15550001001@c.us_EXAMPLE001","sessionId":"11111111-1111-4111-8111-111111111111"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","maxLength":100,"minLength":6},"media":{"type":"string","maxLength":150000000},"filename":{"type":"string","maxLength":200},"mimetype":{"type":"string","maxLength":120},"convert":{"type":"boolean"},"caption":{"type":"string","maxLength":4096}},"required":["to","media"],"additionalProperties":false},"example":{"to":"15550001001","media":"https://example.com/example-file","caption":"Example attachment"}}}}}},"/api/v1/sessions/{sessionId}/files/{filename}":{"get":{"operationId":"session-files-get","tags":["Media"],"summary":"Download service media","description":"Stream a file from this session's WhatsApp service using the media URL returned in a callback or live message read.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nUse the authenticated relative media.url returned by the API. This route returns bytes, not a JSON data envelope, and never exposes service credentials or lets the caller choose another service.\n\nThe filename must be one path segment, at most 255 UTF-8 bytes, with no slash, backslash, percent sign, query, fragment or control characters. No platform copy is retained; availability and deletion follow the WhatsApp service.\n\nThe response uses the service MIME type, an attachment filename, private no-store caching and the configured media size limit. Session ownership and billing access are checked before the service request.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"filename","in":"path","required":true,"description":"The service filename from a media URL returned for this session. Preserve and URL-encode the one path segment.","schema":{"type":"string"},"example":"example.jpg"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"example":"(binary file)"}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/chats":{"get":{"operationId":"whatsapp-get-chats","tags":["Chats"],"summary":"List chats","description":"Fetch chat information from the assigned WhatsApp service.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nURL-encode identifiers in path segments. Phone numbers may be supplied in international format; use returned personal @lid and group identifiers. Explicit newsletter targets are not offered.\n\nAggregate chat lists may include service-provided Channel summaries. Explicit newsletter-target operations are not offered.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"limit","in":"query","required":false,"description":"1–100 results; default 20.","schema":{"type":"integer"},"example":20},{"name":"offset","in":"query","required":false,"description":"0–100000 results to skip; default 0.","schema":{"type":"integer"},"example":0}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}}}},"example":{"data":[]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/chats/{chatId}/messages":{"get":{"operationId":"whatsapp-get-chats-chatid-messages","tags":["Messages and history"],"summary":"Get chat messages","description":"Fetch currently available messages from the service and normalize the response without retaining a platform copy.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nDownloadable media is requested when available. This does not guarantee a complete WhatsApp history.\n\nURL-encode identifiers in path segments. Phone numbers may be supplied in international format; use returned personal @lid and group identifiers. Explicit newsletter targets are not offered.\n\nThe result reflects the service's current available history, with no platform archive or revoke ledger. Incoming view-once content is omitted. Media links require session authorization and stream from the WhatsApp service; their availability depends on that service retaining the file.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"chatId","in":"path","required":true,"description":"An international phone number or WhatsApp chat identifier.","schema":{"type":"string"},"example":"15550001001@c.us"},{"name":"limit","in":"query","required":false,"description":"1–100 results; default 20.","schema":{"type":"integer"},"example":20},{"name":"offset","in":"query","required":false,"description":"0–100000 results to skip; default 0.","schema":{"type":"integer"},"example":0}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string"},"providerMessageId":{"type":"string"},"chatId":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"fromMe":{"type":"boolean"},"participant":{"type":"null"},"phoneNumber":{"type":"string"},"fromName":{"type":"string"},"username":{"type":"null"},"type":{"type":"string"},"text":{"type":"string"},"hasMedia":{"type":"boolean"},"story":{"type":"boolean"},"viewOnce":{"type":"boolean"},"media":{"type":"null"},"location":{"type":"null"},"contacts":{"type":"null"},"replyTo":{"type":"null"},"content":{"type":"object","properties":{}},"timestamp":{"type":"integer"},"ack":{"type":"null"},"ackName":{"type":"null"}}}}}},"example":{"data":[{"sessionId":"11111111-1111-4111-8111-111111111111","providerMessageId":"false_15550001001@c.us_EXAMPLE001","chatId":"15550001001@c.us","from":"15550001001@c.us","to":"15550001002@c.us","fromMe":false,"participant":null,"phoneNumber":"15550001001","fromName":"Example customer","username":null,"type":"text","text":"Hello","hasMedia":false,"story":false,"viewOnce":false,"media":null,"location":null,"contacts":null,"replyTo":null,"content":{},"timestamp":1791676800,"ack":null,"ackName":null}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/chats/{chatId}/archive":{"post":{"operationId":"whatsapp-post-chats-chatid-archive","tags":["Chats"],"summary":"Archive a chat","description":"Archive the selected chat.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nUse a phone number, a personal @c.us or @lid identifier, or a group @g.us identifier. Newsletter IDs are rejected for this operation.\n\nWhatsApp account permissions apply. A disconnected session returns 409 SESSION_NOT_CONNECTED with details.expected [\"WORKING\"]. A denied account permission returns 403 WHATSAPP_FORBIDDEN; a refused operation returns 422 WHATSAPP_REJECTED. These responses carry details.mayHaveExecuted:false. A 502 SERVICE_OPERATION_FAILED or 504 SERVICE_TIMEOUT during a change may carry details.mayHaveExecuted:true: the change may have completed. 501 FEATURE_NOT_OFFERED or CAPABILITY_UNSUPPORTED means the requested operation is unavailable. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nArchiving and unarchiving are WhatsApp app-state changes, which the service refreshes after WhatsApp accepts them. If that refresh fails (for example the connection dropped or WhatsApp rate-limited it), the answer is 502 SERVICE_OPERATION_FAILED with details.mayHaveExecuted:true, not 409 or 422; the change may already be live on the account.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"chatId","in":"path","required":true,"description":"An international phone number or WhatsApp chat identifier.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"}}}}},"example":{"data":{"success":true}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/chats/{chatId}/unarchive":{"post":{"operationId":"whatsapp-post-chats-chatid-unarchive","tags":["Chats"],"summary":"Unarchive a chat","description":"Unarchive the selected chat.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nUse a phone number, a personal @c.us or @lid identifier, or a group @g.us identifier. Newsletter IDs are rejected for this operation.\n\nWhatsApp account permissions apply. A disconnected session returns 409 SESSION_NOT_CONNECTED with details.expected [\"WORKING\"]. A denied account permission returns 403 WHATSAPP_FORBIDDEN; a refused operation returns 422 WHATSAPP_REJECTED. These responses carry details.mayHaveExecuted:false. A 502 SERVICE_OPERATION_FAILED or 504 SERVICE_TIMEOUT during a change may carry details.mayHaveExecuted:true: the change may have completed. 501 FEATURE_NOT_OFFERED or CAPABILITY_UNSUPPORTED means the requested operation is unavailable. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nArchiving and unarchiving are WhatsApp app-state changes, which the service refreshes after WhatsApp accepts them. If that refresh fails (for example the connection dropped or WhatsApp rate-limited it), the answer is 502 SERVICE_OPERATION_FAILED with details.mayHaveExecuted:true, not 409 or 422; the change may already be live on the account.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"chatId","in":"path","required":true,"description":"An international phone number or WhatsApp chat identifier.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"}}}}},"example":{"data":{"success":true}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/labels":{"get":{"operationId":"whatsapp-get-labels","tags":["Labels"],"summary":"List labels","description":"Read the labels available to this WhatsApp account.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nWhatsApp labels belong to WhatsApp Business accounts. An account has at most 20 labels; the WhatsApp service refuses more with 422.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}}}},"example":{"data":[]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"},"post":{"operationId":"whatsapp-post-labels","tags":["Labels"],"summary":"Create a label","description":"Create a WhatsApp label with a name and color index.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nWhatsApp labels belong to WhatsApp Business accounts. An account has at most 20 labels; the WhatsApp service refuses more with 422.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"201":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}}}},"example":{"data":{}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"minLength":1},"color":{"type":"integer","minimum":0,"maximum":19}},"required":["name","color"],"additionalProperties":false},"example":{"name":"Customers","color":3}}}}}},"/api/v1/whatsapp/{sessionId}/labels/{labelId}":{"put":{"operationId":"whatsapp-put-labels-labelid","tags":["Labels"],"summary":"Update a label","description":"Replace the label name and color; both fields are required for PUT and PATCH.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nThe name must differ from the label's current name: the WhatsApp service refuses an unchanged name with 422 (\"Label with '<name>' already exists\"), so a colour-only change is not possible.\n\nWhatsApp labels belong to WhatsApp Business accounts. An account has at most 20 labels; the WhatsApp service refuses more with 422.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"labelId","in":"path","required":true,"description":"A numeric label identifier containing 1–10 digits.","schema":{"type":"string"},"example":"1"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}}}},"example":{"data":{}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"minLength":1},"color":{"type":"integer","minimum":0,"maximum":19}},"required":["name","color"],"additionalProperties":false},"example":{"name":"Customers","color":3}}}}},"patch":{"operationId":"whatsapp-patch-labels-labelid","tags":["Labels"],"summary":"Update a label","description":"Replace the label name and color; both fields are required for PUT and PATCH.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nThe name must differ from the label's current name: the WhatsApp service refuses an unchanged name with 422 (\"Label with '<name>' already exists\"), so a colour-only change is not possible.\n\nWhatsApp labels belong to WhatsApp Business accounts. An account has at most 20 labels; the WhatsApp service refuses more with 422.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"labelId","in":"path","required":true,"description":"A numeric label identifier containing 1–10 digits.","schema":{"type":"string"},"example":"1"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}}}},"example":{"data":{}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100,"minLength":1},"color":{"type":"integer","minimum":0,"maximum":19}},"required":["name","color"],"additionalProperties":false},"example":{"name":"Customers","color":3}}}}},"delete":{"operationId":"whatsapp-delete-labels-labelid","tags":["Labels"],"summary":"Delete a label","description":"Remove a WhatsApp label.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"labelId","in":"path","required":true,"description":"A numeric label identifier containing 1–10 digits.","schema":{"type":"string"},"example":"1"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}}}},"example":{"data":{}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/labels/{labelId}/chats":{"get":{"operationId":"whatsapp-get-labels-labelid-chats","tags":["Labels"],"summary":"List chats with a label","description":"Read the service's chats assigned to this label.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"labelId","in":"path","required":true,"description":"A numeric label identifier containing 1–10 digits.","schema":{"type":"string"},"example":"1"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}}}},"example":{"data":[]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/chats/{chatId}/labels":{"get":{"operationId":"whatsapp-get-chats-chatid-labels","tags":["Labels"],"summary":"Get a chat's labels","description":"List labels assigned to a chat.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"chatId","in":"path","required":true,"description":"An international phone number or WhatsApp chat identifier.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}}}},"example":{"data":[]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"},"put":{"operationId":"whatsapp-put-chats-chatid-labels","tags":["Labels"],"summary":"Replace a chat's labels","description":"Assign a complete set of labels to a chat. An empty array clears the assignments.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe data payload comes from the WhatsApp service. Its populated fields vary by service response; the empty example shows the response envelope, not a fixed resource schema. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"chatId","in":"path","required":true,"description":"An international phone number or WhatsApp chat identifier.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{}}}},"example":{"data":{}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labels":{"type":"array","maxItems":20,"items":{"type":"string","pattern":"^\\d{1,10}$"}}},"required":["labels"],"additionalProperties":false},"example":{"labels":["1","2"]}}}}}},"/api/v1/whatsapp/{sessionId}/groups":{"get":{"operationId":"whatsapp-get-groups","tags":["Groups"],"summary":"List groups","description":"List groups available to this WhatsApp account.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nGroup objects are normalized to identifiers, names and descriptions; available participant and ownership metadata is retained. Group list/get results are normalized this way; participant reads return the service's answer as it is.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"limit","in":"query","required":false,"description":"1–100 results; default 20.","schema":{"type":"integer"},"example":20},{"name":"offset","in":"query","required":false,"description":"0–100000 results to skip; default 0.","schema":{"type":"integer"},"example":0}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}}}},"example":{"data":[{"id":"120363000000000001@g.us","name":"Example team","description":"Team updates"}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/groups/{groupId}":{"get":{"operationId":"whatsapp-get-groups-groupid","tags":["Groups"],"summary":"Get a group","description":"Read one group's normalized metadata.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nURL-encode identifiers in path segments. Phone numbers may be supplied in international format; use returned personal @lid and group identifiers. Explicit newsletter targets are not offered.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"groupId","in":"path","required":true,"description":"A WhatsApp group identifier ending in @g.us.","schema":{"type":"string"},"example":"120363000000000001@g.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}}},"example":{"data":{"id":"120363000000000001@g.us","name":"Example team","description":"Team updates"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/groups/{groupId}/participants":{"get":{"operationId":"whatsapp-get-groups-groupid-participants","tags":["Groups"],"summary":"List group participants","description":"Read group membership and available roles.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nParticipant results depend on the account's access and available session metadata. the WhatsApp service's list is returned as it is, for example [{id, role, pn?}]; identifiers are returned without platform rewriting.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"groupId","in":"path","required":true,"description":"A WhatsApp group identifier ending in @g.us.","schema":{"type":"string"},"example":"120363000000000001@g.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"}}}}}},"example":{"data":[{"id":"15550001001@c.us","role":"participant"}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/contacts/{contactId}/block":{"post":{"operationId":"whatsapp-post-contacts-contactid-block","tags":["Contacts"],"summary":"Block a contact","description":"Update the account's WhatsApp blocklist for this contact.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nWhatsApp account permissions apply. A disconnected session returns 409 SESSION_NOT_CONNECTED with details.expected [\"WORKING\"]. A denied account permission returns 403 WHATSAPP_FORBIDDEN; a refused operation returns 422 WHATSAPP_REJECTED. These responses carry details.mayHaveExecuted:false. A 502 SERVICE_OPERATION_FAILED or 504 SERVICE_TIMEOUT during a change may carry details.mayHaveExecuted:true: the change may have completed. 501 FEATURE_NOT_OFFERED or CAPABILITY_UNSUPPORTED means the requested operation is unavailable. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nThe response is the returned blocklist normalized to id objects.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"contactId","in":"path","required":true,"description":"A personal phone number, @c.us identifier or @lid identifier; group and newsletter identifiers are rejected.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}}}}}},"example":{"data":[{"id":"15550001001@c.us"}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}}}},"/api/v1/whatsapp/{sessionId}/contacts/{contactId}/unblock":{"post":{"operationId":"whatsapp-post-contacts-contactid-unblock","tags":["Contacts"],"summary":"Unblock a contact","description":"Update the account's WhatsApp blocklist for this contact.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nWhatsApp account permissions apply. A disconnected session returns 409 SESSION_NOT_CONNECTED with details.expected [\"WORKING\"]. A denied account permission returns 403 WHATSAPP_FORBIDDEN; a refused operation returns 422 WHATSAPP_REJECTED. These responses carry details.mayHaveExecuted:false. A 502 SERVICE_OPERATION_FAILED or 504 SERVICE_TIMEOUT during a change may carry details.mayHaveExecuted:true: the change may have completed. 501 FEATURE_NOT_OFFERED or CAPABILITY_UNSUPPORTED means the requested operation is unavailable. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nThe response is the returned blocklist normalized to id objects.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"contactId","in":"path","required":true,"description":"A personal phone number, @c.us identifier or @lid identifier; group and newsletter identifiers are rejected.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}}}},"example":{"data":[]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false},"example":{}}}}}},"/api/v1/whatsapp/{sessionId}/blacklist":{"get":{"operationId":"whatsapp-get-blacklist","tags":["Contacts"],"summary":"List blocked contacts","description":"Get the WhatsApp blocklist as normalized contact identifiers.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nWhatsApp account permissions apply. A disconnected session returns 409 SESSION_NOT_CONNECTED with details.expected [\"WORKING\"]. A denied account permission returns 403 WHATSAPP_FORBIDDEN; a refused operation returns 422 WHATSAPP_REJECTED. These responses carry details.mayHaveExecuted:false. A 502 SERVICE_OPERATION_FAILED or 504 SERVICE_TIMEOUT during a change may carry details.mayHaveExecuted:true: the change may have completed. 501 FEATURE_NOT_OFFERED or CAPABILITY_UNSUPPORTED means the requested operation is unavailable. A failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}}}}}},"example":{"data":[{"id":"15550001001@c.us"}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/contacts/{contactId}/check-exists":{"get":{"operationId":"whatsapp-get-contacts-contactid-check-exists","tags":["Contacts"],"summary":"Check one WhatsApp number","description":"Check whether a single phone number exists on WhatsApp.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nUse an international phone number or numeric @c.us identifier. @lid is rejected for this check.\n\nThis endpoint checks one number. Use POST contacts/check-exists to check up to 100 numbers in one bounded request.\n\nThe lookup answers {numberExists, chatId, pn}: chatId can be a LID (for example {\"numberExists\":true,\"chatId\":\"23423462304912@lid\",\"pn\":\"15550001001@c.us\"}), pn is the phone form or null, and a number not on WhatsApp is {\"numberExists\":false,\"chatId\":null,\"pn\":null}. The platform returns these identifiers without rewriting or caching their mapping. Use pn when present; do not derive a phone number from LID digits.\n\nOn a session that is not WORKING, the WhatsApp service holds the lookup for about 5–10 seconds and refuses it; the API answers 409 SESSION_NOT_CONNECTED with details {status (null when the service has no such session), expected, mayHaveExecuted:false}.\n\nA failed GET changes nothing: a service timeout, invalid answer or lost connection answers 504 SERVICE_TIMEOUT \"The WhatsApp service did not answer in time.\", 502 SERVICE_INVALID_RESPONSE \"The WhatsApp service returned an invalid response.\" or 502 SERVICE_CONNECTION_LOST \"The connection to the WhatsApp service ended without a response.\" with details.mayHaveExecuted:false. A POST, PUT, PATCH or DELETE keeps \"... The operation may have completed.\" with details.mayHaveExecuted:true for these failures.\n\nEach lookup marks the WhatsApp account online for about 90 seconds, as a send does.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"},{"name":"contactId","in":"path","required":true,"description":"A personal phone number, @c.us identifier or @lid identifier; group and newsletter identifiers are rejected.","schema":{"type":"string"},"example":"15550001001@c.us"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"numberExists":{"type":"boolean"},"chatId":{"type":"string"},"pn":{"type":"string"}}}}},"example":{"data":{"numberExists":true,"chatId":"23423462304912@lid","pn":"15550001001@c.us"}}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session"}},"/api/v1/whatsapp/{sessionId}/contacts/check-exists":{"post":{"operationId":"whatsapp-post-contacts-check-exists","tags":["Contacts"],"summary":"Check WhatsApp numbers in bulk","description":"Check 1–100 phone numbers through the session's service and return one ordered result for every input, including individual failures.\n\nAuthentication and scope:\nSession token: Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID.\n\nThe overall JSON request body is limited to 16 KiB. The overall response is HTTP 200 with data as an array, even when individual checks fail. Inspect each item's status and data or error.\n\nInput order and duplicates are preserved. Successful data is the single-number service response; numberExists:false is different from a failed or unstarted lookup.\n\nThe lookup answers {numberExists, chatId, pn}: chatId can be a LID (for example {\"numberExists\":true,\"chatId\":\"23423462304912@lid\",\"pn\":\"15550001001@c.us\"}), pn is the phone form or null, and a number not on WhatsApp is {\"numberExists\":false,\"chatId\":null,\"pn\":null}. The platform returns these identifiers without rewriting or caching their mapping. Use pn when present; do not derive a phone number from LID digits.\n\nUp to five checks run concurrently within a 30-second service-forwarding budget; request processing can add to response time. Unstarted entries return status 504, code BULK_CHECK_TIMEOUT and details.attempted:false. A lookup issued but not answered before the shared deadline is also 504 BULK_CHECK_TIMEOUT, with the message \"The batch deadline ended before the service answered for this number.\" and details.attempted:true; bulk items never use SERVICE_TIMEOUT. A per-item 502 SERVICE_CONNECTION_LOST or SERVICE_INVALID_RESPONSE has no details. A lookup changes nothing, so no bulk-check answer carries mayHaveExecuted:true.\n\nAuthentication, ownership, billing and invalid-batch errors are returned before service calls. Then the platform reads the session's live state once (5-second timeout, inside the 30-second budget): unless the WhatsApp service reports WORKING, the whole request answers 409 SESSION_NOT_CONNECTED with details {status (null when the service has no such session), expected:[\"WORKING\"]} and no lookup is made. If a lookup meets the WhatsApp service's session-state refusal during the batch, no further lookups start and the lookups already issued finish. The response is still 200 with every item: finished items are returned as usual, each refused lookup is a per-item 409 SESSION_NOT_CONNECTED with details {status, expected}, and each number not started is the same 409 with details {status, expected, attempted:false}; this includes a number whose per-number recheck (billing, suspension, service controls) was still running when the batch stopped, which is not looked up. An unexpected platform failure during the batch, for example a failure while rechecking account access, also starts no further lookups; once the lookups already issued end, the whole request fails with 503 SERVICE_UNAVAILABLE and no item results. A failure of the live read itself is a request-level error: 504 SERVICE_TIMEOUT, 502 SERVICE_CONNECTION_LOST or 502 SERVICE_INVALID_RESPONSE, whose message ends \"The session state could not be read, so no number was checked.\" and whose details are {mayHaveExecuted:false}; 503 SERVICE_UNAVAILABLE; 502 SERVICE_AUTH_FAILED; or SERVICE_OPERATION_FAILED.\n\nBilling, suspension and maintenance are rechecked before each number (for example a per-item 402 SESSION_EXPIRED). Every valid input is attempted at most once; no retries, background job, send operation or session hold is created. Each lookup marks the account online like a send.","security":[{"SessionToken":[]}],"parameters":[{"name":"sessionId","in":"path","required":true,"description":"The session's UUID or 5-character short ID; a session token reaches only its own session.","schema":{"type":"string"},"example":"11111111-1111-4111-8111-111111111111"}],"responses":{"200":{"description":"Example response. Available resource fields depend on the current WhatsApp response.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","minItems":1,"maxItems":100,"items":{"oneOf":[{"type":"object","properties":{"phone":{"type":"string"},"status":{"type":"integer","const":200},"data":{}},"required":["phone","status","data"],"additionalProperties":false},{"type":"object","properties":{"phone":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}},"required":["code","message"],"additionalProperties":false}},"required":["phone","status","error"],"additionalProperties":false}]}}},"required":["data"],"additionalProperties":false},"example":{"data":[{"phone":"15550001001","status":200,"data":{"numberExists":true,"chatId":"23423462304912@lid","pn":"15550001001@c.us"}},{"phone":"15550001002","status":200,"data":{"numberExists":false,"chatId":null,"pn":null}},{"phone":"15550001003","status":504,"error":{"code":"BULK_CHECK_TIMEOUT","message":"The batch deadline ended before this number could be checked.","details":{"attempted":false}}}]}}}},"default":{"description":"Platform or the WhatsApp service error. A 504 timeout may have executed; no outgoing retry or persistent hold is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-auth-scope":"Session token","x-auth-scopes":{"session":"Only the session bound to this token. sessionId in the URL must name that session, by UUID or short ID."},"x-documentation-area":"session","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phones":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1,"maxLength":40}}},"required":["phones"],"additionalProperties":false},"example":{"phones":["15550001001","15550001002","15550001003"]}}}}}}},"webhooks":{"whatsappEvent":{"post":{"summary":"Receive a subscribed event at your own webhook URL","description":"The body-mode delivery example. Return 2xx promptly. The platform forwards each source event inline at most once per logical target, with no retries or replay. A crash before forwarding can lose the callback, and an unconfirmed result may still have reached your receiver. Separate account and session targets are separate deliveries, even when their URLs match. The service can emit the same WhatsApp message again as a new event with a new id; if your integration needs message-level deduplication, use the raw part of data.providerMessageId (the segment after the chat) together with data.fromMe. X-Webhook-Id identifies the consumed receipt. There is at most one HTTP attempt. Overload can prevent a new notification from being admitted before any delivery opportunity is consumed. A consumed event is never replayed. Business-notification capacity exhaustion can consume a receipt without making an attempt, preserving the business action. session_id (the session UUID) and session_short_id (its short ID) are present for session-scoped events. Other configured modes use path or HTTP method routing, as documented in webhook settings.","parameters":[{"name":"X-Webhook-Id","in":"header","required":true,"schema":{"type":"string"},"description":"Receipt ID for the one permitted attempt."},{"name":"X-Webhook-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds used when signing this attempt."},{"name":"X-Webhook-Signature","in":"header","required":false,"schema":{"type":"string"},"description":"When a secret is configured: sha256=<HMAC-SHA256 of timestamp + '.' + raw JSON body>."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"session_id":{"type":"string","format":"uuid"},"session_short_id":{"type":"string","pattern":"^[2-9bcdfghjkmnpqrstvwxyz]{5,8}$"},"data":{"type":"object","additionalProperties":true}}},"example":{"id":"00000000-0000-4000-8000-000000000010","type":"statuses.post","createdAt":"2026-01-01T12:00:00.000Z","session_id":"00000000-0000-4000-8000-000000000001","session_short_id":"k7m2q","data":{"sessionId":"00000000-0000-4000-8000-000000000001","providerEvent":"message.ack","providerMessageId":"true_15550001001@c.us_EXAMPLE001","ack":1,"ackName":"SERVER","state":"sent","timestamp":1767268800000,"data":{"id":"true_15550001001@c.us_EXAMPLE001","ack":1,"ackName":"SERVER"}}}}}},"responses":{"204":{"description":"Your receiver accepted the event."}}}}},"components":{"securitySchemes":{"SessionToken":{"type":"http","scheme":"bearer","description":"Scoped pc_ session token for one session on /api/v1, including the token of a partner's session. Use only your own session."},"PartnerToken":{"type":"http","scheme":"bearer","description":"Partner pm_ Manager token for POST /api/manager/sessions and DELETE /api/manager/sessions/{sessionId} only. Keep it on your server; it has no owner or session-runtime authority."}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}