Connect Kannel to TelecomsXchange

Kannel 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.

Before you start#

• An SMPP 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 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:

# 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:

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:

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.

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:<message_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:

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:

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.

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?#

References#

• Kannel user guide: SMPP smsc group, unified-prefix, sendsms, DLRs and HTTP administration
• opensmppbox user guide (Kannel add-on)
• opensmppbox example configuration and smpplogins.txt