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
- With your company management key, call
POST /api/v2/customersto create an isolated customer account. - Call
POST /api/v2/customers/{customer}/keysto issue its customer key. - With that customer key, create and pair a WhatsApp connection.
- 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
curl --request GET "https://playjawib.com/api/v2/customers" \
--header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
--header 'Accept: application/json'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('GET', 'https://playjawib.com/api/v2/customers');
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json'
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');{
"data": [],
"meta": {
"page": 1,
"last_page": 1
}
}Illustrative values. Use the actual identifiers and credentials returned by your request.
Create a customer
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"
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->withHeader('Idempotency-Key', 'unique-operation-123')
->send('POST', 'https://playjawib.com/api/v2/customers', [
'json' => json_decode(<<<'JSON'
{
"name": "Example Customer",
"external_id": "customer-123"
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json',
'Idempotency-Key': 'unique-operation-123',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"name": "Example Customer",
"external_id": "customer-123"
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
namerequired | string | — |
external_idrequired | string | — |
{
"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
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"
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('POST', 'https://playjawib.com/api/v2/customers/{customer}/bootstrap', [
'json' => json_decode(<<<'JSON'
{
"request_id": "019c0000-0000-7000-8000-000000000010",
"webhook_url": "https://example.com/webhooks/jawib"
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers/{customer}/bootstrap', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"request_id": "019c0000-0000-7000-8000-000000000010",
"webhook_url": "https://example.com/webhooks/jawib"
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
request_idrequired | string | — |
webhook_urlrequired | string | Public HTTPS callback URL. SSRF protections apply. |
{
"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
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"
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('POST', 'https://playjawib.com/api/v2/customers/{customer}/bootstrap/acknowledge', [
'json' => json_decode(<<<'JSON'
{
"request_id": "019c0000-0000-7000-8000-000000000010"
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers/{customer}/bootstrap/acknowledge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"request_id": "019c0000-0000-7000-8000-000000000010"
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
request_idrequired | string | — |
{
"acknowledged": true
}Illustrative values. Use the actual identifiers and credentials returned by your request.
List customer keys
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'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('GET', 'https://playjawib.com/api/v2/customers/{customer}/keys');
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers/{customer}/keys', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json'
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');{
"data": []
}Illustrative values. Use the actual identifiers and credentials returned by your request.
Issue a customer key
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"
]
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('POST', 'https://playjawib.com/api/v2/customers/{customer}/keys', [
'json' => json_decode(<<<'JSON'
{
"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"
]
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers/{customer}/keys', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"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"
]
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
scopes | array | — |
{
"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
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'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('DELETE', 'https://playjawib.com/api/v2/customers/{customer}/keys/{key}');
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers/{customer}/keys/{key}', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json'
}
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');{
"revoked": true
}Illustrative values. Use the actual identifiers and credentials returned by your request.
Update customer status
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"
}'use Illuminate\Support\Facades\Http;
$response = Http::acceptJson()
->withToken(env('JAWIB_COMPANY_API_KEY'))
->send('PATCH', 'https://playjawib.com/api/v2/customers/{customer}', [
'json' => json_decode(<<<'JSON'
{
"status": "suspended"
}
JSON, true),
]);
$data = $response->throw()->json();// Run in your server, e.g. Node.js. Never expose the token in browser code.
const response = await fetch('https://playjawib.com/api/v2/customers/{customer}', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.JAWIB_COMPANY_API_KEY}`,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"status": "suspended"
})
});
const data = await response.json();
if (!response.ok) throw new Error(data.message ?? 'Request failed');Request body fields
| Field | Type | Description |
|---|---|---|
statusrequired | string | active / suspended |
{
"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.