Transaction Status Programming Examples

These examples show how to receive the POSTed JSON payload and handle it on your side. Each one stands up an endpoint like yoursite.com/api/transaction-status, which you register on your Comms Settings > API Settings page to begin receiving delivery reports. Persist the payload however you prefer (database, queue, log, etc.), and respond quickly — see Endpoint requirements.

Pick your preferred language.

Java

Spring Boot

// DTO
public class TxStatusPayload {
    public String MsgFollowUpUniqueCode;
    public String number;
    public String Status;
}

@RestController
public class TxStatusController {

    @PostMapping("/api/transaction-status")
    public ResponseEntity<String> receive(@RequestBody TxStatusPayload payload) {
        // TODO: persist payload (DB, queue, etc.)
        System.out.println("Status: " + payload.Status + " for " + payload.number);
        return ResponseEntity.ok("OK");
    }
}

Jakarta EE / JAX-RS

import jakarta.ws.rs.*;
import jakarta.ws.rs.core.MediaType;
import jakarta.ws.rs.core.Response;

@Path("/api/transaction-status")
public class TxStatusResource {

    public static class TxStatusPayload {
        public String MsgFollowUpUniqueCode;
        public String number;
        public String Status;
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response receive(TxStatusPayload payload) {
        // TODO: persist payload (DB, queue, etc.)
        System.out.println("Status: " + payload.Status + " for " + payload.number);
        return Response.ok("OK").build();
    }
}

Plain Java (HttpServer, Java 7+)

// Full example, the webhook endpoint created will be '/api/transaction-status' at port 55566
// This example is compatible with Java 7 so it should run on all common JVMs
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpHandler;
import com.sun.net.httpserver.HttpServer;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.InetSocketAddress;
import java.net.URL;

public class Main {

    // Inner class representing the request object
    public static class MessageRequest {
        private String MsgFollowUpUniqueCode;
        private String number;
        private String Status;

        public MessageRequest() {}

        public MessageRequest(String MsgFollowUpUniqueCode, String number, String Status) {
            this.MsgFollowUpUniqueCode = MsgFollowUpUniqueCode;
            this.number = number;
            this.Status = Status;
        }

        // Getters and Setters
        public String getMsgFollowUpUniqueCode() {
            return MsgFollowUpUniqueCode;
        }

        public void setMsgFollowUpUniqueCode(String MsgFollowUpUniqueCode) {
            this.MsgFollowUpUniqueCode = MsgFollowUpUniqueCode;
        }

        public String getNumber() {
            return number;
        }

        public void setNumber(String number) {
            this.number = number;
        }

        public String getStatus() {
            return Status;
        }

        public void setStatus(String Status) {
            this.Status = Status;
        }
    }

    // Simple JSON parser
    public static class JsonParser {
        public static MessageRequest parseMessageRequest(String json) {
            MessageRequest request = new MessageRequest();

            // Remove curly braces and quotes
            json = json.trim();
            if (json.startsWith("{") && json.endsWith("}")) {
                json = json.substring(1, json.length() - 1);
            }

            // Split by comma, but be careful with nested objects
            String[] pairs = json.split(",(?=(?:[^\"]*\"[^\"]*\")*[^\"]*$)");

            for (String pair : pairs) {
                String[] keyValue = pair.split(":(?=(?:[^\"]*\"[^\"]*\")*[^\"]*$)");
                if (keyValue.length == 2) {
                    String key = keyValue[0].trim().replace("\"", "");
                    String value = keyValue[1].trim().replace("\"", "");

                    if ("MsgFollowUpUniqueCode".equals(key)) {
                        request.setMsgFollowUpUniqueCode(value);
                    } else if ("number".equals(key)) {
                        request.setNumber(value);
                    } else if ("Status".equals(key)) {
                        request.setStatus(value);
                    }
                }
            }

            return request;
        }
    }

    // Server endpoint implementation
    public static class MessageEndpointHandler {

        public String handleRequest(String jsonRequest) {
            try {
                // Parse the incoming JSON
                MessageRequest request = JsonParser.parseMessageRequest(jsonRequest);

                // Validate required fields
                if (request.getMsgFollowUpUniqueCode() == null ||
                        request.getNumber() == null ||
                        request.getStatus() == null) {
                    return "{\"error\": \"Missing required fields\"}";
                }

                // Process the request (example)
                System.out.println("Received message:");
                System.out.println("  Unique Code: " + request.getMsgFollowUpUniqueCode());
                System.out.println("  Number: " + request.getNumber());
                System.out.println("  Status: " + request.getStatus());

                // Return success response
                return "{\"success\": true, \"message\": \"Request processed successfully\"}";

            } catch (Exception e) {
                return "{\"error\": \"" + e.getMessage() + "\"}";
            }
        }
    }

    public static void main(String[] args) throws IOException {
        // Create HTTP server on port 55566
        HttpServer server = HttpServer.create(new InetSocketAddress(55566), 0);

        // Create context for the endpoint
        server.createContext("/api/transaction-status", new PostHandler());

        // Set executor (optional)
        server.setExecutor(null);

        // Start the server
        server.start();

        System.out.println("Server started on port 55566");
        System.out.println("Endpoint: POST http://localhost:55566/api/transaction-status");
        System.out.println("Send JSON data to this endpoint");
        System.out.println("Press Ctrl+C to stop the server");

        // Keep server running
        try {
            Thread.currentThread().join();
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        }
    }

