API Documentation - Chattu | WhatsApp Marketing Bot API Reference

API Overview

This API allows you to manage WhatsApp clients, send messages, schedule campaigns, view logs, and receive real-time webhooks. All API endpoints require authentication using your API key via the x-api-key header.

Authentication

All /api/* endpoints require the x-api-key header
API usage is automatically tracked for analytics
Find your API key in account settings on the dashboard

Security & Rate Limiting

Sensitive operations: 5 attempts/hour per IP
Delete operations: 10 operations/15min per IP
Security events are logged for audit

Quick Start

Use the sidebar to navigate endpoints, or press Ctrl+K to search. Click any code example to copy it to your clipboard.

POST /api/add-number

Add a new WhatsApp client phone number. Returns a QR code for authentication if the client is not already connected.

Request Example JSON

{
  "URL": "https://example.com/api/add-number",
  "Headers": {
    "Content-Type": "application/json",
    "x-api-key": "account-api-key"
  },
  "Body": {
    "clientId": "client-id",
    "phoneNumber": "12345678901"
  }
}

Request Parameters

URL: The endpoint URL for adding a new WhatsApp number
Headers:
- Content-Type: application/json - Specifies JSON format
- x-api-key: account-api-key - Your API key for authentication
Body:
- clientId: client-id - Unique identifier for the WhatsApp client
- phoneNumber: 12345678901 - Phone number to add (without + sign)

Response Example JSON

{
  "status": "pending_auth",
  "message": "QR Code generated for authentication",
  "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS...",
  "apiKey": "client-api-key-here"
}

Response Fields

status: pending_auth - Current status of the client (pending_auth or connected)
message: string - Descriptive message about the operation result
qrCode: string - Base64 encoded QR code image (null if already connected)
apiKey: string - Client-specific API key for this WhatsApp client

Note: The response includes a QR code in base64 format when the client needs authentication. If the client is already connected, the status will be "connected" and qrCode will be null. The apiKey returned is the client-specific API key for this WhatsApp client.

POST /schedule-message

Create a scheduled message. Server time expects ISO-8601 UTC format.

Timezone: Send scheduleTime as UTC (e.g., 2025-10-06T18:30:00Z). The dashboard can convert Israel time (Asia/Jerusalem) to UTC automatically.

Request Example JSON

{
  "URL": "https://example.com/schedule-message",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Body": {
    "clientId": "client-id",
    "number": "9721234567",
    "message": "Scheduled hello",
    "scheduleTime": "2025-10-06T18:30:00Z"
  }
}

Request Parameters

clientId: string - The WhatsApp client identifier
number: string - Recipient phone number (with country code, e.g., +972)
message: string - The message text to send
scheduleTime: string - ISO-8601 UTC timestamp (e.g., 2025-10-06T18:30:00Z)

GET /scheduled-messages

List scheduled messages for the logged-in user.

Response Example JSON Array

[
  {
    "id": 1,
    "clientId": "client-id",
    "recipient": "+9721234567",
    "message": "Scheduled hello",
    "scheduleTime": "2025-10-06T18:30:00Z",
    "status": "pending",
    "createdAt": "2025-10-06T17:30:00Z",
    "sentTime": null
  }
]

Response Fields

id: number - Unique identifier for the scheduled message
clientId: string - The WhatsApp client identifier
recipient: string - Recipient phone number
message: string - The message content
scheduleTime: string - When the message will be sent (ISO-8601 UTC)
status: string - Current status (pending, sent, cancelled)
createdAt: string - When the schedule was created
sentTime: string | null - When the message was actually sent (null if not sent yet)

DELETE /scheduled-messages/:id

Cancel a pending scheduled message. This endpoint is rate limited for security.

Rate Limiting: Delete operations are limited to 10 operations per 15 minutes per IP address.

Authentication: Requires session authentication (must be logged in via dashboard).

Request Example DELETE

DELETE /scheduled-messages/123
Headers: {
  "Content-Type": "application/json"
}

Note: Replace 123 with the actual scheduled message ID. No request body required for DELETE operations.

Response Example JSON

{
  "message": "Schedule cancelled."
}

POST /api/reset-api-key

Reset your API key using your current API key and username. This endpoint does not require session authentication and can be called via API.

Security: This endpoint is rate limited to 5 attempts per hour per IP address for security purposes.

Note: This endpoint uses your current API key for authentication, not session-based auth. Use this when you have programmatic access to your API key.

{
  "URL": "https://example.com/api/reset-api-key",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Body": {
    "username": "your-username",
    "currentApiKey": "account-api-key"
  }
}

{
  "message": "API key reset successfully.",
  "newApiKey": "a1b2c3d4e5f6g7h8i9j0"
}

Rate Limiting: If you exceed the rate limit (5 attempts/hour), you'll receive a 429 status code. Wait before retrying.

DELETE /clients/:clientId

Delete a WhatsApp client permanently. This operation requires password confirmation and cannot be undone.

⚠️ Warning: This is a destructive operation that will permanently delete the client and disconnect the WhatsApp session.

Security: This endpoint requires password confirmation for security. Rate limited to 5 attempts per hour per IP.

Note: This endpoint requires session authentication (must be logged in via dashboard). Cannot be called via API key.

{
  "URL": "https://example.com/clients/client-id",
  "Method": "DELETE",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Body": {
    "password": "your-password"
  }
}

{
  "message": "Client deleted successfully."
}

Possible Error Responses:

400 Password is required

403 Invalid password or client not owned by user

404 Client not found

429 Rate limit exceeded (too many delete attempts)

POST /api/update-webhook

Update the webhook URL for a client to receive real-time event notifications.

View Request Example

{
  "URL": "https://example.com/api/update-webhook",
  "Headers": {
    "Content-Type": "application/json",
    "x-api-key": "api-key"
  },
  "Body": {
    "clientId": "client-id",
    "webhookUrl": "https://your-domain.com/webhook.php"
  }
}

Note: Setting a webhook URL enables real-time event notifications for this client. The webhook will receive POST requests for events like message_received, message_sent, and call_rejected.

Your webhook endpoint must be publicly accessible and respond within 5 seconds.

POST /api/send-message

Send a text message or a media attachment (image, video, document) to a phone number.

Note: Either a text message or media attachment must be included.

Supported file types: .jpg, .jpeg, .png, .gif, .webp, .pdf, .mp4, .mp3

View Request Example

{
  "URL": "https://example.com/api/send-message",
  "Headers": {
    "Content-Type": "application/json",
    "x-api-key": "api-key"
  },
  "Body": {
    "clientId": "client-id",
    "number": "12345678901",
    "message": "Hey! Its a test message",
    "mediaUrl": "https://example.com/image.jpg" // Optional, for media files
  }
}

GET /api/clients

Retrieve a list of all clients associated with your account.

View Request Example

{
  "URL": "https://example.com/api/clients",
  "Headers": {
    "x-api-key": "account-api-key"
  }
}

View Response Example

[
  {
    "clientId": "client-id",
    "phoneNumber": "9721234567",
    "apiKey": "client-api-key",
    "connectedNumber": "9721234567@c.us",
    "status": "Authenticated"
  },
  {
    "clientId": "client-id-2",
    "phoneNumber": "972512345678",
    "apiKey": "client-api-key-2",
    "connectedNumber": "Not Connected",
    "status": "Pending Authentication"
  }
]

GET /api/profile

Retrieve your profile details including username, role, API key, and client count.

View Request Example

{
  "URL": "https://example.com/api/profile",
  "Headers": {
    "x-api-key": "account-api-key"
  }
}

View Response Example

{
  "username": "admin",
  "role": "admin",
  "apiKey": "1f92bf99680b32fedeb1",
  "clientCount": 5
}

GET /api/sent-messages

Retrieve a list of sent messages for your clients (last 100 messages).

View Request Example

{
  "URL": "https://example.com/api/sent-messages",
  "Headers": {
    "x-api-key": "api-key"
  }
}

View Response Example

[
  {
    "id": 1,
    "clientId": "client-id",
    "senderNumber": "9721234567",
    "recipient": "1234567890",
    "message": "Hello from WhatsApp!",
    "status": "sent",
    "sentAt": "2025-11-01T12:00:00Z"
  }
]

GET /api/received-messages/:clientId

Retrieve a list of received messages for a specific client (last 100 messages).

View Request Example

{
  "URL": "https://example.com/api/received-messages/client-id",
  "Headers": {
    "x-api-key": "api-key"
  }
}

View Response Example

{
  "status": "success",
  "messages": [
    {
      "id": 1,
      "client_id": "client-id",
      "sender": "1234567890",
      "message": "Hello!",
      "received_at": "2025-11-01T12:00:00Z"
    }
  ]
}

GET /api/incoming-calls/:clientId

Retrieve a list of incoming calls for a specific client (last 100 calls).

View Request Example

{
  "URL": "https://example.com/api/incoming-calls/client-id",
  "Headers": {
    "x-api-key": "api-key"
  }
}

View Response Example

{
  "status": "success",
  "calls": [
    {
      "id": 1,
      "client_id": "client-id",
      "call_from": "1234567890@c.us",
      "is_video": false,
      "start_time": "2025-11-01T12:00:00Z",
      "end_time": null,
      "duration": null,
      "created_at": "2025-11-01T12:00:00Z"
    }
  ]
}

GET /api/call-logs

Retrieve call logs for all your clients (last 50 calls).

View Request Example

{
  "URL": "https://example.com/api/call-logs",
  "Headers": {
    "x-api-key": "api-key"
  }
}

GET /api/logs

Retrieve application logs for debugging and monitoring.

View Request Example

{
  "URL": "https://example.com/api/logs",
  "Headers": {
    "x-api-key": "api-key"
  }
}

GET /api/qr/:clientId

Retrieve the QR code image for a client (PNG format). Use this when a client needs to authenticate with WhatsApp Web.

View Request Example

{
  "URL": "https://example.com/api/qr/client-id",
  "Headers": {
    "x-api-key": "api-key"
  }
}

Note: This endpoint returns a PNG image, not JSON. The QR code is only available when the client is in "Pending Authentication" status. Once authenticated, the QR code expires.

Chat Interface API

Real-time chat interface endpoints for managing WhatsApp conversations. These endpoints require session authentication (login via dashboard). For a complete chat interface, visit /chat in your browser.

GET /api/chats/:clientId

Get all private chats (non-group conversations) for a specific WhatsApp client. Returns chat list with contact names, profile pictures, last messages, and unread counts.

Request Example GET

GET /api/chats/client-id
Headers: {
  "Content-Type": "application/json"
}

Request Parameters

clientId: string (URL parameter) - The WhatsApp client identifier
Authentication: Requires session authentication (must be logged in via dashboard)
Authorization: Client must belong to the logged-in user

Response Example JSON

{
  "chats": [
    {
      "id": {
        "_serialized": "9721234567@c.us"
      },
      "name": "John Doe",
      "profilePic": "https://example.com/profile.jpg",
      "lastMessage": {
        "body": "Hello!",
        "timestamp": 1699123456,
        "fromMe": false
      },
      "timestamp": 1699123456,
      "unreadCount": 2,
      "isMuted": false,
      "pinned": false
    }
  ]
}

Response Fields

chats: array - Array of chat objects (sorted by most recent first)
id._serialized: string - Chat ID in WhatsApp format
name: string - Contact name or phone number
profilePic: string | null - Profile picture URL (if available)
lastMessage: object | null - Last message in the chat
timestamp: number - Unix timestamp of last activity
unreadCount: number - Number of unread messages
isMuted: boolean - Whether the chat is muted
pinned: boolean - Whether the chat is pinned

Note: Only private chats (one-on-one conversations) are returned. Group chats are filtered out. Chats are sorted by most recent activity first.

GET /api/chats/:clientId/:chatId/messages

Get messages for a specific chat. Returns messages with reactions, media info, and timestamps. Messages are sorted from earliest to latest.

Request Example GET

GET /api/chats/client-id/9721234567@c.us/messages?limit=50
Headers: {
  "Content-Type": "application/json"
}

Request Parameters

clientId: string (URL parameter) - The WhatsApp client identifier
chatId: string (URL parameter) - The chat ID (e.g., "9721234567@c.us")
limit: number (query parameter, optional) - Maximum number of messages to return (default: 50)
Authentication: Requires session authentication

Response Example JSON

{
  "messages": [
    {
      "id": {
        "_serialized": "3EB0C767F26AFC1F8B"
      },
      "body": "Hello!",
      "fromMe": false,
      "timestamp": 1699123456,
      "type": "chat",
      "hasMedia": false,
      "hasReaction": true,
      "reactions": [
        {
          "reaction": "👍",
          "senderId": "9721234567@c.us"
        }
      ],
      "ack": 3,
      "filename": null
    }
  ]
}

Response Fields

messages: array - Array of message objects
id._serialized: string - Message ID
body: string - Message text content
fromMe: boolean - Whether message was sent by you
timestamp: number - Unix timestamp
type: string - Message type (chat, image, video, audio, document, etc.)
hasMedia: boolean - Whether message contains media
hasReaction: boolean - Whether message has reactions
reactions: array | null - Array of reaction objects
ack: number - Acknowledgment status (1=sent, 2=delivered, 3=read)
filename: string | null - Filename for media messages

POST /api/chats/:clientId/:chatId/send

Send a text message to a specific chat. The message will be sent in real-time and broadcast via WebSocket to connected clients.

Request Example JSON

POST /api/chats/client-id/9721234567@c.us/send
Headers: {
  "Content-Type": "application/json"
}
Body: {
  "message": "Hello! How can I help you?"
}

Request Parameters

clientId: string (URL parameter) - The WhatsApp client identifier
chatId: string (URL parameter) - The chat ID
message: string (body, required) - The message text to send
Authentication: Requires session authentication

Response Example JSON

{
  "success": true,
  "message": {
    "id": {
      "_serialized": "3EB0C767F26AFC1F8B"
    },
    "body": "Hello! How can I help you?",
    "timestamp": 1699123456
  }
}

Real-time Updates: When a message is sent, it's automatically broadcast via WebSocket to all connected clients listening to the chat interface.

POST /api/chats/:clientId/:chatId/read

Mark a chat as read (send "seen" status). This will update the read receipts in WhatsApp.

Request Example POST

POST /api/chats/client-id/9721234567@c.us/read
Headers: {
  "Content-Type": "application/json"
}

Note: No request body required. The endpoint marks all messages in the chat as read.

Response Example JSON

{
  "success": true
}

GET /api/chats/:clientId/media/:messageId

Download media (image, video, audio, document) from a message. Returns the media file with appropriate content type headers.

Request Example GET

GET /api/chats/client-id/media/3EB0C767F26AFC1F8B
Headers: {
  "Content-Type": "application/json"
}

Request Parameters

clientId: string (URL parameter) - The WhatsApp client identifier
messageId: string (URL parameter) - The message ID containing the media
Authentication: Requires session authentication

Response Example Binary (Image/Video/Audio/Document)

Response Headers: {
  "Content-Type": "image/jpeg",
  "Content-Disposition": "inline; filename=\"photo.jpg\""
}

[Binary media data]

Response Details

Content-Type: MIME type of the media (image/jpeg, video/mp4, audio/mpeg, application/pdf, etc.)
Content-Disposition: Filename for download (if available)
Body: Binary media data (not JSON)

Supported Media Types: Images (JPEG, PNG, GIF, WebP), Videos (MP4), Audio (MP3, OGG), Documents (PDF, DOC, etc.)

Note: This endpoint returns binary data, not JSON. Use it directly in <img>, <video>, or <audio> tags.

Groups & Channels API

Manage WhatsApp groups and channels. Send messages to groups and channels, and retrieve group/channel information. All endpoints support UTF-8 encoding for Hebrew and other Unicode characters.

GET /api/groups/:clientId

Get all groups and channels for a specific WhatsApp client. Returns separate arrays for groups and channels with detailed information including names, descriptions, participants, and more. Supports UTF-8 encoding for Hebrew and other Unicode characters.

Authentication: Supports both session-based authentication (dashboard login) and API key authentication (via x-api-key header).

UTF-8 Support: Group and channel names are returned with proper UTF-8 encoding, supporting Hebrew, Arabic, and other Unicode characters.

Request Example GET

GET /api/groups/client-id
Headers: {
  "Content-Type": "application/json; charset=utf-8",
  "x-api-key": "your-api-key" (optional, if using API key auth)
}

Request Parameters

clientId: string (URL parameter) - The WhatsApp client identifier
Authentication: Session-based (if logged in) or API key via x-api-key header
Authorization: Client must belong to the authenticated user

Response Example JSON

{
  "groups": [
    {
      "id": "120363123456789012@g.us",
      "name": "קבוצת עבודה",
      "description": "קבוצה לעבודה משותפת",
      "profilePic": "https://example.com/group-pic.jpg",
      "participants": 15,
      "owner": "972501234567@c.us",
      "createdAt": 1699123456,
      "lastMessage": {
        "body": "הודעה אחרונה",
        "timestamp": 1699123456,
        "fromMe": false
      },
      "timestamp": 1699123456,
      "unreadCount": 2,
      "isMuted": false,
      "pinned": false,
      "isReadOnly": false,
      "type": "group"
    }
  ],
  "channels": [
    {
      "id": "120363123456789013@c.us",
      "name": "ערוץ חדשות",
      "description": "ערוץ לחדשות",
      "profilePic": "https://example.com/channel-pic.jpg",
      "lastMessage": {
        "body": "חדשות היום",
        "timestamp": 1699123456,
        "fromMe": false
      },
      "timestamp": 1699123456,
      "unreadCount": 0,
      "isMuted": false,
      "pinned": false,
      "isReadOnly": false,
      "type": "channel"
    }
  ],
  "total": 2
}

Response Fields

groups: array - Array of group objects (sorted by most recent first)
channels: array - Array of channel objects (sorted by most recent first)
total: number - Total count of groups and channels
id: string - Group/channel ID in WhatsApp format
name: string - Group/channel name (UTF-8 encoded, supports Hebrew)
description: string | null - Group/channel description
profilePic: string | null - Profile picture URL (if available)
participants: number - Number of participants (groups only)
owner: string | null - Group owner ID (groups only)
createdAt: number | null - Unix timestamp when group was created (groups only)
lastMessage: object | null - Last message in the group/channel
timestamp: number - Unix timestamp of last activity
unreadCount: number - Number of unread messages
isMuted: boolean - Whether the group/channel is muted
pinned: boolean - Whether the group/channel is pinned
isReadOnly: boolean - Whether the group/channel is read-only
type: string - Type identifier ("group" or "channel")

UTF-8 Support: All text fields (name, description, messages) support UTF-8 encoding. Hebrew, Arabic, and other Unicode characters are properly encoded and displayed.

Filtering: Groups are filtered where isGroup = true and isChannel = false. Channels are filtered where isChannel = true.

POST /api/send-group-message

Send a text message or media attachment to a WhatsApp group or channel using API key authentication. Supports UTF-8 encoding for Hebrew and other Unicode characters. Includes automatic message delay (2-5 seconds) to prevent spam.

Authentication: Requires API key via x-api-key header (User or Client API key).

Rate Limiting: 100 requests per 15 minutes (global API limiter).

Message Delay: Automatic 2-5 second random delay before sending to prevent spam.

Read-Only Check: Returns error if attempting to send to a read-only group/channel.

Request Example JSON

POST /api/send-group-message
Headers: {
  "Content-Type": "application/json; charset=utf-8",
  "x-api-key": "your-api-key"
}
Body: {
  "clientId": "client-id",
  "groupId": "120363123456789012@g.us",
  "message": "שלום לכולם! זה הודעה בעברית",
  "mediaUrl": "https://example.com/image.jpg" (optional),
  "mediaType": "image" (optional, required if mediaUrl is provided)
}

Request Parameters

clientId: string (required) - The WhatsApp client identifier
groupId: string (required) - The group or channel ID (e.g., "120363123456789012@g.us")
message: string (optional) - The message text to send (UTF-8 supported, max 4096 characters)
mediaUrl: string (optional) - URL of media file to send (image, video, audio, document)
mediaType: string (optional, required if mediaUrl provided) - Media type: "image", "video", "audio", or "document"
Note: Either message or mediaUrl must be provided

Response Example JSON

{
  "success": true,
  "message": {
    "id": {
      "_serialized": "3EB0C767F26AFC1F8B"
    },
    "body": "שלום לכולם! זה הודעה בעברית",
    "timestamp": 1699123456,
    "type": "chat"
  },
  "groupId": "120363123456789012@g.us",
  "groupName": "קבוצת עבודה"
}

Response Fields

success: boolean - Whether the message was sent successfully
message: object - The sent message object
message.id._serialized: string - Message ID
message.body: string - Message text content
message.timestamp: number - Unix timestamp when message was sent
message.type: string - Message type (chat, image, video, etc.)
groupId: string - The group/channel ID
groupName: string - The group/channel name

Error Codes:

400 - Invalid request (missing required fields, invalid media type, etc.)
401 - Authentication failed (AUTH_ERROR)
403 - Access denied (ACCESS_DENIED, PLAN_LIMIT_EXCEEDED, READ_ONLY_CHAT)
404 - Client or group not found (CLIENT_NOT_FOUND, GROUP_NOT_FOUND)
400 - Invalid chat type (INVALID_CHAT_TYPE) - Chat is not a group or channel
400 - Media error (MEDIA_ERROR) - Failed to process media URL

POST /api/groups/:clientId/:groupId/send

Send a text message or media attachment to a WhatsApp group or channel using session-based authentication. This endpoint is designed for UI-based usage (dashboard). Supports UTF-8 encoding for Hebrew and other Unicode characters.

Authentication: Requires session authentication (must be logged in via dashboard).

Rate Limiting: 60 requests per minute (chat limiter).

Note: For API usage, use /api/send-group-message instead with API key authentication.

Request Example JSON

POST /api/groups/client-id/120363123456789012@g.us/send
Headers: {
  "Content-Type": "application/json; charset=utf-8"
}
Body: {
  "message": "שלום לכולם! זה הודעה בעברית",
  "mediaUrl": "https://example.com/image.jpg" (optional),
  "mediaType": "image" (optional, required if mediaUrl is provided)
}

Request Parameters

clientId: string (URL parameter) - The WhatsApp client identifier
groupId: string (URL parameter) - The group or channel ID
message: string (optional) - The message text to send (UTF-8 supported)
mediaUrl: string (optional) - URL of media file to send
mediaType: string (optional, required if mediaUrl provided) - Media type: "image", "video", "audio", or "document"
Note: Either message or mediaUrl must be provided

Response Example JSON

{
  "success": true,
  "message": {
    "id": {
      "_serialized": "3EB0C767F26AFC1F8B"
    },
    "body": "שלום לכולם! זה הודעה בעברית",
    "timestamp": 1699123456,
    "type": "chat"
  }
}

Real-time Updates: When a message is sent, it's automatically broadcast via WebSocket to all connected clients listening to the chat interface.

UTF-8 Support: All message content supports UTF-8 encoding for Hebrew, Arabic, and other Unicode characters.

Webhooks

Configure a webhook URL in your client settings to receive real-time event notifications. Your webhook endpoint will receive POST requests when events occur.

Note: Webhook URL can be configured when creating or updating a client via the dashboard or API.

The webhook will include the X-Api-Key header for authentication validation.

Webhook Payload Format

All webhook requests use the following format:

View Payload Structure

{
  "event": "event_type",
  "data": {
    // Event-specific data
  }
}

Event: message_received

Sent when a message is received by the WhatsApp client.

View Payload Example

{
  "event": "message_received",
  "data": {
    "from": "1234567890",
    "to": "client-id",
    "body": "Hello, this is a test message",
    "message": "Hello, this is a test message",
    "timestamp": 1699123456789,
    "type": "received_message"
  }
}

Response: You can return a response message that will be automatically sent back to the sender:

{
  "status": "success",
  "response": "Thank you for your message! We'll get back to you soon."
}

Event: message_sent

Sent when a message is successfully sent via the API.

View Payload Example

{
  "event": "message_sent",
  "data": {
    "from": "client-id",
    "to": "1234567890",
    "body": "Hello from the API",
    "message": "Hello from the API",
    "timestamp": 1699123456789,
    "type": "sent_message"
  }
}

Event: call_rejected

Sent when an incoming call is automatically rejected. You can return a custom rejection message.

View Payload Example

{
  "event": "call_rejected",
  "data": {
    "from": "1234567890",
    "to": "client-id",
    "isVideo": false,
    "timestamp": 1699123456789,
    "type": "call_rejected"
  }
}

Response: Return a custom rejection message that will be sent to the caller:

{
  "status": "success",
  "rejectionMessage": "מצטער אינני זמין כעת. אנא שלח הודעה ונחזור אליך בהקדם."
}

Default: If no rejection message is returned, the system uses: "מצטער אינני זמין כעת."

Webhook Headers

All webhook requests include the following headers:

View Headers

{
  "Content-Type": "application/json",
  "X-Api-Key": "your-client-api-key"
}

Webhook Response Format

Your webhook should respond with a JSON object:

View Response Format

{
  "status": "success",
  "message": "Webhook received successfully.",
  
  // Optional fields based on event:
  "response": "Message to send back (for message_received)",
  "rejectionMessage": "Custom rejection message (for call_rejected)"
}

Webhook Implementation Example

Here's an example webhook endpoint implementation:

View PHP Example

 'Invalid API key']);
//     exit;
// }

// Process different event types
if (isset($data['event']) && isset($data['data'])) {
    $event = $data['event'];
    $eventData = $data['data'];
    
    switch ($event) {
        case 'message_received':
            // Return a response message
            echo json_encode([
                'status' => 'success',
                'response' => 'Thank you for your message!'
            ]);
            break;
            
        case 'call_rejected':
            // Return a custom rejection message
            echo json_encode([
                'status' => 'success',
                'rejectionMessage' => 'מצטער אינני זמין כעת. אנא שלח הודעה ונחזור אליך בהקדם.'
            ]);
            break;
            
        case 'message_sent':
            // Just acknowledge receipt
            echo json_encode([
                'status' => 'success',
                'message' => 'Webhook received successfully.'
            ]);
            break;
            
        default:
            echo json_encode([
                'status' => 'success',
                'message' => 'Event received.'
            ]);
    }
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid webhook payload format.']);
}
?>

Webhook Requirements

Your webhook endpoint must accept POST requests
Must respond with HTTP 200 status code
Should respond within 5 seconds (3 seconds for call events)
Must return valid JSON response
Should validate the X-Api-Key header for security
URL must be publicly accessible (no localhost/private IPs)