-
Notifications
You must be signed in to change notification settings - Fork 1
API & Webhooks Integration Guide
The Sendium SMS Gateway provides a RESTful API for managing configurations, sending SMS messages, and handling Delivery Receipts (DLRs).
Interactive API Explorer: An interactive Swagger UI is built into the gateway. Once your container is running, you can access it at
http://<your-server-ip>:8080/swagger-ui.
Sendium uses API Keys for authentication. The type of key you need depends on the endpoint you are accessing.
-
Admin Operations (e.g., managing vendors, routing rules): Require the Admin API Key. This is defined via the
SMS_GATEWAY_API_KEY_ADMINenvironment variable during deployment. -
Messaging Operations (e.g., sending SMS): Require a "message" type API Key. These are created and managed via the
/api/admin/api-keysendpoints.
Authentication headers (e.g., Authorization: Bearer <key> or custom headers) depend on your specific implementation of the security layer, but the keys themselves must match those configured in the system.
To send an SMS, make a POST request to the /api/sms/send endpoint.
Endpoint: POST /api/sms/send
Request Body (IncomingSms):
{
"from": "SenderID",
"to": "+1234567890",
"text": "Hello from Sendium!",
"forwardUrl": "[https://your-app.com/webhooks/dlr](https://your-app.com/webhooks/dlr)"
}-
from: The sender ID or phone number. -
to: The recipient's phone number. -
text: The content of the message. -
forwardUrl: (Optional) A specific webhook URL to receive DLRs for this specific message.
Successful Response (200 OK):
{
"status": "ACCEPTED",
"internalId": "abc-123-def-456",
"error": null
}Save the internalId as you will need it to match incoming Delivery Receipts to the original message.
Sendium supports automatic forwarding of Delivery Receipts to your external systems via Webhooks.
-
Global Webhook: Set via the
quarkus.rest-client.dlr-forwarding.urlenvironment variable. All DLRs will be sent here by default. -
Message-Specific Webhook: Passed in the
forwardUrlfield when sending the SMS. This overrides the global webhook for that specific message.
When a DLR is received from a provider, Sendium will make an HTTP POST request to your webhook URL with the following JSON payload (DlrForwardingPayload):
{
"smscid": "Provider_A",
"status": "DELIVRD",
"errorCode": "0",
"receivedAt": "2024-10-24T10:15:30Z",
"processedAt": "2024-10-24T10:15:31Z",
"rawDlr": "id:123456 sub:001 dlvrd:001 submit date:2410241015 done date:2410241015 stat:DELIVRD err:000 Text:Hello",
"fromAddress": "SenderID",
"toAddress": "+1234567890",
"message": {
"internalId": "abc-123-def-456",
"text": "Hello from Sendium!"
}
}-
status: The final status of the message (e.g.,DELIVRD,REJECTD,UNDELIV). -
message.internalId: Use this to match the DLR to the response you received when calling/api/sms/send.
The Admin API allows you to programmatically configure the gateway without editing JSON files manually.
-
Vendors: Manage SMPP connections.
-
GET /api/admin/vendors- List all vendors. -
POST /api/admin/vendors- Add a new vendor (RequiresVendorConfobject). -
PUT /api/admin/vendors/{id}- Update a vendor. -
DELETE /api/admin/vendors/{id}- Remove a vendor.
-
-
Routing Rules: Define how messages are routed to different vendors based on conditions (e.g., regex matching on the recipient's number).
-
GET /api/admin/routing-rules- Get current rules. -
PUT /api/admin/routing-rules- Update rules.
-
-
API Keys: Manage client access.
-
GET /api/admin/api-keys- List all keys. -
PUT /api/admin/api-keys- Update keys.
-
This guide explains how to import and use the Postman collection for our SMS Gateway API. The collection includes pre-configured endpoints and sample request bodies for all available operations (API Keys, Routing Rules, SMPP Vendors, DLR, and SMS).
Step 1: Import the Collection Copy the JSON: Copy the raw JSON code block from this page (check at the end)
Open Postman: Launch your Postman desktop app or open the web workspace.
Import: Click the Import button in the top left corner of Postman.
Paste: Select Raw text and paste the JSON (or drag and drop the downloaded file).
Click Import to finish. You should now see the sms-gateway API collection in your sidebar.
Step 2: Configure Your API Key The collection is set up to automatically apply the authorization header (x-api-key) to every request inside it. You just need to add your personal/admin key.
In the left sidebar, click on the sms-gateway API collection folder.
In the main window, click the Authorization tab.
You will see the Type is set to API Key.
In the Value field, replace your-admin-api-key with your actual working API key.
Click Save (or Ctrl+S / Cmd+S).
Note: Because this is configured at the collection level, you do not need to add the header manually to individual requests.
Step 3: Set the Base URL By default, the environment is pointed at a local server. You will need to update this to hit our actual development or production environments.
Click on the sms-gateway API collection folder again.
Navigate to the Variables tab.
Find the baseUrl variable.
Change the Current Value from http://localhost:8080 to the proper server URL (e.g., https://api.ourdomain.com).
Click Save.
Step 4: Make a Request! You are all set! Open any folder (like SMS), select a request (like Send an SMS message), modify the JSON body as needed, and hit Send.
You can find a postman collection here:
{
"info": {
"name": "Sendium API",
"description": "Sendium API",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"auth": {
"type": "apikey",
"apikey": [
{
"key": "value",
"value": "your-admin-api-key",
"type": "string"
},
{
"key": "key",
"value": "x-api-key",
"type": "string"
},
{
"key": "in",
"value": "header",
"type": "string"
}
]
},
"variable": [
{
"key": "baseUrl",
"value": "http://localhost:8080",
"type": "string"
}
],
"item": [
{
"name": "API Key Management",
"description": "Operations for managing API keys",
"item": [
{
"name": "Get all API keys",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/admin/api-keys",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"api-keys"
]
},
"description": "Retrieves a list of all API keys."
}
},
{
"name": "Update API keys",
"request": {
"method": "PUT",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "[\n {\n \"type\": \"admin\",\n \"key\": \"string\",\n \"systemId\": \"string\",\n \"password\": \"string\"\n }\n]"
},
"url": {
"raw": "{{baseUrl}}/api/admin/api-keys",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"api-keys"
]
},
"description": "Updates the list of API keys."
}
}
]
},
{
"name": "Routing Rules",
"description": "Operations for managing routing rules",
"item": [
{
"name": "Get Routing Rules",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/admin/routing-rules",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"routing-rules"
]
},
"description": "Retrieves the current routing rules grouped by rule group."
}
},
{
"name": "Update Routing Rules",
"request": {
"method": "PUT",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "[\n {\n \"ruleName\": \"string\",\n \"conditions\": {\n \"sender\": \"string\",\n \"recipient\": \"string\",\n \"textContains\": \"string\",\n \"textMatchesRegex\": \"string\"\n },\n \"destinationId\": \"string\",\n \"nextRuleGroupName\": \"string\"\n }\n]"
},
"url": {
"raw": "{{baseUrl}}/api/admin/routing-rules",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"routing-rules"
]
},
"description": "Updates the routing rules."
}
}
]
},
{
"name": "SMPP Vendor Configuration",
"description": "Operations for managing SMPP vendor configurations",
"item": [
{
"name": "Get all vendors",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/admin/vendors",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"vendors"
]
},
"description": "Retrieves a list of all SMPP vendors."
}
},
{
"name": "Create a new vendor",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"id\": \"string\",\n \"enabled\": true,\n \"host\": \"string\",\n \"port\": 0,\n \"systemId\": \"string\",\n \"password\": \"string\",\n \"reconnectIntervalSeconds\": 0,\n \"enquireLinkIntervalSeconds\": 0,\n \"transactionsPerSecond\": 0,\n \"type\": \"string\",\n \"httpApiKey\": \"string\",\n \"httpApiUrl\": \"string\"\n}"
},
"url": {
"raw": "{{baseUrl}}/api/admin/vendors",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"vendors"
]
},
"description": "Creates a new SMPP vendor."
}
},
{
"name": "Get a vendor by ID",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/admin/vendors/:id",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"vendors",
":id"
],
"variable": [
{
"key": "id",
"value": "1"
}
]
},
"description": "Retrieves a single SMPP vendor by its ID."
}
},
{
"name": "Update a vendor",
"request": {
"method": "PUT",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"id\": \"string\",\n \"enabled\": true,\n \"host\": \"string\",\n \"port\": 0,\n \"systemId\": \"string\",\n \"password\": \"string\",\n \"reconnectIntervalSeconds\": 0,\n \"enquireLinkIntervalSeconds\": 0,\n \"transactionsPerSecond\": 0,\n \"type\": \"string\",\n \"httpApiKey\": \"string\",\n \"httpApiUrl\": \"string\"\n}"
},
"url": {
"raw": "{{baseUrl}}/api/admin/vendors/:id",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"vendors",
":id"
],
"variable": [
{
"key": "id",
"value": "1"
}
]
},
"description": "Updates an existing SMPP vendor."
}
},
{
"name": "Delete a vendor",
"request": {
"method": "DELETE",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/admin/vendors/:id",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"admin",
"vendors",
":id"
],
"variable": [
{
"key": "id",
"value": "1"
}
]
},
"description": "Deletes an SMPP vendor."
}
}
]
},
{
"name": "Delivery Reports (DLR)",
"description": "Operations related to message delivery reports",
"item": [
{
"name": "Get DLR Status",
"request": {
"method": "GET",
"header": [],
"url": {
"raw": "{{baseUrl}}/api/dlr/status",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"dlr",
"status"
]
},
"description": "Retrieves the status of all delivery reports."
}
}
]
},
{
"name": "SMS",
"description": "Operations for sending SMS messages",
"item": [
{
"name": "Send an SMS message",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"from\": \"string\",\n \"to\": \"string\",\n \"text\": \"string\",\n \"timestamp\": \"string\",\n \"coding\": \"string\",\n \"internalId\": \"string\",\n \"sessionId\": 0,\n \"gateway\": \"string\",\n \"forwardUrl\": \"string\"\n}"
},
"url": {
"raw": "{{baseUrl}}/api/sms/send",
"host": [
"{{baseUrl}}"
],
"path": [
"api",
"sms",
"send"
]
},
"description": "Sends a new SMS message."
}
}
]
}
]
}