We have for a long time supported the public Cheogram SIP instance, which allows easy interaction between the federated Jabber network and the federated SIP network. When it comes to connecting to the phone network via a SIP provider, however, very few of these providers choose to interact with the federated SIP network at all. It has always been possible to work around this with a self-hosted PBX, but documentation on the best way to do this is scant. We have also heard from some that they would like hosting the gateway themselves to be easier, as increasingly people are familiar with Docker and not with other packaging formats. So, we have sponsored the development of a Docker packaging solution for the full Cheogram SIP solution, including an easy ability to connect to an unfederated SIP server

XMPP Server

First of all, in order to self-host a gateway speaking the XMPP protocol on one side, you’ll need an XMPP server. We suggest Prosody, which is already available from many operating systems. While a full Prosody self-hosting tutorial is out of scope here, the relevant configuration to add looks like this:

Component "asterisk"
    component_secret = "some random secret 1"
    modules_disabled = { "s2s" }
Component "sip"
    component_secret = "some random secret 2"
    modules_disabled = { "s2s" }

Note that, especially if you are going to set the gateway up with access to your private SIP account at some provider, you almost certaintly do not want either of these federated. So no DNS setup is needed, nor do the component names need to be real hostnames. The rest of this guide will assume you’ve used the names here.

If you don’t use Prosody, configuration for most other XMPP servers should be similar.

Run Docker Image

You’ll need to pull the Docker image:

docker pull singpolyma/cheogram-sip:latest

Then run it like this:

docker run -d \
    --network=host \
    -e COMPONENT_DOMAIN=sip \
    -e COMPONENT_SECRET="some random secret 2" \
    -e ASTERISK_COMPONENT_DOMAIN=asterisk \
    -e ASTERISK_COMPONENT_SECRET="some random secret 1" \
    -e SIP_HOST=sip.yourprovider.example.com \
    -e SIP_USER=your_sip_username \
    -e SIP_PASSWORD=your_sip_password \
    -e SIP_JID=your-jabber-id@yourdomain.example.com \
    singpolyma/cheogram-sip:latest

If you just want to connect with the federated SIP network, you can leave off the SIP_HOST, SIP_USER, SIP_PASSWORD, and SIP_JID. If you are using a private SIP provider for connecting to the phone network, then fill in those values with the connection information for your provider, and also your own Jabber ID so it knows where to send calls that come in to that SIP address.

Make a Call

You can now make a call to any federated SIP address at them\40theirdomain.example.com@sip and to any phone number at +15551234567@sip which wil route via your configured SIP provider.

You should even be able to use the dialler in Cheogram Android:

Inbound calls will route to your Jabber ID automatically as well.

What About SMS?

Cheogram SIP does have some basic support for SIP MESSAGE protocol, so if your provider has that it may work, but more testing and polish is needed since this is not a very common feature at providers we have tested with.

Where to Learn More

If you have any questions or feedback of any kind, don’t hesistate to stop by the project channel which you can get on the web or using your Jabber ID.

A big part of the vision of Sopranica, and Cheogram in particular, is bidirectional gateways.  A bidirectional gateway is one that allows (at a minimum) any user of either protocol to contact any user of the other protocol without creating an account.  This is not possible with all protocols, but works well when both sides are federated.

Simple Example

Take for instance sip.cheogram.com, which is a bidirectional gateway between XMPP and SIP.  Any federated Jabber ID can communicate with any federated SIP URI with no configuration at the gateway.  This is possible because every valid SIP URI is assigned a Jabber ID of the format xmpp:user\40domain.tld@sip.cheogram.com and every Jabber ID is assigned a SIP URI of the format sip:user%40domain.tld@sip.cheogram.com.

Contrast this with irc.cheogram.com, which is not a bidirectional gateway even though IRC is an open protocol, due to the non-federated nature of that protocol.  While every IRC channel and nick is given a Jabber ID, not every Jabber ID can be given a channel or nick on every IRC network out there, and even to do it on a single network would require creating many connections or a special peering arrangement.  Using the Jabber ID assigned to an IRC channel may require registering a nick with that IRC network and configuring the associated password at the gateway.  It works well enough, and is quite useful, but it’s not bidirectional.

User Experience

One of the big advantages of a bidirectional gateway is the seamless user experience for those who know the gateway exists.  Instead of asking “is this room bridged to protocol X” or “do you also have an address on protocol Y” the existance of the bridge is sufficient to know that, yes, with no extra setup by either party, communication will be possible.  One does not need to convince users to switch to the favored protocol, or bend by creating an identity with the other’s favored protocol, but simply to add the other party directly.  Users with Jabber IDs can advertise how they may be contacted via SIP, SMTP, Matrix, SMS, and more without the other party thinking anything more than “this address looks a bit long”.

Raising the Whole Network with Chaining

Because a high-quality bidirectional gateway effectively makes one network out of two networks, any service or gateway added to either network can be used from both sides.  Thus, Matrix, SMTP, or even SMS users can get phone numbers from JMP.  Even further than that, a Matrix user could advertise an SMTP or SIP contact address using the Cheogram gateways, all without any SMTP or SIP gateway needing to exist for Matrix at all.

Stable Addresses

If someone is going to give out an address that goes via a gateway, they need confidence that this address will not need to be changed.  So long as their main address on their preferred protocol remains the same, so should their address on other protocols.  This requires a stable DNS name with gateways that are open to anyone, free of charge.  That is the vision behind Cheogram, an infrastructure project inside of Sopranica to maintain stable addressing for bidirectional gateways.

Conclusion

Obviously there is still lots of work to do. Most of the gateways mentioned in this post are missing important features they could have in order to facilitate more seamless communication.  Clients of every protocol can gain features to make using a bidirectional gateway a more obvious choice for users.  Unique use cases need more testing to find where the rough edges are.  Cheogram infrastructure is supported in part by JMP, but can always use financial support.  Together we can help people connect to all their contacts.  Come join us.

The Soprani.ca project, and Cheogram in particular, is pretty big on bidirectional gateways.  The most popular Cheogram-hosted instance, so popular that it gets to own Jabber IDs on cheogram.com, is a bidirectional gateway to the telephone network.  How is it bidirectional?  Don’t you need a Jabber ID to use it?  Of course not!

Sending a Message

From any SMS-enabled device, add +12266669977, which is the gateway’s phone number.  Send the following SMS:

/msg someone@server.tld Hello!

The user with Jabber ID someone@server.tld should shortly receive your message.  If they reply, what you see will depend on their relationship to the gateway.  If they have a backend route set (such as JMP, Vonage, or Twilio) then you will get an SMS from their associated phone number.  If not, you will get a message from the gateway’s number like this:

<someone@server.tld says> Oh, fun!

Joining a Chatroom

An SMS user can also join exactly one chatroom at a time.  Send this to the gateway’s number:

/join someroom@conference.server.tld

You should receive a message with the current list of participants, after which you will start seeing messages sent to the room.  After this point, any SMS send to the gateway’s number that is not a valid command (such as /msg) will be sent to your joined room as a message.  You can send /help at any time to get a list of other commands for leaving, setting your nickname, etc.

Making a Voice Call

To call a Jabber ID, first enter it into this form then dial one of the access numbers and follow it up with the extension generated by the form.

The extensions are often very long, so the easiest way to dial them on Android is to create a contact with a phone number of the form:

+access_number,*10816etc

If you have trouble with one access number, try another one.  If the Jabber ID you wish to call is very long some access numbers may time-out waiting for you to dial all the digits.