SMSDESK Configuration Guide

Complete guide to configuring your SMSDESK deployment for SMS messaging, webhooks, and API integration.

Accessing the Portal

Login

1. Navigate to your SMSDESK portal (e.g., https://desk.sms.com.na)
2. Enter your username and password
3. Click Sign In

Navigation

After login, you'll see the main dashboard. Key sections:

• Account → SMS Channels - Configure SMS channels and webhooks
• Account → Users - Manage user accounts and API keys
• Account → Cron Jobs - Schedule automated tasks
• Monitor - View real-time message statistics

SMS Channel Configuration

Step 1: Access SMS Channels

1. Click Account in the main menu
2. Select SMS Channels
3. Click on an existing channel or create a new one

Step 2: Basic Channel Settings

Incoming SMS Configuration

Message Forwarding Options

Incoming SMS Webhook (HTTP POST JSON)

Webhook Configuration

Delivery Report (DLR) Webhook

Receive real-time notifications when messages are delivered, failed, or expire.

Opt-out Webhook

Receive notifications when users send "STOP" to unsubscribe from your messages.

Complete Webhook Setup Example

Channel: 33333 (Incoming) / 44880 (Outgoing)
Status: ✓ Enabled

📨 Incoming SMS Webhook:
   Handler: HTTP POST (JSON)
   URL: https://api.yourcompany.com/sms/incoming
   Secret: 64-character secure key (generated)

📊 Delivery Report Webhook:
   URL: https://api.yourcompany.com/sms/dlr
   Secret: (same as above)

🚫 Opt-out Webhook:
   URL: https://api.yourcompany.com/sms/optout
   Secret: (same as above)

🔒 Security Key: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2

Security Key Management

Generating a Secure Key

1. In the SMS Channel configuration page, locate the Security Key (API) field
2. Click the Generate button
3. A cryptographically secure 64-character key will be generated
4. Copy this key to your application configuration
5. Click Save Settings

Key Usage

The Security Key is used for:

• Incoming SMS Webhooks: HMAC-SHA256 signature in X-Signature header
• DLR Webhooks: HMAC-SHA256 signature in X-Signature header
• Opt-out Webhooks: HMAC-SHA256 signature in X-Signature header
• Legacy GET/SOAP: Passed as securitykey parameter

API Key Configuration

Generating API Keys

1. Navigate to Account → Users
2. Click on the user who needs API access
3. Scroll to the API Access section
4. Click Generate API Key
5. Copy the generated key immediately (it won't be shown again)
6. Click Save

Using API Keys

API keys are used for authenticating SMS API requests:

curl -X POST https://{host}/sms/2/messages \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "destinations": [{"to": "+264811234567"}],
      "text": "Hello from SMSDESK!"
    }]
  }'

SMPP Server Configuration

SMPP Connection Details

Channel Routing

Messages sent via SMPP are automatically routed using your account's default channel configured in the portal. The source_addr field in the PDU is ignored.

Test SMPP Connection (Python)

import smpplib.client

client = smpplib.client.Client('sms.com.na', 2775)
client.connect()
client.bind_transmitter(
    system_id='your-email@example.com',
    password='rqym36t4'  # First 8 chars of API key
)
client.send_message(
    source_addr='Any',  # Ignored - default channel used
    destination_addr='264811234567',  # No + prefix
    short_message=b'Test from SMPP!'
)
print('✓ Message sent!')
client.unbind()
client.disconnect()

For full SMPP documentation, see the SMPP Server API Documentation.

Testing Your Configuration

Test 1: Send SMS via API

# Replace YOUR_API_KEY with your actual API key
curl -X POST https://{host}/sms/2/messages \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "44880",
      "destinations": [{"to": "+264811234567"}],
      "text": "Test message",
      "deliveryReport": true
    }]
  }'

# Expected response:
{
  "bulkId": "BULK-...",
  "messages": [{
    "to": "+264811234567",
    "messageId": "...",
    "status": {
      "groupName": "PENDING",
      "name": "PENDING_ACCEPTED"
    }
  }]
}

Test 2: Verify Incoming SMS Webhook

1. Send an SMS to your incoming shortcode (e.g., 33333)
2. Check your webhook endpoint logs
3. Verify the X-Signature header is present
4. Verify signature using the code examples in Incoming SMS Webhook Documentation

Test 3: Verify DLR Webhook

1. Send a test SMS with "deliveryReport": true
2. Wait for delivery (usually 5-30 seconds)
3. Check your DLR webhook endpoint logs
4. Verify the payload contains messageId, status, statusCode

Test 4: Verify Opt-out Webhook

1. Send "STOP" to your outgoing shortcode (e.g., 44880)
2. Check your opt-out webhook endpoint logs
3. Verify the contact is blacklisted in the portal
4. Try sending to that number - should be rejected

Troubleshooting

Webhooks Not Receiving Requests

Signature Verification Failing

API Authentication Failing

Best Practices

Security

• ✅ Always verify HMAC signatures on webhooks
• ✅ Use HTTPS for all webhook URLs
• ✅ Rotate security keys every 90 days
• ✅ Store keys in environment variables, not code
• ✅ Use different keys for dev/staging/production

Performance

• ✅ Return 200 OK quickly from webhooks (process async)
• ✅ Implement idempotency (same webhook may be sent twice)
• ✅ Log all webhook attempts for debugging
• ✅ Use bulk SMS API for sending multiple messages

Reliability

• ✅ Implement retry logic for failed API calls
• ✅ Monitor webhook endpoint uptime
• ✅ Set up alerts for webhook failures
• ✅ Keep webhook endpoints simple and fast