Webhooks · Aysali Solutions

General

Webhooks send automated HTTP POST requests from Aysali Bot to a URL you define when specific events occur. Each request is JSON with a shared envelope (function, key, sender-url, data).

Configure under Settings → General → Webhooks. The help link on that setting points here.

Setup

•
Open settings
In the admin panel, go to Settings → General → Webhooks.
•
Destination URL
Enter the endpoint that should receive events. Aysali Bot sends a JSON body via POST (Content-Type: application/json).
•
Secret key
Set a Secret key. The same value is sent in every payload as key. Compare it on your server to confirm the request came from your bot instance.
•
Activate
Enable Active, save settings, and verify your endpoint receives test traffic.
•
Filter events (optional)
In Active webhooks, enter comma-separated event names (for example message-sent,login). Leave empty to allow all events listed below.

Example receiver (PHP)

$raw = file_get_contents('php://input');
$payload = json_decode($raw, true);

$secret = 'your-secret-from-settings';
if (!is_array($payload) || ($payload['key'] ?? '') !== $secret) {
    http_response_code(403);
    exit;
}

$event = $payload['function'] ?? '';
$data = $payload['data'] ?? null;
// Handle $event ...

Your endpoint can be implemented in any language; read the raw request body as JSON.

Payload envelope

Every webhook uses the same top-level shape:

Field	Description
`function`	Event name (for example `message-sent`)
`key`	Your Secret key from settings
`sender-url`	Page URL from `HTTP_REFERER` when the server sends the webhook; may be empty for some background requests
`data`	Event-specific object or scalar

Delivery uses sb_curl from the server for PHP-triggered events. Browser-triggered events call the webhooks AJAX action, which runs the same sb_webhooks() function on the server.

Event reference

`function`	When it fires
`message-sent`	A message is stored (user, agent, or external channel such as WhatsApp)
`email-sent`	A notification email is sent to a user or agent
`new-messages`	New messages arrive in the visitor chat widget (not external channels — use `message-sent` for those)
`rich-message`	A rich message form is submitted (registration, follow-up email, buttons with inputs, etc.)
`new-conversation`	The visitor receives a new conversation in the widget
`new-conversation-created`	A conversation row is created on the server
`conversation-status-updated`	Conversation status code changes
`login`	Successful login from the chat login form
`registration`	Successful registration (including updates via a rich-message registration form)
`user-deleted`	A user is deleted from the admin Users area
`new-email-address`	Email captured via follow-up, subscribe, or email rich message
`message-deleted`	A message is deleted in the chat UI
`slack-message-sent`	A message is sent to Slack from the admin area
`bot-message`	Reserved in code; not emitted by current builds
`sms-sent`	Legacy mapping only — SMS notifications are not available in Aysali Bot

Conversation status codes

Used in conversation-status-updated and related fields:

Code	Meaning
`0`	Live
`1`	Waiting for user reply
`2`	Waiting for agent reply
`3`	Archive
`4`	Trash

message-sent

Sent when a new message is saved (widget, admin, WhatsApp, and other integrated sources).

{
  "function": "message-sent",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "user_id": "947",
    "conversation_user_id": "947",
    "conversation_id": "1057",
    "conversation_status_code": "2",
    "conversation_source": "wa",
    "message_id": "2574",
    "message": "Hello! How are you?",
    "attachments": [["name", "https://example.com/image.png"], ["name", "https://example.com/file.txt"]]
  }
}

email-sent

Sent when a notification email is delivered.

{
  "function": "email-sent",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "recipient_id": "957",
    "message": "Hello! How can I help you?",
    "attachments": [["name", "https://example.com/image.png"], ["name", "https://example.com/file.txt"]]
  }
}

new-messages

Sent from the chat widget when new messages are received in the active conversation. For WhatsApp, Instagram, and other external platforms, use message-sent instead.

