Gestion des instances
Une instance represente un numero WhatsApp unique connecte a Wappfy. Chaque instance suit un cycle de vie : creation, connexion, scan du QR code, utilisation, puis eventuellement deconnexion ou suppression.
Types d’instances
Wappfy prend en charge deux fournisseurs :
| Type | Description |
|---|
waha | API WhatsApp Web auto-hebergee via WAHA Plus. Support complet des fonctionnalites, y compris les groupes, les etiquettes et les contacts. |
cloud_api | API Cloud WhatsApp Business officielle de Meta. Necessite un compte Meta Business. |
Valeurs de statut des instances
Tout au long de son cycle de vie, une instance transite par ces statuts :
| Statut | Description |
|---|
created | L’enregistrement de l’instance existe mais n’a pas encore ete demarre. |
starting | L’instance est en cours de demarrage et d’initialisation de la session WhatsApp. |
scan_qr | L’instance attend que vous scanniez le QR code avec votre telephone. |
connected | La session WhatsApp est active et prete a envoyer/recevoir des messages. |
disconnected | La session a ete arretee ou a perdu la connexion. Peut etre reconnectee. |
failed | L’instance a rencontre une erreur lors du demarrage ou de la connexion. |
Vue d’ensemble du cycle de vie
Creer une instance
Creez une nouvelle instance WhatsApp liee a votre compte.
curl -X POST https://api.wappfy.io/api/instances \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My WhatsApp",
"type": "waha"
}'
{
"data": {
"id": "inst_abc123",
"name": "My WhatsApp",
"type": "waha",
"status": "created",
"created_at": "2026-02-10T12:00:00Z"
}
}
Connecter une instance
Demarrez la session WhatsApp. L’instance passera au statut starting puis a scan_qr.
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": {
"id": "inst_abc123",
"status": "starting"
}
}
Obtenir le QR code
Une fois que l’instance atteint le statut scan_qr, recuperez le QR code pour le scanner avec votre telephone.
curl https://api.wappfy.io/api/instances/inst_abc123/qr \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": {
"qr": "data:image/png;base64,iVBORw0KGgo..."
}
}
Le QR code expire apres environ 60 secondes. S’il expire avant que vous ne le scanniez, appelez a nouveau l’endpoint pour obtenir un nouveau code.
connected.
Verifier le statut de l’instance
Interrogez l’endpoint de statut pour savoir quand l’instance est prete.
curl https://api.wappfy.io/api/instances/inst_abc123/status \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": {
"id": "inst_abc123",
"status": "connected",
"phone_number": "5511999998888"
}
}
Au lieu d’interroger periodiquement, configurez un webhook pour les evenements instance.connected et instance.qr afin d’etre notifie en temps reel.
Lister toutes les instances
Recuperez toutes les instances de votre compte.
curl https://api.wappfy.io/api/instances \
-H "X-Api-Key: YOUR_API_KEY"
{
"data": [
{
"id": "inst_abc123",
"name": "My WhatsApp",
"type": "waha",
"status": "connected"
},
{
"id": "inst_def456",
"name": "Support Line",
"type": "waha",
"status": "disconnected"
}
]
}
Deconnecter une instance
Arretez la session WhatsApp sans supprimer l’instance. Vous pourrez vous reconnecter plus tard.
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
-H "X-Api-Key: YOUR_API_KEY"
Redemarrer une instance
Redemarrez la session WhatsApp. Cela est utile si l’instance est en etat failed ou se comporte de maniere inattendue.
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
-H "X-Api-Key: YOUR_API_KEY"
Le redemarrage preserve la session WhatsApp liee. Vous n’aurez pas besoin de scanner a nouveau le QR code.
Deconnecter un compte WhatsApp (Logout)
Deconnectez-vous completement de WhatsApp. Cela dissocie le telephone de la session. Vous devrez scanner a nouveau le QR code pour vous reconnecter.
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
-H "X-Api-Key: YOUR_API_KEY"
Le logout supprime completement le lien WhatsApp. Contrairement a la deconnexion, vous devez scanner un nouveau QR code pour reutiliser cette instance.
Supprimer une instance
Supprimez definitivement une instance et toutes les donnees associees.
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
-H "X-Api-Key: YOUR_API_KEY"
Cette action est irreversible. Tous les messages, webhooks et configurations associes a cette instance seront definitivement supprimes.
Exemple complet du cycle de vie
Voici un exemple complet qui cree une instance, la connecte et recupere le QR code :
# 1. Creer l'instance
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Production", "type": "waha"}')
INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Created instance: $INSTANCE_ID"
# 2. Connecter l'instance
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
-H "X-Api-Key: YOUR_API_KEY"
# 3. Attendre un moment, puis recuperer le QR code
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
-H "X-Api-Key: YOUR_API_KEY")
echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code saved to qr-code.png — scan it with your phone"
# 4. Interroger le statut jusqu'a la connexion
while true; do
STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
-H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.status')
echo "Status: $STATUS"
if [ "$STATUS" = "connected" ]; then
echo "Instance is connected and ready!"
break
fi
sleep 2
done
Gestion des erreurs
| Code de statut | Description |
|---|
404 | Instance non trouvee ou n’appartenant pas a votre compte. |
409 | L’instance est deja dans l’etat demande (par ex., deja connectee). |
422 | Corps de requete invalide (par ex., name manquant ou type invalide). |
429 | Limite de debit depassee. Voir Limites de debit. |
