Skip to content
JawibDocumentationWHATSAPP API · v2
Documentation/Customers

Customers

The customer management API is available to partner companies. Each customer has an independent boundary for connections, messages, groups, media, API keys, and webhooks. Creating a customer does not create a Jawib login or password for that customer.

When to use this API

Use Customers when your company provides a service to multiple customers and each customer connects their own WhatsApp number. For example, a software company can provision Customer A and Customer B with separate credentials and data.

A customer is an isolated service account that owns a connected number. It is not a message recipient, a WhatsApp contact, or a chat participant. Set the recipient in the message request's to field.

If you only use your own account's WhatsApp number, you do not need to create a customer. Use the Connections and Messages APIs directly.

Provisioning flow

  1. With your company management key, call POST /api/v2/customers to create an isolated customer account.
  2. Call POST /api/v2/customers/{customer}/keys to issue its customer key.
  3. With that customer key, create and pair a WhatsApp connection.
  4. Use the customer's key for messages, conversations, groups, and webhooks belonging to that customer.

The partner company remains responsible for the subscription. Customer API usage and sending attempts consume the company's shared plan allowance. End customers do not need a separate Jawib login.

External references

Set external_id to a stable reference from your own system, such as customer-123. The reference is unique within your partner company. Repeating the same reference and name returns the existing customer; using it with a different name returns 409.

Store the returned data.id for subsequent customer-management requests. Active customers count toward your plan's customer limit. Each customer may have one live connection, and all customers share the company's total connection allowance.

Customer credentials

The issue-key endpoint returns the plaintext credential in data.token once. Save it securely before closing the response. Use that token, rather than the company management token, for the customer's WhatsApp operations.

Customer status

Setting status: suspended revokes the customer's API keys and disconnects their session. Setting status: active is subject to the active-customer limit. Re-activation does not restore old keys or reconnect WhatsApp automatically.

List customers

GET/api/v2/customers
Key owner: Partner companyRequired scope: customers:read
curl --request GET "https://playjawib.com/api/v2/customers" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": [],
    "meta": {
        "page": 1,
        "last_page": 1
    }
}

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

Create a customer

POST/api/v2/customers
Key owner: Partner companyRequired scope: customers:write
curl --request POST "https://playjawib.com/api/v2/customers" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: unique-operation-123' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Example Customer",
    "external_id": "customer-123"
}'
Request body fields
FieldTypeDescription
namerequiredstring—
external_idrequiredstring—
Response example 201
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000001",
        "external_id": "customer-123",
        "name": "Example Customer",
        "status": "active",
        "connection_limit": 1
    }
}

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

Bootstrap a managed customer

POST/api/v2/customers/{customer}/bootstrap
Key owner: Partner companyRequired scope: customers:write

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

curl --request POST "https://playjawib.com/api/v2/customers/{customer}/bootstrap" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "request_id": "019c0000-0000-7000-8000-000000000010",
    "webhook_url": "https://example.com/webhooks/jawib"
}'
Request body fields
FieldTypeDescription
request_idrequiredstring—
webhook_urlrequiredstringPublic HTTPS callback URL. SSRF protections apply.
Response example 201
{
    "data": {
        "customer_id": "019c0000-0000-7000-8000-000000000001",
        "workspace_id": "42",
        "token": "jwb_REDACTED_EXAMPLE",
        "key_id": "12",
        "webhook_id": "18",
        "webhook_secret": "whsec_REDACTED_EXAMPLE"
    }
}

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

Acknowledge stored customer credentials

POST/api/v2/customers/{customer}/bootstrap/acknowledge
Key owner: Partner companyRequired scope: customers:write

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

curl --request POST "https://playjawib.com/api/v2/customers/{customer}/bootstrap/acknowledge" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "request_id": "019c0000-0000-7000-8000-000000000010"
}'
Request body fields
FieldTypeDescription
request_idrequiredstring—
Response example 200
{
    "acknowledged": true
}

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

List customer keys

GET/api/v2/customers/{customer}/keys
Key owner: Partner companyRequired scope: customers:read

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

curl --request GET "https://playjawib.com/api/v2/customers/{customer}/keys" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "data": []
}

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

Issue a customer key

POST/api/v2/customers/{customer}/keys
Key owner: Partner companyRequired scope: customers:write

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

curl --request POST "https://playjawib.com/api/v2/customers/{customer}/keys" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "scopes": [
        "connections:pair",
        "connections:read",
        "connections:write",
        "messages:write",
        "messages:read",
        "conversations:read",
        "groups:read",
        "groups:write",
        "groups:messages:read",
        "groups:receipts:read",
        "webhooks:read",
        "webhooks:write"
    ]
}'
Request body fields
FieldTypeDescription
scopesarray—
Response example 201
{
    "data": {
        "id": "12",
        "token": "jwb_REDACTED_EXAMPLE",
        "customer_id": "019c0000-0000-7000-8000-000000000001",
        "scopes": [
            "connections:pair",
            "connections:read",
            "connections:write",
            "messages:write",
            "messages:read",
            "conversations:read",
            "groups:read",
            "groups:write",
            "groups:messages:read",
            "groups:receipts:read",
            "webhooks:read",
            "webhooks:write"
        ]
    }
}

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

Revoke a customer key

DELETE/api/v2/customers/{customer}/keys/{key}
Key owner: Partner companyRequired scope: customers:write

Replace {customer}, {key} with the actual IDs returned by the API.

curl --request DELETE "https://playjawib.com/api/v2/customers/{customer}/keys/{key}" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json'
Response example 200
{
    "revoked": true
}

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

Update customer status

PATCH/api/v2/customers/{customer}
Key owner: Partner companyRequired scope: customers:write

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

curl --request PATCH "https://playjawib.com/api/v2/customers/{customer}" \
  --header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "suspended"
}'
Request body fields
FieldTypeDescription
statusrequiredstringactive / suspended
Response example 200
{
    "data": {
        "id": "019c0000-0000-7000-8000-000000000001",
        "external_id": "customer-123",
        "name": "Example Customer",
        "status": "suspended",
        "connection_limit": 1
    }
}

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