    // Helper method to send POST request (if needed)
    public static String sendPostRequest(String endpointUrl, String jsonData) {
        try {
            URL url = new URL(endpointUrl);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            // Send JSON data
            OutputStream os = conn.getOutputStream();
            os.write(jsonData.getBytes());
            os.flush();
            os.close();

            // Read response
            int responseCode = conn.getResponseCode();
            BufferedReader in = new BufferedReader(
                    new InputStreamReader(conn.getInputStream()));
            String inputLine;
            StringBuilder response = new StringBuilder();

            while ((inputLine = in.readLine()) != null) {
                response.append(inputLine);
            }
            in.close();

            return response.toString();

        } catch (IOException e) {
            return "{\"error\": \"" + e.getMessage() + "\"}";
        }
    }

    public static class PostHandler implements HttpHandler {
        private MessageEndpointHandler handler = new MessageEndpointHandler();

        @Override
        public void handle(HttpExchange exchange) throws IOException {
            // Allow only POST requests
            if (!"POST".equals(exchange.getRequestMethod())) {
                String response = "{\"error\": \"Method not allowed. Use POST.\"}";
                exchange.sendResponseHeaders(405, response.length());
                OutputStream os = exchange.getResponseBody();
                os.write(response.getBytes());
                os.close();
                return;
            }

            try {
                // Read the request body
                BufferedReader reader = new BufferedReader(
                        new InputStreamReader(exchange.getRequestBody()));
                StringBuilder jsonBuffer = new StringBuilder();
                String line;
                while ((line = reader.readLine()) != null) {
                    jsonBuffer.append(line);
                }
                String jsonData = jsonBuffer.toString();

                // Process the request
                String response = handler.handleRequest(jsonData);

                // Send response
                exchange.getResponseHeaders().set("Content-Type", "application/json");
                exchange.sendResponseHeaders(200, response.length());
                OutputStream os = exchange.getResponseBody();
                os.write(response.getBytes());
                os.close();

            } catch (Exception e) {
                String error = "{\"error\": \"" + e.getMessage() + "\"}";
                exchange.sendResponseHeaders(500, error.length());
                OutputStream os = exchange.getResponseBody();
                os.write(error.getBytes());
                os.close();
            }
        }
    }
}

Rust

use axum::{routing::post, Json, Router};
use serde::Deserialize;

#[derive(Deserialize)]
struct TxStatusPayload {
    #[serde(rename = "MsgFollowUpUniqueCode")]
    msg_follow_up_unique_code: String,
    number: String,
    #[serde(rename = "Status")]
    status: String,
}

async fn receive(Json(payload): Json<TxStatusPayload>) -> &'static str {
    // TODO: persist payload (DB, queue, etc.)
    println!("Status: {} for {}", payload.status, payload.number);
    "OK"
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/api/transaction-status", post(receive));
    axum::Server::bind(&"0.0.0.0:8080".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

Flask

from flask import Flask, request

app = Flask(__name__)

@app.post("/api/transaction-status")
def receive():
    payload = request.get_json(force=True)
    msg_code = payload.get("MsgFollowUpUniqueCode")
    number = payload.get("number")
    status = payload.get("Status")

    # TODO: persist payload (DB, queue, etc.)
    print(f"Status: {status} for {number} code={msg_code}")

    return "OK", 200

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Go

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

type TxStatusPayload struct {
    MsgFollowUpUniqueCode string `json:"MsgFollowUpUniqueCode"`
    Number                string `json:"number"`
    Status                string `json:"Status"`
}

func receive(w http.ResponseWriter, r *http.Request) {
    var payload TxStatusPayload
    if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
        http.Error(w, "invalid json", http.StatusBadRequest)
        return
    }

    // TODO: persist payload (DB, queue, etc.)
    fmt.Printf("Status: %s for %s\n", payload.Status, payload.Number)

    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
}

func main() {
    http.HandleFunc("/api/transaction-status", receive)
    http.ListenAndServe(":8080", nil)
}

Node.js

const express = require("express");
const app = express();

app.use(express.json());

app.post("/api/transaction-status", (req, res) => {
  const { MsgFollowUpUniqueCode, number, Status } = req.body;

  // TODO: persist payload (DB, queue, etc.)
  console.log(`Status: ${Status} for ${number} code=${MsgFollowUpUniqueCode}`);

  res.status(200).send("OK");
});

app.listen(3000, () => console.log("Listening on :3000"));

PHP

<?php

// Assuming you have the necessary credentials to connect to your MySQL database
$servername = "xxxxxx";
$username = "xxxxxxx";
$password = "******";
$dbname = "xxxxxxx";

// Create a connection to the database
$conn = new mysqli($servername, $username, $password, $dbname);

// Check the connection
if ($conn->connect_error) {
    die("Connection failed: " . $conn->connect_error);
}

// Read the raw data from the incoming HTTP request's body
$data = file_get_contents("php://input");

// Decode the JSON data into an associative array
$decoded_data = json_decode($data, true);

// Write incoming payloads to a local file (optional)
file_put_contents('msgdata.txt', $data, FILE_APPEND);

// Check if JSON decoding was successful
if ($decoded_data === null) {
    echo "Error decoding JSON data.";
    exit;
}

// Extract data from the JSON structure
$number = $decoded_data['number'];
$message_code = $decoded_data['MsgFollowUpUniqueCode'];
$status = $decoded_data['Status'];

// Escape each value to prevent SQL injection
$number = $conn->real_escape_string($number);
$message_code = $conn->real_escape_string($message_code);
$status = $conn->real_escape_string($status);

// SQL query to insert the data into a table named 'egosmsdata'
$sql = "INSERT INTO tableName (number, message_code, status) VALUES ('$number', '$message_code', '$status')";
if ($conn->query($sql) !== TRUE) {
    echo "Error in saving delivery report: " . $conn->error;
    $conn->close();
    exit;
}

echo "Delivery report saved successfully into the database.";

// Close the database connection
$conn->close();
?>