Inbound callbacks - Beem API

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

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

{
  "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:

{
  "transaction_id": "120a1039103910",
  "successful": true
}

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

Sample implementations

Node.js
PHP
Python

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"));

<?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);
?>

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)