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"
  }'

const response = await fetch("https://api.wappfy.io/api/instances", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My WhatsApp",
    type: "waha",
  }),
});

const instance = await response.json();
console.log(instance.data.id); // use this ID for all subsequent calls

Reponse :

{
  "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"

Reponse :

{
  "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"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/qr",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
// data.qr contains a base64-encoded QR code image

Reponse :

{
  "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.

Ouvrez l’image du QR code et scannez-la avec WhatsApp > Appareils connectes > Connecter un appareil sur votre telephone. Une fois scanne, le statut de l’instance passera a 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"

Reponse :

{
  "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"

Reponse :

{
  "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.

Premiers Pas

Guides

Gestion des instances

Gestion des instances

Types d’instances

Valeurs de statut des instances

Vue d’ensemble du cycle de vie

Creer une instance

Connecter une instance

Obtenir le QR code

Verifier le statut de l’instance

Lister toutes les instances

Deconnecter une instance

Redemarrer une instance

Deconnecter un compte WhatsApp (Logout)

Supprimer une instance

Exemple complet du cycle de vie

Gestion des erreurs

​Gestion des instances

​Types d’instances

​Valeurs de statut des instances

​Vue d’ensemble du cycle de vie

​Creer une instance

​Connecter une instance

​Obtenir le QR code

​Verifier le statut de l’instance

​Lister toutes les instances

​Deconnecter une instance

​Redemarrer une instance

​Deconnecter un compte WhatsApp (Logout)

​Supprimer une instance

​Exemple complet du cycle de vie

​Gestion des erreurs

Gestion des instances

Types d’instances

Valeurs de statut des instances

Vue d’ensemble du cycle de vie

Creer une instance

Connecter une instance

Obtenir le QR code

Verifier le statut de l’instance

Lister toutes les instances

Deconnecter une instance

Redemarrer une instance

Deconnecter un compte WhatsApp (Logout)

Supprimer une instance

Exemple complet du cycle de vie

Gestion des erreurs