{
  "function": "new-messages",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "conversation_id": "4607",
    "messages": [
      {
        "details": {
          "message": "Hello world!",
          "attachments": "",
          "payload": {},
          "status_code": "0",
          "id": "10231",
          "profile_image": "https://example.com/image.jpg",
          "first_name": "Don",
          "last_name": "John",
          "user_id": "1964",
          "user_type": "admin",
          "full_name": "Don John",
          "creation_time": "2024-04-02 16:57:19"
        }
      }
    ]
  }
}

rich-message

Sent when the user submits a rich message that collects input (follow-up email form, registration form, button forms, etc.).

{
  "function": "rich-message",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "result": true,
    "data": {
      "type": "inputs",
      "result": {
        "name": ["Don John", "Name"],
        "your-email": ["[email protected]", "Your Email"],
        "site-url": ["www.example.com", "Site URL"]
      }
    },
    "id": "example"
  }
}

new-conversation

Sent in the visitor widget when a new conversation appears for the user. The function value is new-conversation (not new-conversation-received).

{
  "function": "new-conversation",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "messages": [
      {
        "id": "10222",
        "user_id": "4746",
        "message": "Hi there!",
        "creation_time": "2024-04-02 07:26:18",
        "attachments": "",
        "status_code": "0",
        "payload": "",
        "conversation_id": "4605",
        "first_name": "User",
        "last_name": "#19332",
        "profile_image": "https://example.com/image.png",
        "user_type": "lead"
      }
    ],
    "details": {
      "user_id": "4746",
      "first_name": "User",
      "last_name": "#19332",
      "profile_image": "https://example.com/image.png",
      "user_type": "lead",
      "id": "4605",
      "title": "",
      "status_code": "0",
      "creation_time": "2024-04-02 07:26:17",
      "department": null,
      "agent_id": null,
      "source": null,
      "extra": null,
      "tags": null,
      "busy": false
    }
  }
}

new-conversation-created

Sent on the server when a conversation record is created (same data shape as new-conversation in typical flows).

{
  "function": "new-conversation-created",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "messages": [],
    "details": {
      "id": "4605",
      "user_id": "4746",
      "status_code": "0",
      "creation_time": "2024-04-02 07:26:17"
    }
  }
}

conversation-status-updated

{
  "function": "conversation-status-updated",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "conversation_id": "1057",
    "status_code": "0"
  }
}

Sent only after a successful login from the chat login form.

{
  "function": "login",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "details": {
      "id": "18",
      "profile_image": "https://example.com/avatar.png",
      "first_name": "Fede",
      "last_name": "",
      "email": "[email protected]",
      "user_type": "user",
      "token": "ec83c134e5d53be98abd0025145473eec0ff814e",
      "url": "https://your-bot.example.com",
      "password": "$2y$10$…",
      "conversation_id": "false"
    }
  }
}

registration

Sent after successful registration, including updates submitted through a rich-message registration form.

{
  "function": "registration",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "id": "example",
    "conversation_id": "123",
    "user": {
      "first_name": ["Don", "First name"],
      "last_name": ["John", "Last name"],
      "email": ["[email protected]", "Email"],
      "password": ["********", "Password"],
      "user_type": ["user", ""]
    },
    "extra": {
      "phone": ["+02123456789", "Phone"],
      "city": ["London", "City"]
    }
  }
}

Field values are [value, label] pairs. See Registration and login.

user-deleted

data is the numeric user ID (string) of the deleted account.

{
  "function": "user-deleted",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": "951"
}

See Users — import, search, delete, and merge.

new-email-address

Sent when an email is collected via follow-up message, subscribe message, or email rich message.

{
  "function": "new-email-address",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

message-deleted

Sent when a message is deleted from the chat interface. data is the message ID.

{
  "function": "message-deleted",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": "2574"
}

slack-message-sent

Sent when an agent posts to a linked Slack channel from the admin area.

{
  "function": "slack-message-sent",
  "key": "xxxxxxxx",
  "sender-url": "https://example.com",
  "data": {
    "message": "Hello from admin",
    "conversation_id": "1057",
    "slack_channel": "C01234567"
  }
}

Email notifications — triggers email-sent
Registration and login — triggers login and registration
Rich messages — many fire rich-message