123 lines
4.5 KiB
Markdown
123 lines
4.5 KiB
Markdown
---
|
|
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. 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**:
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```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 });
|
|
}
|
|
```
|