Webhooks

Webhooks allow you to extend WBOT's functionality by integrating it with your own applications or services. When a message is received, WBOT can send the message data to a URL you specify, allowing you to perform custom actions like logging to a database, triggering other APIs, or generating dynamic responses.

Webhook Logic Flow

WBOT can trigger webhooks at two different levels: globally for every message, or specifically when a certain rule is matched.

graph TD
    A[Incoming Message] --> B{Is global webhook configured?}
    B -- Yes --> C[POST to global webhook]
    B -- No --> D{Find matching rule}
    C --> D
    D -- Found --> E{Does the rule have a webhook?}
    E -- Yes --> F[POST to rule's webhook]
    E -- No --> G[Send configured response]
    F --> G
    D -- Not Found --> H[Send `noMatch` response]

Global vs. Rule-Specific Webhooks

• Global Webhook: Set the webhook URL in the appconfig section of bot.json. This webhook is called for every incoming message the bot receives.

  "appconfig": {
      "webhook": "https://your-server.com/global-handler"
  }

• Rule-Specific Webhook: Add a webhook URL inside a specific rule object in the bot array. This webhook is called only when that rule is matched.

  {
      "contains": ["order"],
      "response": "Please wait",
      "webhook": "https://your-server.com/order-handler"
  }

Payload Format

When a webhook is triggered, WBOT sends an HTTP POST request with a JSON body containing the message details:

{
    "text": "The content of the message",
    "type": "message",
    "user": "1234567890@c.us"
}

Expected Response Format

Your webhook server can optionally return a JSON response to make the bot send one or more replies. The response should be an array of objects.

Text-Only Response

[
  {
    "text": "This is a dynamic reply from the webhook!",
    "type": "message"
  }
]

Response with File Attachment

To send a file, include a files array. Each file object needs a name and the file content as a base64 encoded string.

[
  {
    "text": "Here is the document you requested.",
    "type": "message",
    "files": [
      {
        "name": "document.pdf",
        "file": "<Base64-string-of-the-file>"
      }
    ]
  }
]

Example Implementations

Node.js (Express)

Here is a simple Express server that listens for webhook calls.

const express = require('express');
const app = express();
const port = 3001;

// Enable JSON body parsing
app.use(express.json());

app.post('/api/incoming-webhook', (req, res) => {
    console.log('Received webhook data:', req.body);

    // Example: send a dynamic reply
    const replyText = `You said: ${req.body.text}`;

    res.json([
        {
            "text": replyText,
            "type": "message"
        }
    ]);
});

app.listen(port, () => console.log(`Webhook server listening on port ${port}!`));

PHP

Here is a basic PHP script to handle webhook requests.

<?php
header("Content-Type: application/json");

// Get the raw POST data
$json_data = file_get_contents("php://input");
$data = json_decode($json_data);

$message = $data->text;
$response = [];

if ($message == 'hi') {
    $response[] = ['text' => 'Hello from your PHP webhook!', 'type' => 'message'];
}

echo json_encode($response);
?>