Partner integration
Use this flow when your company integrates Jawib into a platform used by multiple customers, each with their own WhatsApp number. Your customers connect inside your application and do not need a Jawib account.
Two credential boundaries
| Credential | Used by your backend for |
|---|---|
| Company management key | Creating customer accounts and issuing or revoking customer keys. |
| Customer key | Pairing that customer's number and accessing their messages, conversations, media, groups, and webhooks. |
The company holds the subscription. Each customer has an isolated data boundary, while API and sending usage aggregate under the company's approved plan.
End-to-end flow
Partner company
├── Customer A → Customer A key → WhatsApp connection A → Chats A
└── Customer B → Customer B key → WhatsApp connection B → Chats B
1. Create a customer account
After company subscription activation, use a company key with customers:write:
curl --request POST 'https://playjawib.com/api/v2/customers' \
--header "Authorization: Bearer $JAWIB_COMPANY_API_KEY" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: provision-customer-123' \
--data '{
"name": "Customer A",
"external_id": "customer-123"
}'Store the returned data.id as CUSTOMER_UUID. This request creates the customer's data boundary; it does not start a WhatsApp connection or return QR credentials.
2. Issue the customer's key
curl --request POST 'https://playjawib.com/api/v2/customers/CUSTOMER_UUID/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", "conversations:write", "media:read",
"webhooks:read", "webhooks:write"
]
}'Save data.token securely on your backend as this customer's key. It is shown once. In the following steps, JAWIB_API_KEY means this customer token, not the company management token.
3. Show your customer a QR or code
With the customer key, call POST /api/v2/connections, then GET /api/v2/connections/{connection}/pairing. Render qr_data_url in your own interface, or open the temporary hosted_url. Phone-code pairing is also available.
Poll the pairing endpoint until the connection is connected. The Direct integration guide contains the complete connection requests; the same requests apply here using the customer key.
You can combine provisioning, key issuance, and pairing behind one “Connect WhatsApp” action in your application. The underlying API operations remain separate so you can track each resource and retry the supported operations safely.
4. Load that customer's chats
curl 'https://playjawib.com/api/v2/conversations?connection_id=CONNECTION_UUID' \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'
curl 'https://playjawib.com/api/v2/conversations/CONVERSATION_ID/messages?limit=50' \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'Your backend selects the key mapped to the signed-in customer's account in your application. You do not switch data boundaries by adding a customer_id query parameter, and the company management key does not automatically read customer chats.
5. Route incoming events
Register webhooks with the customer's key and retain their signing secret. After signature verification, use your endpoint mapping and the event's customer_id to route the event to the correct customer in your system. Store event IDs to prevent duplicate processing.
What to store in your application
| Value | Purpose |
|---|---|
| Your customer ID | Identify the customer in your platform. |
| Jawib customer ID | Manage that customer's account and keys. |
| Customer API key, encrypted | Authorize that customer's WhatsApp data requests. |
| Connection UUID | Select the connected WhatsApp number. |
| Webhook signing secret, encrypted | Verify events before routing them to the customer. |
A customer account is not a message recipient. Use to when sending a private message. Captured chat content is available only after capture is enabled and within its retention period.