Skip to main content

​
What is an instance?

An instance is a core concept in WhatsApp APIs. It represents a single unit of connection to WhatsApp: think of it as a “client” that talks to WhatsApp on your behalf, letting you send and receive messages, manage contacts, and run other related operations.

​
What does an instance do?

An instance manages the communication between your application and WhatsApp. Its main responsibilities include:
  • Sending and receiving messages: an instance can send and receive text, images, audio, and other media through the API.
  • Webhooks: an instance can also fire webhooks, notifying your application about events such as incoming messages or status changes.

​
How do instances work?

Each instance is authenticated with a single phone number. Once connected, it keeps an active session with WhatsApp’s servers. That session is what lets the instance send and receive messages in real time.
  1. Authentication: to get started, the instance is authenticated with WhatsApp. This usually means scanning a QR code or using specific credentials.
  2. Keeping the connection alive: after authentication, the instance holds a persistent connection to WhatsApp. This connection has to stay active for the instance to keep working.
  3. Interacting with the API: once connected, the instance can interact with WhatsApp to run operations like sending messages, checking contact status, and more.
  4. Webhooks and events: the instance can be configured to notify your application through webhooks when certain events happen, such as a new incoming message or a change in a contact’s status.

​
Summary

Instances are essential for any application that needs to interact with WhatsApp through an API. They enable real-time two-way communication and give you the tools to handle events effectively. Understanding how to set up and maintain an instance is key to a successful WhatsApp integration.

​
Connection types

On Zapster, an instance can connect to WhatsApp in two ways: through a QR code (unofficial) or through Meta’s official API (WABA). Both use the same endpoints to send and receive messages.

​
Unofficial (QR code)

This is the default mode. You create the instance, scan the QR code (or use the pairing code), and the number is connected. Behind the scenes, Zapster keeps a persistent connection to WhatsApp’s servers. It works well for most cases: automations, chatbots, notification delivery. The trade-off is that, because it is not the official API, very high volumes or inappropriate practices can lead to restrictions on the number.

​
Official (WABA)

This uses Meta’s Cloud API, the official WhatsApp channel for businesses. The connection is done through OAuth (Embedded Signup) or a manual token. It needs no QR code and no connected device. The upsides: stability backed by Meta, no ban risk from using the API, support for message templates, and reliable delivery and read receipts. The limitations: Meta charges per conversation (pricing varies by category and country), it does not support sending to groups, and the initial setup is more involved.

​
Comparison

​
About migration

Right now it is not possible to convert an unofficial instance into a WABA one (or the other way around). This capability is in development. When it is available, the migration will be seamless: your webhooks and integrations will keep working without any changes. To decide which type to pick and how to connect a WABA instance, see the WABA connection guide and the detailed comparison.