Autonomo AI API Documentation

Welcome to the API documentation for Autonomo AI's WhatsApp API

Autonomo AI's Incoming WhatsApp Webhook

POST /webhook/whatsapp

This endpoint is where Autonomo AI receives incoming messages from WhatsApp (after potentially being processed or adapted from a provider like WAHA). It forwards the message content to an LLM service for processing and sends the generated reply back to the user via WhatsApp.

Security: This endpoint requires an X-API-Key header with a valid API key for authentication, which is internal to Autonomo AI's system.

Request Body (JSON):

The webhook expects a JSON payload containing message details. The critical fields are message.from (sender's ID) and message.text (message content). This format is often a simplified representation after initial parsing from a WhatsApp gateway like WAHA.

{
  "message": {
    "from": "whatsapp:+1234567890",
    "text": "Hello, can you help me with something?"
  },
  "//": "Other fields like 'type', 'timestamp', etc., might be present but are not processed by this webhook if not explicitly documented."
}

Request Headers:

Parameters (in JSON body):

Responses:

200 OK: The webhook successfully received and authenticated the message. The reply will be sent asynchronously.

{
  "status": "ok"
}

400 Bad Request: The payload was invalid or missing required fields.

{
  "error": "Invalid payload"
}

401 Unauthorized: The X-API-Key header was missing or invalid.

{
  "success": false,
  "message": "Unauthorized: Invalid or missing API Key."
}

WAHA Incoming Webhook Formats

This section describes the various JSON payloads that Autonomo AI's backend expects to receive from a configured WAHA instance's webhook, corresponding to different types of WhatsApp events. Autonomo AI's /webhook/whatsapp endpoint would then parse these and potentially convert them to its internal message format for processing.

Text Message Event (event: "message")

Triggered when a user sends a standard text message to the WhatsApp number linked with WAHA.

Example Webhook Payload:

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "from": "11111111111@c.us",
    "fromMe": false,
    "to": "11111111111@c.us",
    "body": "Hi there!",
    "hasMedia": false,
    "ack": 1,
    "vCards": [],
    "_data": {
      "//": "Internal WAHA data"
    }
  }
}

Payload Fields:

Message Reaction Event (event: "message.reaction")

Triggered when a user adds, removes, or changes an emoji reaction to a message.

Example Webhook Payload:

{
    "event": "message.reaction",
    "session": "default",
    "me": {
        "id": "79222222222@c.us",
        "pushName": "WAHA"
    },
    "payload": {
        "id": "false_79111111@c.us_11111111111111111111111111111111",
        "from": "79111111@c.us",
        "fromMe": false,
        "participant": "79111111@c.us",
        "to": "79111111@c.us",
        "timestamp": 1710481111.853,
        "reaction": {
            "text": "🙏",
            "messageId": "true_79111111@c.us_11111111111111111111111111111111"
        }
    },
    "engine": "WEBJS",
    "environment": {
        "version": "2024.3.3",
        "engine": "WEBJS",
        "tier": "PLUS",
        "browser": "/usr/bin/google-chrome-stable"
    }
}

Payload Fields:

Media Message Event (event: "message")

Triggered when a user sends any type of media (image, video, audio, document) to the WhatsApp number linked with WAHA.

Example Webhook Payload:

{
  "event": "message",
  "session": "default",
  "payload": {
    "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "timestamp": 1667561485,
    "body": "Check this out (caption for the media)!",
    "from": "11111111111@c.us",
    "hasMedia": true,
    "media": {
      "url": "http://localhost:3000/api/files/true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.jpg",
      "mimetype": "image/jpeg",
      "filename": null,
      "error": null
    }
  }
}

Payload Fields:

Sending Messages via WAHA API (Outgoing)

To send messages and manage chat presence on WhatsApp, Autonomo AI leverages the WAHA API. This section outlines the recommended process and specific API endpoints to ensure compliant and human-like interaction and to avoid being flagged as spam by WhatsApp.

Important Guidelines: How to Process Messages

When processing messages in your bot, it’s important to follow certain steps to avoid being flagged as spam. Here’s a recommended process to follow:

  1. Send seen before processing the message. This can be done by sending a POST /api/sendSeen/ request to the WAHA API.
  2. Start typing before sending a message and wait for a random interval depending on the size of the message. This can be done by sending a POST /api/startTyping/ request.
  3. Stop typing before sending the message. This can be done by sending a POST /api/stopTyping/ request.
  4. Send the text message using the POST /api/sendText request.

By following these steps, you can ensure that your bot processes messages in a way that’s compliant with WhatsApp’s guidelines and reduces the risk of being blocked.

Send Seen

POST /api/sendSeen

Sends a "seen" (read) receipt for all unread messages in a given chat. This is crucial for avoiding blocking and mimicking human behavior.

Request Body (JSON):

{
  "session": "default",
  "chatId": "11111111111@c.us"
}

Parameters (in JSON body):

Responses:

200 OK: Request to send seen receipt was accepted.

{
  "success": true,
  "message": "Seen receipt sent"
}

400 Bad Request: Invalid chatId or missing parameters.

{
  "success": false,
  "message": "Invalid chatId provided."
}

Start Typing

POST /api/startTyping

Sets the chat presence to "typing" for a specified duration, indicating that the bot is preparing a response. This makes interactions feel more natural.

Request Body (JSON):

{
  "session": "default",
  "chatId": "111111111@c.us",
  "presence": "typing"
}

Parameters (in JSON body):

Responses:

200 OK: Typing presence initiated.

{
  "success": true,
  "message": "Typing presence set to 'typing'"
}

Stop Typing

POST /api/stopTyping

Resets the chat presence from "typing" back to "paused" or normal, typically done just before sending the actual message.

Request Body (JSON):

{
  "session": "default",
  "chatId": "111111111@c.us",
  "presence": "paused"
}

Parameters (in JSON body):

Responses:

200 OK: Typing presence stopped.

{
  "success": true,
  "message": "Typing presence set to 'paused'"
}

Send Text Message

POST /api/sendText

Sends a standard text message to a specified WhatsApp chat.

Request Body (JSON):

{
  "session": "default",
  "chatId": "11111111111@c.us",
  "message": "This is your reply from Autonomo AI!"
}

Parameters (in JSON body):

Responses:

200 OK: Message successfully queued for sending.

{
  "success": true,
  "message": "Message sent successfully",
  "id": "true_11111111111@c.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

400 Bad Request: Invalid chatId or missing message content.

{
  "success": false,
  "message": "Invalid message or chatId provided."
}

500 Internal Server Error: An error occurred on the WAHA server.

{
  "success": false,
  "message": "Failed to send message due to an internal server error."
}