--- title: Connect Kannel to TelecomsXchange url: https://help.telecomsxchange.com/integrations/kannel/ audience: Integrations summary: Add a group = smsc with smsc = smpp, host = smpp01.telecomsxchange.com, port = 2776, transceiver-mode = true and your account's SMPP System Id and SMPP Password as smsc-username and smsc-password. Set unified-prefix = "TECH_PREFIX#,+,00" on that group so +447700900123 leaves as 80039#447700900123. To sell SMS, Kannel needs the opensmppbox add-on to accept TelecomsXchange's bind. updated: '2026-10-23' verified_commit: 83b4ebc96d0081a25213776d5a8871bd04941125 --- # Connect Kannel to TelecomsXchange > Add a group = smsc with smsc = smpp, host = smpp01.telecomsxchange.com, port = 2776, transceiver-mode = true and your account's SMPP System Id and SMPP Password as smsc-username and smsc-password. Set unified-prefix = "TECH_PREFIX#,+,00" on that group so +447700900123 leaves as 80039#447700900123. To sell SMS, Kannel needs the opensmppbox add-on to accept TelecomsXchange's bind. ## Kannel to TelecomsXchange over SMPP 1. **Your application**: HTTP sendsms to smsbox, to=+447700900123 2. **Your Kannel** (via `smsc=tcxc`): bearerbox smsc group, transceiver bind 3. **TelecomsXchange** (via `80039#447700900123`): smpp01, TCP 2776 4. **Seller's SMSC**: The SMS route you purchased [Kannel](https://www.kannel.org/) connects to TelecomsXchange like to any SMSC: one `smsc` group in bearerbox makes the transceiver bind, and smsbox takes your applications' HTTP requests. This guide adds the TelecomsXchange link, prefixes every number with your route's tech prefix, wires up delivery receipts and covers the selling direction, which needs the opensmppbox add-on. For the values themselves, see [Connect an SMPP platform](https://help.telecomsxchange.com/integrations/connect-smpp-platforms/). ## Before you start - An [SMPP account](https://help.telecomsxchange.com/buyers/create-your-first-account/) with its **SMPP System Id** and **SMPP Password**. Set its **IP Address** to your Kannel server's public IP, for example `203.0.113.10`. - An [SMS route](https://help.telecomsxchange.com/buyers/find-and-buy-routes/) and its tech prefix from **My Interconnections**, for example `80039`. Below, `TECH_PREFIX` stands for it. - A sender ID registered on the account (see **Sender Settings** on **Logs → SDR (SMS)**). - Kannel 1.4 or later with a working `core` and `smsbox` group. ## How do I send SMS through TelecomsXchange? 1. Add an `smsc` group to `kannel.conf`: ```ini # TelecomsXchange: one transceiver bind group = smsc smsc = smpp smsc-id = tcxc host = smpp01.telecomsxchange.com port = 2776 transceiver-mode = true # bind_transceiver on 'port'; no receive-port smsc-username = SYSTEM_ID # account's SMPP System Id smsc-password = PASSWORD # account's SMPP Password interface-version = 34 # SMPP 3.4 enquire-link-interval = 30 reconnect-delay = 10 max-pending-submits = 10 throughput = 10 # keep at or below the account's SMPP Rate Limit (req/sec) # Put the tech prefix in front of every number sent on this link: # +447700900123 or 00447700900123 becomes 80039#447700900123 unified-prefix = "TECH_PREFIX#,+,00" ``` `SYSTEM_ID` and `PASSWORD` are the account's credentials; replace `TECH_PREFIX` with the route's prefix, keeping the `#`: `unified-prefix = "80039#,+,00"`. 2. Send messages to this link only. Either force it on the sendsms user: ```ini group = sendsms-user username = app password = APP_PASSWORD forced-smsc = tcxc default-sender = MyBrand # a sender ID registered on your account max-messages = 10 # allow long messages to be split concatenation = true ``` or pass `smsc=tcxc` on each request. 3. Restart bearerbox and smsbox. 4. Have your applications send numbers in international format with `+` or `00`, so the `unified-prefix` rule matches: ```bash curl -G "http://127.0.0.1:13013/cgi-bin/sendsms" \ --data-urlencode "username=app" \ --data-urlencode "password=APP_PASSWORD" \ --data-urlencode "to=+447700900123" \ --data-urlencode "from=MyBrand" \ --data-urlencode "text=Test from Kannel" \ --data-urlencode "dlr-mask=3" \ --data-urlencode "dlr-url=http://127.0.0.1/dlr?id=42&status=%d" ``` `unified-prefix` replaces the leading `+` or `00` with `TECH_PREFIX#`, so the `submit_sm` leaves with `destination_addr` `80039#447700900123`. A number sent without `+` or `00` doesn't match the rule and goes out plain, which TelecomsXchange sends through your account's default route. !!! tip To use a routing group instead of one route, put the group's prefix in the rule: `unified-prefix = "444123#,+,00"`. To send through two different routes, define two `smsc` groups with different `smsc-id` values and prefixes and choose with `smsc=` per request. ## How do I receive delivery receipts? Ask for a receipt with `dlr-mask` (1 delivered, 2 not delivered; `3` for both) and a `dlr-url`. Kannel sets `registered_delivery` on the `submit_sm`, stores the `message_id` from the `submit_sm_resp`, and when TelecomsXchange sends the `deliver_sm` with `id:` and `stat:DELIVRD` on the same bind, it calls your `dlr-url` with `%d` set to the delivery state. Keep the link up: receipts are relayed only to an open bind. If a receipt arrives that Kannel can't match, set `msg-id-type` on the `smsc` group to the number base the IDs use (see References). ## How do I receive SMS from TelecomsXchange as a seller? Kannel's bearerbox only connects out to SMSCs; it doesn't accept SMPP binds. To let TelecomsXchange bind to you, install **opensmppbox**, a separate Kannel add-on that listens for SMPP clients and passes their messages to bearerbox, which delivers them through your own `smsc` links. 1. In `kannel.conf`, make sure the `core` group has `smsbox-port` set (for example `13001`) and a DLR store; opensmppbox connects to bearerbox on that port. 2. Create `opensmppbox.conf`: ```ini group = opensmppbox opensmppbox-id = tcxc-in opensmppbox-port = 2775 # the port you enter on your TelecomsXchange SMS route bearerbox-host = 127.0.0.1 bearerbox-port = 13001 # bearerbox smsbox-port our-system-id = MYSMSC route-to-smsc = my-operator-link # smsc-id of the link that delivers the traffic use-systemid-as-smsboxid = true # match logins on system ID and password only smpp-logins = /etc/kannel/smpplogins.txt log-file = /var/log/kannel/opensmppbox.log ``` 3. Add TelecomsXchange to `/etc/kannel/smpplogins.txt`: system ID, password, system type and the allowed source IP: ```text TCXC_SYSTEM_ID TCXC_PASSWORD tcxc 174.136.44.213 ``` Use the same **SMPP System Id** and **SMPP Password** you set on your SMS route under **Routes → My Routes**. 4. Start opensmppbox, allow `174.136.44.213` to port 2775 on your firewall, and on the route enter your server as `IP:2775`, **SMPP Version** **3.4**, **TLS** **No**. !!! warning Without `use-systemid-as-smsboxid = true`, opensmppbox also compares the bind's `system_type` with the third column of `smpplogins.txt`, and a mismatch refuses the bind. Leave it on. opensmppbox answers each `submit_sm` and sends receipts back to the bind as `deliver_sm` when the message was submitted with `registered_delivery`, which TelecomsXchange always sets. **Inbound SMS for numbers you sell**: add a second `smsc` group with `smsc-id = tcxc-did`, the same host and port, `smsc-username = did` and `smsc-password = did` (or your custom DID credentials), no `unified-prefix`, and route messages for those numbers to it. Buying numbers works the other way round: TelecomsXchange binds to the **SMPP Endpoint** on your number, so it also needs opensmppbox. ## How do I test it? 1. Open the bearerbox status page: `http://127.0.0.1:13000/status?password=STATUS_PASSWORD`. The `tcxc` link should show **online**. On TelecomsXchange, the account's **Bind Status** shows **ONLINE**. 2. Send the `curl` request above to a test handset. 3. In the bearerbox log, find the `submit_sm` with `destination_addr: "80039#447700900123"` and its `submit_sm_resp` with status 0, then the `deliver_sm` receipt. Use `log-level = 0` while testing. 4. Go to **Logs → SDR (SMS)**, choose **All Messages** and click **Search SMS**. ## What if something goes wrong? | You see | What to do | |---|---| | Link never goes online; log shows bind status `0x0D` | Check `smsc-username` and `smsc-password`, and that Kannel binds from the account's IP address or an additional allowed IP. | | `submit_sm_resp` status `0x45` (69) | The message was refused: no route or rate for the prefix, blocked route, low balance, sender ID not allowed or rate limit. Check **Failed Only** in the SDR. Lower `throughput` if you hit the rate limit. | | Messages go to the default route | `destination_addr` has no prefix: the number wasn't sent with `+` or `00`, or `unified-prefix` is on another group. | | sendsms rejects the `to` number | You put `#` in `to`, which isn't in the default `sendsms-chars`. Send `+447700900123` and let `unified-prefix` add the prefix, or add `#` to `sendsms-chars`. | | Status `0x01` | The route takes single messages only. Enable `concatenation` so Kannel sends UDH parts. | | Status `0xFE` (254) or `0x08` | The seller timed out or the platform failed to forward. Kannel retries according to its queue; use a routing group with a failover route. | | No DLR reaches your `dlr-url` | Check `dlr-mask`, that the link stayed online, and `msg-id-type`. The SDR still shows the delivered status. | | Selling: Test Bind "has FAILED" | The system ID or password don't match `smpplogins.txt`, or `use-systemid-as-smsboxid` is off. | | Selling: "host/port is probably unreachable" | opensmppbox isn't listening on that port or `174.136.44.213` is blocked. | ## References - [Kannel user guide: SMPP smsc group, unified-prefix, sendsms, DLRs and HTTP administration](https://www.kannel.org/download/1.4.5/userguide-1.4.5/userguide.html) - [opensmppbox user guide (Kannel add-on)](https://svn.kannel.org/opensmppbox/trunk/doc/userguide.xml) - [opensmppbox example configuration and smpplogins.txt](https://svn.kannel.org/opensmppbox/trunk/example/) ## Frequently asked questions **Q: Can I put 80039#447700900123 straight into the sendsms to parameter?** A: Only if you add # to sendsms-chars in the smsbox group; by default Kannel accepts only 0123456789+- in to. The unified-prefix rewrite avoids that and keeps your applications sending plain numbers. **Q: Can Kannel sell SMS routes on TelecomsXchange?** A: Not on its own: bearerbox only connects out to SMSCs. To accept TelecomsXchange's SMPP bind you need opensmppbox, a separate Kannel add-on that listens for SMPP clients and hands their messages to bearerbox. **Q: Which dlr-mask should I use?** A: 3 (delivered plus non-delivered to phone) is enough. TelecomsXchange relays the seller's final receipt to your bind as stat:DELIVRD. **Q: Does Kannel split long messages?** A: Yes, if the sendsms-user allows it: set max-messages above 1 and concatenation = true. Each part is billed as one segment.