Incoming message

Event incoming_message fires when a customer sends a message on a device linked to your webhook and set to On incoming message → Webhook.

Header:

X-Kirisan-Event: incoming_message

Unified envelope

WhatsApp, Telegram, and WABA share the same top-level shape:

Field	Type	Meaning
event	string	Always incoming_message
device	string	Kirisan device token for the line or bot
channel	string	whatsapp, telegram, or waba
sender	object	Who sent the message — see below
message	object	Message body — see below
metadata	object	Channel-specific extra fields
timestamp	integer	Unix seconds
production	boolean	true for live traffic; false for Webhooks → Test

sender

Field	Meaning
sender	Reply target — WhatsApp/WABA phone or Telegram chat id (use for {{sender}} shortcuts)
name	Display name after normalization (use for {{name}})
details	Channel-specific bag — see per-channel sections

message

Field	Meaning
type	text, image, video, document, location, callback, button_reply, list_reply, and other media types
text	Primary line — body, caption, or callback data (use for {{message}})
file	Optional — url, filename, filetype, mime_type, file_id
location	Optional — latitude, longitude, coordinate
button	Optional — id and text for button/list replies

More {{…}} shortcuts: Resources → Variables → Incoming. Dashboard tour: Variables.

---

WhatsApp example

{
  "event": "incoming_message",
  "device": "your-whatsapp-device-token",
  "channel": "whatsapp",
  "sender": {
    "sender": "6281234567890",
    "name": "Ada",
    "details": {
      "type": "personal",
      "sender": "6281234567890",
      "pushname": "Ada",
      "from_me": false
    }
  },
  "message": {
    "type": "text",
    "text": "Hi, I need help with my order."
  },
  "metadata": {
    "inboxid": 0,
    "isgroup": false,
    "isforwarded": false
  },
  "timestamp": 1735689600,
  "production": true
}

WhatsApp sender.details may also include senderlid, member, memberlid, and type: "group" for group chats.

Media messages set message.type to image, video, audio, or file and populate message.file.url.

---

Telegram example

{
  "event": "incoming_message",
  "device": "your-telegram-bot-token",
  "channel": "telegram",
  "sender": {
    "sender": "-1001234567890",
    "name": "Alex",
    "details": {
      "type": "group",
      "chat_id": "-1001234567890",
      "user_id": "555444333",
      "username": "alex_test",
      "first_name": "Alex",
      "last_name": "",
      "from_me": false
    }
  },
  "message": {
    "type": "text",
    "text": "Hello from the group."
  },
  "metadata": {
    "update_id": 100002,
    "message_id": "1001",
    "chat_type": "supergroup"
  },
  "timestamp": 1735689600,
  "production": true
}

For callback queries (inline button taps), message.type is callback and message.text holds the callback data. metadata.callback_query_id may be present.

In groups, sender.sender is the chat id (reply target), not the user id.

---

WABA example

WABA uses the same envelope as WhatsApp and Telegram:

{
  "event": "incoming_message",
  "device": "your-waba-device-token",
  "channel": "waba",
  "sender": {
    "sender": "6281234567890",
    "name": "Ada",
    "details": {
      "type": "personal",
      "sender": "6281234567890",
      "from_me": false
    }
  },
  "message": {
    "type": "text",
    "text": "Hello — WABA text message."
  },
  "metadata": {
    "message_id": "wamid.HBgLNjI4...",
    "waba_type": "text"
  },
  "timestamp": 1735689600,
  "production": true
}

Interactive replies use message.type button_reply or list_reply with a message.button object. metadata may include interactive_type, button_reply_id, or list_reply_id.

---

Related

• Webhooks overview — setup and delivery rules
• Verification — headers and signing secret
• Submission payload — autoreply form completions
• Message status — WABA delivery receipts
• Webhooks → Test — preview sample JSON per channel