Featured Image

Mobile-friendly Gateway to any SIP Provider

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_SECRET="some random secret 2" \
    -e ASTERISK_COMPONENT_SECRET="some random secret 1" \
    -e \
    -e SIP_USER=your_sip_username \
    -e SIP_PASSWORD=your_sip_password \
    -e \

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

Cheogram Android Dialler
Cheogram Android Dialler

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.

Signup with Cheogram Android

Welcome to! If you are looking for a simple guide on how to sign up for JMP, then you have come to the right place! We will be keeping this guide up-to-date if there is ever a change in how to sign up.

We will first start with signing up from within your Jabber chat application on mobile, where you will never need to leave the client to get set up. I will be using the freedomware Android client Cheogram to do this signup. To start us off, we will need to create a Jabber ID (or “JID”). Upon first opening the app you will be presented with a welcome screen where you can choose to signup using the built-in flow for, or you can choose your own server.

Main Startup Screen Account User Creation Password Creation

We will choose “I need to sign up” for the purposes of this guide, but you are definitely free to choose whatever service you like, or bring your own! On the first screen of the server signup it will ask you to enter a username; this can be anything you want as long as it isn’t already in use on the server. After tapping Next, it will ask you to create a password for this account; length does not seem to be limited so create one as long as you want. Do not forget it, or use a password manager to create/store the password! Tapping Next again will log you in and offer to set an avatar for your account, you can set one now or choose to do so at a later time, if at all.

Captcha Profile Avatar Service Selectioin

Once you are logged in Cheogram will immediately open the sign-up screen with the Cheogram Bot, where you can select which service you are planning to set up. Once you tap on the JMP logo you will be presented with a number search box. Here you can search by Area Code, State (or Province), City/State, Zip Code, or even a vanity pattern by placing the tilde (~) character first followed by up to 4 numbers. You will then be presented with a scrollable list of numbers to choose from, tap on one and then tap next to continue on. On the nex tpage you will choose how to activate your account, with the options of Credit Card, Bitcoin, Referral Code, Mail or e-Transfer. You must also choose which currency you will be using. After selecting one of the four payment options, the next screen will either ask for paymment by the chosen method with details on how to pay, or activate your account if you used a valid referral code.

Number Search Number Search Results Payment Method

Once your account has been activated you will be presented with the command UI of the bot, which has all of your account options, settings and details. Tapping “Show Account Info” will display your phone number, account balance and other useful information. Exiting from this view you should be presented with a popup asking if you want to enable Dialer Integration and grant Microphone permissions, tap yes to enable these features and be taken through the setup of dialer integration.

Command UI Account Info Dialer Integration Permission

Mic Permissions Dialog Calling Accounts Make Calls With Priority

At some point you will also be asked if you want to download the default stickers for use in your chats, if you do tap “YES” and then it will prompt you for Media access permissions (this will allow Cheogram to access labelled folders inside the common media locations such as Downloads, Pictures, Documents, Movies). Tap to allow access permissions and Cheogram will download them in the background. Bonus: you can also download sticker packs from any other site and then load them into Cheogram!

Sticker Download Media Access Dialog Battery Optomization

Now that you have activated your account and set up dialer integration you are able to place calls, even from your native dialer, SMS or MMS with your contacts. To add a contact within Cheogram is quite easy with the contacts integration. Now that the bot has been added to your account contacts, your device’s contacts should already be visible when you tap on the “chat” icon to start a new chat, or you can do the following to add a contact to your Jabber server. First tap the chat icon, tap the “+”, then “add contact”. The first thing you should notice that is different this time with the dialog box that pops up is that it now has two selectable buttons: Jabber ID, and PSTN. The PSTN option makes adding telephone numbers for calling or sending SMS to very easy, just type out the phone number you wish to add to your contacts and then tap CALL or MESAAGE, depending on what you wish to do first. This will automatically format the phone number according to the locale detected on your device. If you need to add an international number, you will need to add the phone in the full international format to override the country code being automatically added. With the contact now added, you can either start typing out a message, or tap the “phone” icon that appears at the top to make an audio call to the contact. Images, videos and audio files can also be sent using a number from JMP.

Contacts Permissions Add Contact 1 Add Contact Form

Featured Image

How to use Jabber from SMS

The 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, 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:


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.

How to Subscribe to This Blog Using Movim

This blog is powered by XMPP. That means it is federated over the Jabber network, it has a Jabber ID, and you can subscribe to it using a supporting Jabber client. One such client with support for subscribing, liking, and commenting is Movim. There are several public Movim instances including one hosted by upstream and one by chatterboxtown. Once you are logged in with a Movim instance, you can follow these steps to discover this blog and subscribe.

  1. Click Explore

    in the left navigation menu
  2. Click

    Communitites Servers
  3. If is not yet known to this instance, you can use the search box to add it

    Search for a new server
  4. After entering in the search box and hitting enter, you may need to click away to any other Movim page and then come back to the Communities Servers area as before.
  5. Click
  6. Click

    JMP Blog
  7. Click

  8. New posts from the blog will now show up under News

    in the left navigation menu 

Creative Commons Attribution ShareAlike