Incoming Messages

Incoming message webhooks deliver real-time notifications when your recipients reply, enabling immediate responses and interactive conversations through WhatsApp.

The Incoming Messages system provides a robust webhook infrastructure that enables your application to receive and process WhatsApp messages from your recipients in real-time. This guide covers how to configure, manage, and handle incoming message webhooks.

Overview

Webhooks are HTTP callbacks that deliver notifications to your server whenever specific events occur - in this case, when recipients reply to your WhatsApp messages. Benefits include:

Real-time processing of customer responses
Seamless integration with your existing systems
Automated workflows triggered by customer messages
Enhanced customer experience through timely interactions

Try it in the API Reference

Explore the Webhook Management API and start receiving incoming messages

Webhook Configuration

Managing Endpoints

Access Webhook Settings

Navigate to the Developer section in your dashboard sidebar to manage webhook configurations.

Configure Endpoint

Add a new webhook URL where you want to receive incoming message notifications.

Endpoint Requirements

All webhook endpoints must be publicly accessible via HTTPS and configured to accept POST requests with JSON payloads. HTTP endpoints are not supported in production environments.

Your webhook endpoint must:

Accept HTTP POST requests
Process JSON payloads
Return a 2xx status code within 10 seconds
Implement idempotency handling (see best practices below)

Webhook Payload

When a user replies to your WhatsApp message, we’ll send a POST request to your configured endpoint with a detailed payload.

Sample Payload

{
  "last_messages": [
    {
      "type": "user",
      "content": "Thank you for the quick response. Can you provide more details about your premium service plans?",
      "timestamp": "2025-06-09T22:08:11.990Z",
      "content_type": "text"
    },
    {
      "type": "bot",
      "content": "I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
      "timestamp": "2025-06-09T21:45:30.417Z",
      "content_type": "text"
    }
  ],
  "conversation_paragraph": "User (10:08:11 PM): Thank you for the quick response. Can you provide more details about your premium service plans? ; Bot (9:45:30 PM): I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
  "phone_number": "14155552671",
  "recipient_name": "Sarah Johnson",
  "user_id": "9232fcef-a570-4a2c-b46b-6cab53aec304",
  "last_message_of_user": "Thank you for the quick response. Can you provide more details about your premium service plans?",
  "last_message_of_bot": "I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
  "message_type": "text",
  "user_last_message_time": 1749506891,
  "bot_last_message_time": 1749504330,
  "attachment_url": null,
  "note": "",
  "note_automation": "",
  "labels": "sales, premium-inquiry"
}

Payload Fields

last_messages

array

required

Array containing the recent messages in the conversation

Show last_messages array

type

string

required

Sender type (“user” or “bot”)

content

string

Message content (empty for media messages)

timestamp

string

required

ISO 8601 timestamp when the message was sent

content_type

string

required

Type of content (text, image, audio, video, document, location)

media_url

string

URL to media file if applicable (valid for 24 hours)

conversation_paragraph

string

required

Human-readable summary of the recent conversation

phone_number

string

required

The phone number of the recipient who sent the message

recipient_name

string

The name of the recipient if available

user_id

string

required

Unique identifier for the user in your system

last_message_of_user

string

The last message sent by the user

last_message_of_bot

string

The last message sent by your system

message_type

string

required

The type of the latest message (text, image, audio, video, document, location)

user_last_message_time

integer

required

Unix timestamp of the user’s last message

bot_last_message_time

integer

required

Unix timestamp of your system’s last message

attachment_url

string

URL to media file if the latest message contains media (null for text messages)

note

string

Custom note field for additional context

note_automation

string

Automation-related notes

labels

string

Comma-separated labels for categorizing the conversation

Webhook Management API

You can programmatically manage your webhook endpoints using our API.

Create Webhook Endpoint

curl -X POST \
  https://api.insightssystem.com/api:qh9OQ3OW/webhook/dev/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "url": "https://your-domain.com/api/webhooks/whatsapp"
  }'

Always verify webhook signatures to ensure the authenticity of incoming requests. This prevents malicious actors from sending fraudulent events to your endpoint.

Troubleshooting

Webhook Not Receiving Events

FAQs

Can I receive notifications for all WhatsApp account events?

How do I handle different message types?

Do I need to respond to every webhook request?

How can I test webhook delivery?

Need assistance?

Our technical support team is available to assist with webhook configuration, payload handling, and integration questions.

On this page

Overview
Webhook Configuration
Managing Endpoints
Endpoint Requirements
Webhook Payload
Sample Payload
Payload Fields
Webhook Management API
Create Webhook Endpoint
Troubleshooting
FAQs

Incoming message webhooks deliver real-time notifications when your recipients reply, enabling immediate responses and interactive conversations through WhatsApp.

Overview

Webhooks are HTTP callbacks that deliver notifications to your server whenever specific events occur - in this case, when recipients reply to your WhatsApp messages. Benefits include:

Real-time processing of customer responses
Seamless integration with your existing systems
Automated workflows triggered by customer messages
Enhanced customer experience through timely interactions

Try it in the API Reference

Explore the Webhook Management API and start receiving incoming messages

Webhook Configuration

Managing Endpoints

Access Webhook Settings

Navigate to the Developer section in your dashboard sidebar to manage webhook configurations.

Configure Endpoint

Add a new webhook URL where you want to receive incoming message notifications.

Endpoint Requirements

