Direct integration
Use this flow when your application accesses WhatsApp numbers owned by your Jawib account. You do not need to provision customers first.
Connection flow
Your account's API key
↓
Create a connection
↓
Retrieve QR or phone code → Number owner pairs WhatsApp
↓
Connection becomes connected
↓
Your application sends messages and receives conversations
1. Prepare your key
Store your account's token on your backend as JAWIB_API_KEY. Include connections:pair and connections:read for pairing. Add conversations:read for chat history, media:read for media downloads, and the messaging and webhook scopes your integration uses.
2. Start pairing
curl --request POST 'https://playjawib.com/api/v2/connections' \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: connect-number-123' \
--data '{
"name": "My WhatsApp connection",
"method": "qr",
"privacy_accepted": true,
"inbox_enabled": true,
"group_inbox_enabled": false
}'Save the UUID from data.id as your connection ID. Only set privacy consent and capture flags after obtaining the number owner's authorization.
3. Display QR or a phone code
curl 'https://playjawib.com/api/v2/connections/CONNECTION_UUID/pairing' \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'When available, data.qr_data_url contains a PNG data URL that your frontend can render. Alternatively, open the temporary data.hosted_url. Your backend retains the API key; it sends only the temporary pairing data to the authorized frontend.
For phone-code pairing, create the connection with method: code and phone in international format without a plus sign. The pairing response returns data.code when ready.
Poll the pairing endpoint every few seconds until data.status becomes connected, then stop polling. If the attempt expires, start a new one.
4. Retrieve conversations and messages
# List captured conversations for this connection.
curl 'https://playjawib.com/api/v2/conversations?connection_id=CONNECTION_UUID' \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'
# Retrieve retained messages from one conversation.
curl 'https://playjawib.com/api/v2/conversations/CONVERSATION_ID/messages?limit=50' \
--header "Authorization: Bearer $JAWIB_API_KEY" \
--header 'Accept: application/json'Use the conversation ID returned by the first request. For media, use the message's media-download endpoint from your backend with media:read.
Pairing does not import the phone's complete historical archive. The API exposes content captured after inbox activation, subject to retention and supported message types.
5. Receive updates
Configure a signed HTTPS webhook in the same account boundary. Subscribe to message.received for inbound private messages, message.outbound for outgoing synchronization, and message-status events for delivery and reading.
Your application decides how to display chats, process messages, or use automation. Use the Conversations, Messages, Groups, and Webhooks references for the corresponding endpoint contracts.