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.

---

1. Authentication

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_ADMIN environment 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-keys endpoints.

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.

---

2. Sending SMS Messages

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.

---

3. Handling Delivery Receipts (DLRs) via Webhooks

Sendium supports automatic forwarding of Delivery Receipts to your external systems via Webhooks.

Global vs. Message-Specific Webhooks

1. Global Webhook: Set via the quarkus.rest-client.dlr-forwarding.url environment variable. All DLRs will be sent here by default.
2. Message-Specific Webhook: Passed in the forwardUrl field when sending the SMS. This overrides the global webhook for that specific message.

Webhook Payload Format

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.

---

4. Administrative API Endpoints

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 (Requires VendorConf object).
  • 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.