---
title: "Inbound Message Webhooks"
description: "Process incoming customer replies across SMS and WhatsApp in real time."
---

# Inbound Message Webhooks

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` | WhatsApp | 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:

```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
```