Skip to content
JawibDocumentationWHATSAPP API · v2
Documentation/WhatsApp connections

WhatsApp connections

Create a connection with the customer's API key. The API returns 202 and the connection UUID in data.id. This starts a pairing attempt; it does not mean that WhatsApp is connected.

QR pairing

  1. Create a connection with method: qr and privacy_accepted: true.
  2. Retrieve GET connections/{connection}/pairing using the same customer key.
  3. Open data.hosted_url for the customer, or render data.qr_data_url as an image in your application.
  4. Poll the pairing endpoint every few seconds until the status is connected. Pairing credentials expire; create a new attempt after expiration.

Obtain the number owner's authorization before pairing and enabling content capture. Hosted pairing links are temporary credentials and must not be published or logged.

Phone-code pairing

Use method: code with phone in international format without the leading plus sign. When ready, the pairing response includes code. The requested phone number is not a verified identity until pairing completes.

Inbox settings

inbox_enabled controls private-conversation capture. group_inbox_enabled controls group-content capture independently. Enable only the capture that your integration needs and the number owner has authorized.

Infrastructure connections use inbox_reply_mode: external. Jawib's internal bots do not run on these connections, and internal reply mode is not permitted.

Disconnection and ownership

Disconnecting stops use of the connection. It does not immediately erase retained history. A customer cannot use another customer's connection, and pairing does not silently transfer an existing number between customer data boundaries.

List connections

GET/api/v2/connections
Key owner: Customer or direct companyRequired scope: connections:read
curl --request GET "https://playjawib.com/api/v2/connections" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": [],
    "next_after_id": null
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Create a connection

POST/api/v2/connections
Key owner: Customer or direct companyRequired scope: connections:pair
curl --request POST "https://playjawib.com/api/v2/connections" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: unique-operation-123' \
  --header 'Content-Type: application/json' \
  --data '{
    "method": "qr",
    "name": "Customer WhatsApp",
    "privacy_accepted": true,
    "inbox_enabled": true,
    "group_inbox_enabled": false
}'
Request body fields
FieldTypeDescription
namestring—
methodstringqr / code
phonestringRequired for code pairing, international phone number.
privacy_acceptedrequiredboolean—
inbox_enabledboolean—
group_inbox_enabledboolean—
return_urlstring—
Response example 202
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000002",
        "name": "Customer WhatsApp",
        "status": "pairing",
        "service_mode": true,
        "is_healthy": false,
        "group_inbox_enabled": false,
        "inbox_enabled": true,
        "inbox_reply_mode": "external",
        "requires_relink": false,
        "pairing_expires_at": "2026-10-29T09:03:00+00:00",
        "pairing_path": "/api/v2/connections/019c0000-0000-7000-8000-000000000002/pairing",
        "last_seen_at": null
    }
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Retrieve a connection

GET/api/v2/connections/{connection}
Key owner: Customer or direct companyRequired scope: connections:read

Replace {connection} with the actual IDs returned by the API.

curl --request GET "https://playjawib.com/api/v2/connections/{connection}" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000002",
        "name": "Customer WhatsApp",
        "status": "pairing",
        "service_mode": true,
        "is_healthy": false,
        "group_inbox_enabled": false,
        "inbox_enabled": true,
        "inbox_reply_mode": "external",
        "requires_relink": false,
        "pairing_expires_at": "2026-10-29T09:03:00+00:00",
        "pairing_path": "/api/v2/connections/019c0000-0000-7000-8000-000000000002/pairing",
        "last_seen_at": null
    }
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Retrieve pairing credentials

GET/api/v2/connections/{connection}/pairing
Key owner: Customer or direct companyRequired scope: connections:pair

Replace {connection} with the actual IDs returned by the API.

curl --request GET "https://playjawib.com/api/v2/connections/{connection}/pairing" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000002",
        "name": "Customer WhatsApp",
        "status": "qr_ready",
        "service_mode": true,
        "is_healthy": false,
        "group_inbox_enabled": false,
        "inbox_enabled": true,
        "inbox_reply_mode": "external",
        "requires_relink": false,
        "pairing_expires_at": "2026-10-29T09:03:00+00:00",
        "pairing_path": "/api/v2/connections/019c0000-0000-7000-8000-000000000002/pairing",
        "last_seen_at": null,
        "hosted_url": "https://playjawib.com/integrations/connect/019c0000-0000-7000-8000-000000000002?expires=TIMESTAMP&signature=SIGNATURE",
        "qr_data_url": "data:image/png;base64,BASE64_ENCODED_PNG"
    }
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Update inbox settings

PATCH/api/v2/connections/{connection}
Key owner: Customer or direct companyRequired scope: connections:write

Replace {connection} with the actual IDs returned by the API.

curl --request PATCH "https://playjawib.com/api/v2/connections/{connection}" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "inbox_enabled": true,
    "group_inbox_enabled": true
}'
Request body fields
FieldTypeDescription
inbox_enabledboolean—
group_inbox_enabledboolean—
inbox_reply_modestringinternal / external / human
Response example 200
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000002",
        "name": "Customer WhatsApp",
        "status": "pairing",
        "service_mode": true,
        "is_healthy": false,
        "group_inbox_enabled": true,
        "inbox_enabled": true,
        "inbox_reply_mode": "external",
        "requires_relink": false,
        "pairing_expires_at": "2026-10-29T09:03:00+00:00",
        "pairing_path": "/api/v2/connections/019c0000-0000-7000-8000-000000000002/pairing",
        "last_seen_at": null
    }
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

DELETE/api/v2/connections/{connection}
Key owner: Customer or direct companyRequired scope: connections:write

Replace {connection} with the actual IDs returned by the API.

curl --request DELETE "https://playjawib.com/api/v2/connections/{connection}" \
  --header "Authorization: Bearer $JAWIB_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000002",
        "name": "Customer WhatsApp",
        "status": "revoked",
        "service_mode": true,
        "is_healthy": false,
        "group_inbox_enabled": false,
        "inbox_enabled": false,
        "inbox_reply_mode": "external",
        "requires_relink": false,
        "pairing_expires_at": "2026-10-29T09:03:00+00:00",
        "pairing_path": "/api/v2/connections/019c0000-0000-7000-8000-000000000002/pairing",
        "last_seen_at": null
    },
    "cleanup": {
        "remote_logout_confirmed": true
    }
}

Illustrative values. Use the actual identifiers and credentials returned by your request.

Jawib API documentationAPI v2 · HTTPS / JSON
Search guides and API endpoints · Press Esc to close