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

name	description
evolution-api	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:

{
  "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. Sending a Text Message (v2.x.x Payload Schema)

In Evolution API v2, the POST /message/sendText/<instanceName> endpoint expects a simplified body structure compared to v1.

• Method: POST
• URL: https://<evolution_url>/message/sendText/<instanceName>
• Headers:
  • apikey: <global_api_key>
  • Content-Type: application/json
• Body:

{
  "number": "5585981145217",
  "text": "Your message here",
  "delay": 1200
}

Note: Do not use the legacy textMessage or options wrappers (like { options: { delay: 1200 }, textMessage: { text: "..." } }), as these will return a 400 Bad Request in v2.

---

5. 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.

---

6. Reference Implementation (Node.js/Express)

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 });
}