WAHA Skill

This skill provides comprehensive knowledge and patterns for working with WAHA (WhatsApp HTTP API), a self-hosted API that automates WhatsApp Web.

Core Concepts

1. Authentication

WAHA typically uses an API Key (if configured) or no authentication by default in local/dev environments.

• •Header: X-Api-Key: YOUR_API_KEY (if enabled)

2. Session Management

WAHA is session-based. Each session represents one WhatsApp account.

• •List Sessions: GET /api/sessions?all=true
• •Start Session: POST /api/sessions/start
• •Logout/Stop: POST /api/sessions/stop or POST /api/sessions/logout
• •Get QR Code:
  • •GET /api/{session}/auth/qr (Returns JSON with QR data)
  • •GET /api/screenshot (Useful for visual debugging)

3. Messaging

• •Send Text: POST /api/sendText
  • •Payload: { "chatId": "number@c.us", "text": "message", "session": "default" }
• •Send Media: POST /api/sendMedia
  • •Supports image, document, video via URL or local file path.
• •Check Number: GET /api/{session}/contacts/check-exists?phone=number

4. Webhooks

WAHA sends POST requests to your configured URL for events.

• •Event Types: message, message.any, session.status, qr.
• •Payload: Typically includes data about the message and the session name.

Code Example (Axios)

import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:3000',
  // headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});

// Start a session
const startSession = async (name: string) => {
  const { data } = await api.post('/api/sessions/start', { name });
  return data;
};

// Send a simple text message
const sendMessage = async (session: string, chatId: string, text: string) => {
  const { data } = await api.post('/api/sendText', {
    session,
    chatId,
    text
  });
  return data;
};

Best Practices

1. •Session Persistence: Ensure WAHA is configured with a persistent store (e.g., file system or MongoDB) so sessions remain after restart.
2. •Handle QR Code Expiration: QR codes expire quickly. Re-fetch if not scanned within the timeout.
3. •chatId Format: WhatsApp IDs use @c.us for contacts and @g.us for groups.
4. •Security: Secure your WAHA instance with an API key and avoid exposing the Swagger UI publicly without protection.