---
name: evolution-api
description: Manage connection, creation, deletion and messaging workflows for WhatsApp using Evolution API v2.
---

# Evolution API v2 Integration & Troubleshooting Skill

This guide outlines how to configure, connect, and troubleshoot WhatsApp integration using Evolution API (v2.x.x) across SaaS environments.

## 1. Instance Creation Payload (Evolution API v2)
When creating a WhatsApp instance via `POST /instance/create`, the endpoint requires specific fields. In version **v2.3.x or higher**, the parameter `"integration": "WHATSAPP-BAILEYS"` is **mandatory**. Omitting it will result in a `400 Bad Request` with the error `Invalid integration`.

### Request Configuration:
- **Method**: `POST`
- **URL**: `https://<evolution_url>/instance/create`
- **Headers**:
  - `apikey`: `<global_api_key>`
  - `Content-Type`: `application/json`
- **Body**:
```json
{
  "instanceName": "microtecflix",
  "token": "optional_custom_token",
  "qrcode": true,
  "integration": "WHATSAPP-BAILEYS"
}
```

---

## 2. Checking Connection State
To check if the WhatsApp instance is connected:
- **Method**: `GET`
- **URL**: `https://<evolution_url>/instance/connectionState/<instanceName>`
- **Headers**: `apikey: <global_api_key>`
- **Response**: Returns the state (e.g., `open`, `connecting`, `closed`).
  - If it returns `open`, the device is successfully paired.

---

## 3. Retrieving the QR Code
To fetch the QR code for scanning:
- **Method**: `GET`
- **URL**: `https://<evolution_url>/instance/connect/<instanceName>`
- **Headers**: `apikey: <global_api_key>`
- **Response**: Returns a JSON containing `{ base64: "data:image/png;base64,...", pairingCode: "..." }`. Display this `base64` image on the frontend.

---

## 4. Troubleshooting: "Não foi possível conectar o dispositivo" / Connection Failure
A common error during QR code scanning is `Não foi possível conectar o dispositivo` on the phone, while the API is stuck. This is caused by a corrupted Baileys session cache in the Evolution API container.

### Resolution Steps:
1. **Do not use logout only**: Just running `DELETE /instance/logout/<instanceName>` only closes the current session but leaves the corrupted files on the server.
2. **Delete the Instance**: Completely remove the instance from the server using the delete endpoint:
   - **Method**: `DELETE`
   - **URL**: `https://<evolution_url>/instance/delete/<instanceName>`
   - **Headers**: `apikey: <global_api_key>`
3. **Re-create and Re-scan**: Call the create endpoint (`POST /instance/create`) again with the Baileys integration. This allocates a clean session directory, generating a fresh QR Code that scans instantly.

---

## 5. Reference Implementation (Node.js/Express)

```typescript
import axios from 'axios';

async function getQRCode(apiUrl: string, apiKey: string, instance: string) {
  const headers = { apikey: apiKey };

  // 1. Check connection state
  try {
    const stateRes = await axios.get(`${apiUrl}/instance/connectionState/${instance}`, { headers });
    if (stateRes.data?.instance?.state === 'open') {
      return { connected: true };
    }
  } catch (err: any) {
    if (err.response?.status === 404) {
      // 2. Automatically create instance if not found
      await axios.post(`${apiUrl}/instance/create`, {
        instanceName: instance,
        qrcode: true,
        integration: 'WHATSAPP-BAILEYS'
      }, { headers });
    } else {
      throw err;
    }
  }

  // 3. Fetch fresh connection QR Code
  const connectRes = await axios.get(`${apiUrl}/instance/connect/${instance}`, { headers });
  return {
    connected: false,
    qrCode: connectRes.data.base64 || connectRes.data.qrcode || null
  };
}

async function resetInstance(apiUrl: string, apiKey: string, instance: string) {
  const headers = { apikey: apiKey };
  // Completely delete the instance to wipe the Baileys session cache
  await axios.delete(`${apiUrl}/instance/delete/${instance}`, { headers });
}
```