All webhook endpoints must be publicly accessible via HTTPS and configured to accept POST requests with JSON payloads. HTTP endpoints are not supported in production environments.

Your webhook endpoint must:

Accept HTTP POST requests
Process JSON payloads
Return a 2xx status code within 10 seconds
Implement idempotency handling (see best practices below)

Webhook Payload

When a user replies to your WhatsApp message, we’ll send a POST request to your configured endpoint with a detailed payload.

Sample Payload

{
  "last_messages": [
    {
      "type": "user",
      "content": "Thank you for the quick response. Can you provide more details about your premium service plans?",
      "timestamp": "2025-06-09T22:08:11.990Z",
      "content_type": "text"
    },
    {
      "type": "bot",
      "content": "I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
      "timestamp": "2025-06-09T21:45:30.417Z",
      "content_type": "text"
    }
  ],
  "conversation_paragraph": "User (10:08:11 PM): Thank you for the quick response. Can you provide more details about your premium service plans? ; Bot (9:45:30 PM): I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
  "phone_number": "14155552671",
  "recipient_name": "Sarah Johnson",
  "user_id": "9232fcef-a570-4a2c-b46b-6cab53aec304",
  "last_message_of_user": "Thank you for the quick response. Can you provide more details about your premium service plans?",
  "last_message_of_bot": "I'd be happy to help you explore our premium service options. Let me connect you with a specialist who can provide detailed information.",
  "message_type": "text",
  "user_last_message_time": 1749506891,
  "bot_last_message_time": 1749504330,
  "attachment_url": null,
  "note": "",
  "note_automation": "",
  "labels": "sales, premium-inquiry"
}

Payload Fields

last_messages

array

required

Array containing the recent messages in the conversation

Show last_messages array

type

string

required

Sender type (“user” or “bot”)

content

string

Message content (empty for media messages)

timestamp

string

required

ISO 8601 timestamp when the message was sent

content_type

string

required

Type of content (text, image, audio, video, document, location)

media_url

string

URL to media file if applicable (valid for 24 hours)

conversation_paragraph

string

required

Human-readable summary of the recent conversation

phone_number

string

required

The phone number of the recipient who sent the message

recipient_name

string

The name of the recipient if available

user_id

string

required

Unique identifier for the user in your system

last_message_of_user

string

The last message sent by the user

last_message_of_bot

string

The last message sent by your system

message_type

string

required

The type of the latest message (text, image, audio, video, document, location)

user_last_message_time

integer

required

Unix timestamp of the user’s last message

bot_last_message_time

integer

required

Unix timestamp of your system’s last message

attachment_url

string

URL to media file if the latest message contains media (null for text messages)

note

string

Custom note field for additional context

note_automation

string

Automation-related notes

labels

string

Comma-separated labels for categorizing the conversation

Webhook Management API

You can programmatically manage your webhook endpoints using our API.

Create Webhook Endpoint

curl -X POST \
  https://api.insightssystem.com/api:qh9OQ3OW/webhook/dev/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "url": "https://your-domain.com/api/webhooks/whatsapp"
  }'

Always verify webhook signatures to ensure the authenticity of incoming requests. This prevents malicious actors from sending fraudulent events to your endpoint.

Troubleshooting

Webhook Not Receiving Events

FAQs

Can I receive notifications for all WhatsApp account events?

How do I handle different message types?

Do I need to respond to every webhook request?

How can I test webhook delivery?

Need assistance?

Our technical support team is available to assist with webhook configuration, payload handling, and integration questions.

On this page

Overview
Webhook Configuration
Managing Endpoints
Endpoint Requirements
Webhook Payload
Sample Payload
Payload Fields
Webhook Management API
Create Webhook Endpoint
Troubleshooting
FAQs

Overview

Try it in the API Reference

Webhook Configuration

Managing Endpoints

Endpoint Requirements

Webhook Payload

Sample Payload

Payload Fields

Webhook Management API

Create Webhook Endpoint

Troubleshooting

FAQs

Need assistance?

API Documentation

WhatsAble API

Notifier by WhatsAble

Notifier System

Incoming Messages

Overview

Try it in the API Reference

Webhook Configuration

Managing Endpoints

Endpoint Requirements

Webhook Payload

Sample Payload

Payload Fields

Webhook Management API

Create Webhook Endpoint

Troubleshooting

FAQs

Need assistance?

​Overview

Try it in the API Reference

​Webhook Configuration

​Managing Endpoints

​Endpoint Requirements

​Webhook Payload

​Sample Payload

​Payload Fields

​Webhook Management API

​Create Webhook Endpoint

​Troubleshooting

​FAQs

Need assistance?

API Documentation

WhatsAble API

Notifier by WhatsAble

Notifier System

​Overview

Try it in the API Reference

​Webhook Configuration

​Managing Endpoints

​Endpoint Requirements

​Webhook Payload

​Sample Payload

​Payload Fields

​Webhook Management API

​Create Webhook Endpoint

​Troubleshooting

​FAQs

Need assistance?

Overview

Webhook Configuration

Managing Endpoints

Endpoint Requirements

Webhook Payload

Sample Payload

Payload Fields

Webhook Management API

Create Webhook Endpoint

Troubleshooting

FAQs

Overview

Webhook Configuration

Managing Endpoints

Endpoint Requirements

Webhook Payload

Sample Payload

Payload Fields

Webhook Management API

Create Webhook Endpoint

Troubleshooting

FAQs