An instance of Evolution API is a WhatsApp number linked to your server. With the Baileys integration it is linked the way you link a computer to WhatsApp Web: you ask the API for a QR code and scan it with the phone. When the link drops, scanning another QR usually fixes it. This article shows how, and how to tell why it dropped before you try again.
The exact requests (routes, fields and response format) are in the project’s official documentation, and they change between versions. What follows is the sequence, not the syntax.
Linking a new instance
| 1 |
Create the instance. It is a request authenticated with the API key (AUTHENTICATION_API_KEY) that names the instance and picks the integration. Choose Baileys to link by QR. The documentation says what the request carries.
|
|
| 2 |
Ask for the connection. The API returns the QR code. In versions that support it, the documentation also describes a pairing code, which you type into the phone instead of scanning.
|
|
| 3 |
Show the QR and scan it quickly. The code expires fast and the API replaces it. If the screen is slow, ask for another. If you receive it as encoded text rather than an image, the documentation explains how to turn it into one.
|
|
| 4 |
On the phone, open WhatsApp, go to settings, choose linked devices and link a device. Point the camera at the QR.
|
|
| 5 |
Check the state. Ask the API for the connection state. While it says “connecting”, it has not linked yet. When it moves to the connected state (the exact name is in the documentation), you can send. See sending your first message.
|
|
|
The QR gives access to the number. Whoever scans it can send messages as you. Do not leave it on a public page, in a group chat or in a saved screenshot. If you showed it to someone you should not have, end the session under linked devices on the phone.
|
When the connection drops
| Cause |
How it shows |
What to do |
| Removed from linked devices |
You removed the session on the phone, or WhatsApp ended it. |
Scan a new QR. The old session cannot be recovered. |
| The phone was offline for a long time |
WhatsApp unlinks devices when the phone stays off the internet for too long. |
Get the phone online and scan a new QR if it asks. |
| The sessions were lost |
After a restart or an update the instance no longer exists. |
The persistent volume was missing. See PostgreSQL and Redis. |
| It sits on “connecting” |
The QR never links and the service keeps restarting. |
See the instance stuck on “connecting”. |
| The number was banned |
The phone shows a WhatsApp notice and no QR will help. |
It is the Baileys risk. Do not push: see the risk and the rules. |
Reconnecting without losing time
| 1 |
State first. Ask the API what state the instance is in before touching anything.
|
|
| 2 |
Then the logs. docker compose logs -f tells you whether the fault is the session, the network or the service.
|
|
| 3 |
Asking for another connection is usually enough if the instance exists but is disconnected.
|
|
| 4 |
Only if that fails, delete the instance and create it again, with the documentation open. You will need to scan a new QR.
|
|
|
Avoid unlinking and relinking the same number over and over. Repeated attempts look like suspicious behaviour, and WhatsApp may react. If the connection will not stay up, look for the cause instead of repeating.
|
|
Need another server for your instances? Have a look at the VPS plans.
See VPS servers
|
RECOMMENDED PRODUCT Web hosting with cPanel Domain and SSL included, daily backups and the panel you already know. from ₦9.900,00/mo (3-year plan, with coupon) See plans |
Angola
Brasil
Kenya
Moçambique
Nigeria
Portugal
South Africa
United Kingdom
United States
International
