{
"response": "Connecting",
"request_id": "5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f",
"status": {
"connected": false,
"loggedIn": false,
"jid": null
}
}Connect instance to WhatsApp
Starts the instance’s connection to WhatsApp.
- Without
phone, returns a QR Code to scan with the phone. - With
phone, returns a pairing code for that number.
The instance remains in connecting until pairing is confirmed or the
timeout expires. Track progress via GET /instance/status; do not repeat the
call while the process is in progress.
After connecting, the available history starts arriving through the
history event and can be queried via POST /message/find and POST /chat/find.
The response may include request_id at the top level, even before the QR code
or pairing code is read. Keep this id to correlate the attempt with
the pairing’s history batches, including the completion status, and with
GET /instance/history-sync/status. It stays the same during the same
attempt and changes with each new pairing. It may be absent when there is no
pairing or tracking available.
In a new pairing, history_days chooses how many days of history the
phone sends. Without the field, with a value outside 0–365, or from 1 to 90 days, the
request is the normal history (90 days, when there is no valid value). From 91
to 365 days, or with 0 (the maximum, 365 days), the request is the full
history, larger and slower. An already paired instance reconnects without
requesting history.
To choose a connection region, first query
GET /proxy-managed/countries and GET /proxy-managed/cities and reuse the
values returned in the proxy_managed_* fields.
{
"response": "Connecting",
"request_id": "5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f",
"status": {
"connected": false,
"loggedIn": false,
"jid": null
}
}Authorizations
Body
Phone number in international format (e.g., 5511999999999). If provided, generates a pairing code. If omitted, generates a QR code.
^\d{10,15}$"5511999999999"
Browser used in the authentication/connection cycle. auto keeps a valid saved profile or picks Safari, Firefox or Edge for new connections.
auto, safari, firefox, edge, chrome "auto"
System/name displayed on the phone under linked devices. Helps identify the instance on WhatsApp; for greater stability, we recommend leaving it blank and using the default value of the chosen browser.
"My Company"
Desired country for the regional proxy, in lowercase ISO alpha-2. Use the value returned by GET /proxy-managed/countries.
^[a-z]{2}$"br"
State/subdivision of the chosen city. When the country/city requires disambiguation, use the state field returned by GET /proxy-managed/cities?country=br.
"sp"
City chosen for the regional proxy. Always use the value field returned by GET /proxy-managed/cities.
"campinas"
Days of history requested from the phone during pairing.
- Absent: 90 days, via normal history.
- From
1to90: the last N days, via normal history. - From
91to365: the last N days, via full history. 0: the maximum, 365 days via full history.- Outside 0–365: ignored; the 90 days apply.
Only applies to a new pairing. An already paired instance reconnects without requesting history, and an already generated QR code or code keeps what was requested. The phone decides what it sends: the days are a requested limit, not a guarantee.
0 <= x <= 36590
Response
Success
Current connection status
false
Login status
false
WhatsApp ID (when logged in)
null
Full instance details
Show child attributes
Show child attributes
{ "id": "i91011ijkl", "token": "abc123xyz", "status": "connected", "paircode": "1234-5678", "qrcode": "data:image/png;base64,iVBORw0KGg...", "name": "Instância Principal", "profileName": "Loja ABC", "profilePicUrl": "https://example.com/profile.jpg", "isBusiness": true, "plataform": "Android", "systemName": "WppFy", "owner": "user@example.com", "lastDisconnect": "2025-01-24T14:00:00Z", "lastDisconnectReason": "Network error", "adminField01": "custom_data", "openai_apikey": "sk-...xyz", "chatbot_enabled": true, "chatbot_ignoreGroups": true, "chatbot_stopConversation": "parar", "chatbot_stopMinutes": 60, "created": "2025-01-24T14:00:00Z", "updated": "2025-01-24T14:30:00Z", "currentPresence": "available" }
Identifier of the pairing attempt and its initial history. Optional; it is the same one reported in the history events and in GET /instance/history-sync/status.
"5f0c2a8e-6d1b-4c3a-9e7f-1a2b3c4d5e6f"