> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound callbacks

> Handle inbound SMS callbacks from Beem on your server.

When a subscriber sends an SMS to your Two-Way number, Beem forwards the message to your configured callback URL via **HTTP POST** with a JSON body.

***

## Callback flow

```text theme={null}
Inbound SMS received
        │
        ▼
Beem POSTs JSON to your callback URL
        │
        ▼
Your server processes the message
        │
        ▼
Your server responds with acknowledgement JSON
```

***

## Callback parameters

| Parameter                  | Type   | Description                                           |
| -------------------------- | ------ | ----------------------------------------------------- |
| `from`                     | String | Source address — subscriber mobile number (MSISDN)    |
| `to`                       | String | Destination address — your long code or short code    |
| `channel`                  | String | Channel name (default: `sms`)                         |
| `timeUTC`                  | String | UTC timestamp (e.g. `Wed, 14 Jun 2017 07:00:00 GMT`)  |
| `transaction_id`           | String | Beem transaction ID                                   |
| `message`                  | Object | Inbound message payload                               |
| `message.text`             | String | SMS content sent by the subscriber                    |
| `message.media`            | Object | Media attachments — **not currently supported**       |
| `message.media.mediaUrl`   | String | Reserved for future use — **not currently supported** |
| `message.custom`           | Object | Custom data object                                    |
| `billing`                  | Object | Billing details for the message                       |
| `billing.currency`         | String | Currency code (default: `TZS`)                        |
| `billing.subscriber_price` | String | Amount charged to the subscriber (if applicable)      |
| `billing.billing_price`    | String | Billing price for the message                         |

***

## Sample callback payload

```json theme={null}
{
  "from": "255701000000",
  "to": "255701000001",
  "channel": "sms",
  "timeUTC": "Wed, 14 Jun 2017 07:00:00 GMT",
  "transaction_id": "120a1039103910",
  "message": {
    "text": "Test message",
    "media": { "mediaUrl": "" },
    "custom": {}
  },
  "billing": {
    "currency": "TZS",
    "subscriber_price": "100.00",
    "billing_price": "100.00"
  }
}
```

***

## Expected response

Your server should respond with **HTTP 200 OK** and a JSON body acknowledging receipt:

```json theme={null}
{
  "transaction_id": "120a1039103910",
  "successful": true
}
```

Return the same `transaction_id` from the inbound request so Beem can correlate the acknowledgement.

***

## Sample implementations

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const express = require("express");
    const app = express();

    app.use(express.urlencoded({ extended: false }));
    app.use(express.json());

    app.post("/", (req, res) => {
      const { from, to, channel, timeUTC, transaction_id, message, billing } = req.body;

      // Process the inbound message here

      res.json({
        transaction_id,
        successful: true,
      });
    });

    app.listen(3000, () => console.log("app running on port 3000"));
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php
    $data = file_get_contents('php://input');
    $data = json_decode($data, true);

    $source_addr = $data['from'];
    $dest_addr = $data['to'];
    $channel = $data['channel'];
    $timestamp = $data['timeUTC'];
    $id = $data['transaction_id'];
    $message = $data['message'];
    $billing = $data['billing'];

    // Process the inbound message here

    $res = ['transaction_id' => $id, 'successful' => true];
    echo json_encode($res);
    ?>
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from flask import Flask, request, jsonify

    app = Flask(__name__)

    @app.route('/submit', methods=['POST'])
    def handle_callback():
        data = request.get_json()
        source_addr = data['from']
        dest_addr = data['to']
        channel = data['channel']
        timestamp = data['timeUTC']
        txn_id = data['transaction_id']
        message = data['message']
        billing = data['billing']

        # Process the inbound message here

        return jsonify({
            'transaction_id': txn_id,
            'successful': True
        })

    if __name__ == '__main__':
        app.run(debug=True)
    ```
  </Tab>
</Tabs>