XMPP Component (XEP-0114) to send and receive SMS
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



sms-over-xmpp is an XMPP component (XEP-0114) that acts as a gateway between an XMPP network and the SMS network. It allows you to send and receive SMS messages as if they were XMPP messages, using your favorite XMPP client.

You send an XMPP message and your friend receives an SMS. When she responds by SMS, you receive an XMPP message.


You'll need the following available to install and run sms-over-xmpp.

Twilio account

You need a Twilio account to interact with the phone network. Eventually I'd like to add support for other telephony providers, but Twilio is all that's supported for now.

After creating your account, create an API Key. Make note of the Key SID and Key Token for later in the installation. This key allows sms-over-xmpp to send outgoing SMS on your behalf.

To send and receive SMS, you'll also need a Twilio phone number. Unfortunately, a verified number cannot send SMS. It must be a Twilio number.

XMPP server

sms-over-xmpp is an XMPP component as defined in XEP-0114. That means that it needs an existing XMPP server to interact with the XMPP network. There are several open source XMPP servers available. My favorite is Prosody. It's easy to configure and operate. ejabberd is another popular choice.

Once your XMPP server is running, you'll need to add an external component for sms-over-xmpp. Instructions are available:

You'll need to enter the component's host name and password in your sms-over-xmpp configuration file later.

Receive HTTP requests

If you want to receive incoming SMS, the server on which sms-over-xmpp runs must be able to receive incoming HTTP requests. This is how your telephony provider delivers messages to sms-over-xmpp. Ideally you should support TLS so that your incoming SMS are kept private in transit.

Configuration details can vary greatly depending on your local circumstances. At a minimum, you can open a high numbered port on your firewall so that your telephony provider can make HTTP requests directly to sms-over-xmpp.


Install the binary with

go get github.com/mndrix/sms-over-xmpp/...

Write a config file (config.toml is a common name):

# define how to connect to your XMPP server
host = ""
port = 5347
name = "sms.example.com"
secret = "shared secret from your XMPP server config"

# Twilio API details
account-sid = "AC..."
key-sid = "SK..."
key-secret = "..."

# map XMPP usernames to E.164 phone numbers
"john@example.com" = "+13075551212"

Run your SMS component:

sms-over-xmpp config.toml

To receive incoming SMS, you also have to associate each of your Twilio phone numbers with a messaging URL. It's usually easiest to configure a TwiML App then attach it to each of your phone numbers. The messaging URL is the address through which Twilio can contact sms-over-xmpp with an HTTP request.