Skip to content
JawibDocumentationWHATSAPP API · v2
Documentation/Direct integration

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.

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