Create local evolution-api workspace skill for development reuse

.agents/skills/evolution-api/SKILL.md

@@ -0,0 +1,103 @@
+---
+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 });
+}
+```