Skip to content
JawibDocumentationWHATSAPP API · v2
Documentation/Partner integration

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

CredentialUsed by your backend for
Company management keyCreating customer accounts and issuing or revoking customer keys.
Customer keyPairing 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

ValuePurpose
Your customer IDIdentify the customer in your platform.
Jawib customer IDManage that customer's account and keys.
Customer API key, encryptedAuthorize that customer's WhatsApp data requests.
Connection UUIDSelect the connected WhatsApp number.
Webhook signing secret, encryptedVerify 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.

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