xSignal SMS API Integration Guide

1. Choosing a Protocol

xSignal supports SMPP for persistent high-throughput connections and HTTP REST for simpler backend integrations. Both deliver through the same routing, billing, and delivery-report pipeline.

2. Getting Credentials

Credentials are provisioned by xSignal. You do not self-register API credentials.

• SMPP: you receive a system_id, password, and IP whitelist where applicable.
• HTTP: you receive an API-Key and API-Secret pair. Multiple HTTP credentials can be issued per app, environment, or message type.

Keys can be retrieved through the client portal. Keep all API secrets and SMPP passwords server-side only.

3. SMPP Guide

3.1 Connection

3.2 Binding

Send bind_transceiver, bind_transmitter, or bind_receiver with your system_id and password. bind_transceiver is recommended because it lets you submit and receive delivery reports on the same session.

Successful binds return ESME_ROK. Failed binds may return ESME_RBINDFAIL for bad IP or credentials, or ESME_RALYBND if already bound.

3.3 Sending with submit_sm

Once bound, send a submit_sm PDU with source_addr, destination_addr, short_message, and data_coding. Use registered_delivery = 1 when you want a delivery receipt pushed back to your session.

Insufficient wallet balance returns ESME_RSUBMITFAIL. Exceeding TPS returns ESME_RTHROTTLED, so slow down and retry.

3.4 Delivery Reports

If registered_delivery = 1 and your session is still bound when final carrier status returns, xSignal sends deliver_sm to you. Respond with deliver_sm_resp to acknowledge.

3.5 Keepalive and Unbind

Send enquire_link every 30 seconds. Send unbind to close gracefully. If no valid PDU is received within the response timeout, the server may drop the connection.

3.6 SMPP Status Codes

4. HTTP REST API

4.1 Base URL and Authentication

All HTTP send requests go to your assigned xSignal host.

POST https://<your-assigned-host>/api/http/send
POST https://<your-assigned-host>/api/http/send/bulk

Every request must include X-API-Key and X-API-Secret headers. Invalid or inactive credentials return 401 Unauthorized.

4.2 Send to One or More Recipients

POST /api/http/send sends the same sender and text to every address in receivers. One message record is created per receiver.

{
  "sender": "ABCDE",
  "receivers": ["2348012345678", "2348098765432"],
  "text": "Your OTP is 482913. It expires in 5 minutes.",
  "sms_type": "TRANSACTIONAL"
}

{
  "sent": 2,
  "messages": [
    {
      "our_message_id": "hx_4f3a2b1c9d8e7f6a",
      "provider_message_id": "MC-998877",
      "receiver": "2348012345678",
      "status": "SENT",
      "provider_status": "PENDING",
      "error_code": null,
      "error_message": null
    }
  ]
}

4.3 Send a Batch of Independent Messages

POST /api/http/send/bulk lets each item have its own sender, receiver, text, and sms_type. The response preserves request order.

{
  "messages": [
    {"sender": "ABCDEF", "receiver": "2348012345678", "text": "Your OTP is 482913.", "sms_type": "TRANSACTIONAL"},
    {"sender": "ABCDEF", "receiver": "2348098765432", "text": "50% off today only!", "sms_type": "PROMOTIONAL"}
  ]
}

4.4 Message Status Values

4.5 Routing Rules

Every HTTP credential has one or more active routes tied to sms_type: PROMOTIONAL or TRANSACTIONAL.

4.6 Error Responses

5. Retrieving API Keys

HTTP API keys are retrievable through the client portal, gated behind your session login and a separate numeric passcode. This protects your keys even if a session token leaks.

https://cl.xsignalling.xyz/api

Keep your keys secret. They are returned as plain text on request and should be treated like database passwords.

6. Delivery Report Reconciliation

Regardless of protocol, delivery status updates are tracked centrally. For SMPP, delivery reports can also be pushed live through deliver_sm.

GET /api/portal/webhooks

This uses the same X-Client-ID / X-Token authentication as the rest of the portal.

7. Rate Limits and Best Practices

• Use sms_type correctly: TRANSACTIONAL or PROMOTIONAL.
• For SMPP, prefer bind_transceiver and keep the session alive with enquire_link.
• For HTTP, use /send/bulk for mixed batches instead of looping individual send requests.
• Never hardcode API secrets or SMPP passwords in client-side code.

8. Support

Contact your xSignal account manager for credential provisioning, sender ID registration, or integration issues.

Contact xSignal