Evolution API Skill

This skill provides comprehensive knowledge and patterns for working with the Evolution API, an open-source WhatsApp integration API.

Core Concepts

1. Authentication

Evolution API uses a global apikey for most operations. This key should be passed in the apikey header.

• •Header: apikey: YOUR_GLOBAL_API_KEY

2. Instance Lifecycle

• •Create Instance: POST /instance/create
  • •Integration: WHATSAPP-BAILEYS (default)
  • •Options: qrcode, rejectCall, msgCall, groupsIgnore, alwaysOnline, etc.
• •Connect/QR Code: GET /instance/connect/{instanceName}
• •Status: GET /instance/connectionState/{instanceName}
• •Logout: DELETE /instance/logout/{instanceName}
• •Delete: DELETE /instance/delete/{instanceName}
• •Restart: PUT /instance/restart/{instanceName}

2.1. Instance Settings

• •Update Settings: POST /settings/set/{instanceName}
  • •Update: rejectCall, msgCall, groupsIgnore, alwaysOnline, readMessages, readStatus
• •Get Settings: GET /settings/find/{instanceName}
  • •Returns current instance settings

3. Messaging

• •Send Text: POST /message/sendText/{instanceName}
  • •Payload: { "number": "target", "text": "message", "delay": 1200 }
• •Send Media: POST /message/sendMedia/{instanceName}
  • •Supports: image, video, audio, document
• •Send Audio (PTT): POST /message/sendWhatsAppAudio/{instanceName}

4. Webhooks

Configure webhooks to receive real-time notifications for events like MESSAGES_UPSERT, CONNECTION_UPDATE, etc.

• •Set Webhook: POST /webhook/set/{instanceName}
  • •Payload includes url, enabled, and an array of events.

Code Example (Axios)

import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8080',
  headers: { 'apikey': 'YOUR_API_KEY' }
});

// List Instances
const listInstances = async () => {
  const { data } = await api.get('/instance/fetchInstances');
  return data;
};

// Send Message
const sendMessage = async (instanceName, number, text) => {
  const { data } = await api.post(`/message/sendText/${instanceName}`, {
    number,
    text
  });
  return data;
};

5. Chatwoot Integration

Evolution API has native integration with Chatwoot that automatically creates and manages inboxes.

• •Set Chatwoot: POST /chatwoot/set/{instanceName}
  • •Payload includes enabled, accountId, token, url, nameInbox, autoCreate, etc.
  • •When autoCreate: true, Evolution API automatically creates the inbox in Chatwoot
• •Get Chatwoot Config: GET /chatwoot/find/{instanceName}

Code Example (Axios)

import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8080',
  headers: { 'apikey': 'YOUR_API_KEY' }
});

// List Instances
const listInstances = async () => {
  const { data } = await api.get('/instance/fetchInstances');
  return data;
};

// Send Message
const sendMessage = async (instanceName, number, text) => {
  const { data } = await api.post(`/message/sendText/${instanceName}`, {
    number,
    text
  });
  return data;
};

// Configure Chatwoot Integration
const setChatwoot = async (instanceName, chatwootConfig) => {
  const { data } = await api.post(`/chatwoot/set/${instanceName}`, {
    enabled: true,
    accountId: chatwootConfig.accountId,
    token: chatwootConfig.token,
    url: chatwootConfig.url,
    signMsg: true,
    nameInbox: instanceName,
    reopenConversation: true,
    conversationPending: false,
    importContacts: false,
    importMessages: false,
    autoCreate: true // Automatically creates inbox in Chatwoot
  });
  return data;
};

Best Practices

1. •Always handle rate limits and delays to avoid number banning.
2. •Use Webhooks instead of polling for message updates.
3. •Secure API Keys using environment variables.
4. •Use native Chatwoot integration (/chatwoot/set) instead of manually creating inboxes - Evolution API handles inbox creation automatically when autoCreate: true.