Inbound Message Webhooks
Process incoming customer replies across SMS and WhatsApp in real time.
Last updated · Markdown version
When customers reply to your SMS shortcode, two-way numbers, or your connected WhatsApp account, Bulkit immediately forwards the message to your configured Inbox Webhook URL (API Keys -> Webhooks in the dashboard).
Events Dispatched
| Event Identifier | Channel | Description |
|---|---|---|
sms.received / sms.inbound | SMS | Inbound SMS message sent to your shortcode or alphanumeric number. |
whatsapp.message.received | Incoming customer WhatsApp message (text, media, or document). |
1. Incoming SMS Payload
When a subscriber texts your shortcode or inbound SMS route:
JSON
{
"event": "sms.received",
"mobile": "254700000001",
"shortcode": "BULKIT",
"message": "YES please send me the quotation",
"received_at": "2026-09-19T06:40:00+03:00"
}Payload Fields
| Field | Type | Description |
|---|---|---|
event | string | sms.received or sms.inbound. |
mobile | string | Sender mobile number in international format (2547...). |
shortcode | string | Destination shortcode or sender name that received the SMS. |
message | string | The full SMS text sent by the subscriber. |
received_at | string | Timestamp when the message reached Bulkit. |
2. Incoming WhatsApp Message Payload
When a customer messages your connected WhatsApp account:
JSON
{
"event": "whatsapp.message.received",
"id": "c1f7a072-4a0b-4835-bd57-f6498ec5bbdc",
"message_id": "3EB042F803DA86B4",
"from": "254700000001",
"to": "254712345678@s.whatsapp.net",
"sender_jid": "254700000001@s.whatsapp.net",
"chat_jid": "254700000001@s.whatsapp.net",
"text": "Hello, could you please send me an updated invoice for this month?",
"media_type": "text",
"media_url": "",
"file_name": "",
"file_size": 0,
"mime_type": "",
"timestamp": "2026-09-19T06:41:22Z"
}Inbound WhatsApp Media Attachment Example
If the customer sends a photo, PDF, or audio voice note:
JSON
{
"event": "whatsapp.message.received",
"id": "e88383a8-4bb9-4d69-a1b7-a36c841fa909",
"message_id": "3EB09395AB6E6FF1",
"from": "254700000001",
"to": "254712345678@s.whatsapp.net",
"sender_jid": "254700000001@s.whatsapp.net",
"chat_jid": "254700000001@s.whatsapp.net",
"text": "Here is the proof of payment screenshot.",
"media_type": "image",
"media_url": "/api/v2/messages/whatsapp/e88383a8-4bb9-4d69-a1b7-a36c841fa909/media",
"file_name": "receipt_screenshot.jpg",
"file_size": 184502,
"mime_type": "image/jpeg",
"timestamp": "2026-09-19T06:42:01Z"
}Media Types
text: Regular text chat.image: Photo or graphic file (JPEG, PNG).document: PDF, Office document, CSV, etc.audio: Recorded voice note or music file.video: Video clip (MP4).
Downloading Received Media
The media_url field contains the path to download the decrypted file. You can fetch it using your API key:
cURL / Bash
curl -X GET "https://api.bulkitsms.com/api/v2/messages/whatsapp/e88383a8-4bb9-4d69-a1b7-a36c841fa909/media" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
--output proof_of_payment.jpg