What is a WhatsApp instance?
A WhatsApp instance is a WhatsApp number connected to an API. Each instance has its own active session, its own identifier (ID), its own credentials and its own settings, and works separately from the others. If you have three numbers, you have three instances. It is the unit you use to create, connect, monitor and bill any API operation.
Published on · 2 min read
How an instance works
You create the instance in the dashboard, and it gets an ID. Then you pair the number by scanning a QR code with your phone, the same way you connect WhatsApp Web. From then on the instance stays connected on a server and can send messages, receive messages through a webhook and report its status.
On ZapZap, the instance ID is part of the address of every call and authentication uses an account key and secret. The step by step is in the quick start and in authentication.
What lives inside an instance
Each instance holds the connected number, the connection state (connected or disconnected), the webhook URL that receives events and its own settings, such as the automation attached to that number. Each instance has its own session, so a disconnection on one number does not disconnect the others.
What changes between providers is the billing model: on ZapZap each active number costs R$15 per month, prepaid, with no per-message fee. See pricing for the current value.
How many instances do I need
One per WhatsApp number you want to operate. A clinic with reception and billing on different numbers uses two. An agency serving ten clients, each with their own number, uses ten.
Splitting by function, such as support, sales and billing, also helps: if one number has a problem, the others keep running. And it is worth having a spare number, because no number is irreplaceable. See the glossary for the other terms, or the guide on the unofficial WhatsApp API for context.
Quick summary
- An instance is a WhatsApp number connected to an API, with its own session, ID, credentials and webhook.
- You create the instance in the dashboard and pair the number by QR code, as with WhatsApp Web.
- One instance per number. Splitting by function isolates problems and keeps the rest of the operation running.
Keep reading
Also read
Frequently asked questions
Is an instance the same as a WhatsApp account?
Not exactly. The account is your number on WhatsApp. The instance is that number's connection to the API: the active session on the server, with an ID, credentials and a webhook. A number connected to an API becomes an instance.
Does my phone need to stay on for the instance to work?
You use the phone to scan the QR code and pair the number. After that the session runs on the server. If WhatsApp asks you to reconnect, you will need to scan the QR code again.
What happens when an instance disconnects?
Messages stop being sent and received through that instance until the number is reconnected, usually by scanning the QR code again. The other instances are not affected.
Can I have more than one instance on the same account?
Yes. Each active number is an instance, and the same account can have several, each with its own ID and webhook.
Create your first instance and connect by QR code
Create the account, verify your phone and get the welcome credit, with no deposit (one per phone, subject to the current campaign). In a few minutes you have a connected instance.