Setting up Vonage

These instructions are intended for technical and/or motivated individuals who need to text from a non-US/Canadian phone number or want to "self-host". We recommend people who are fine with using a hosted US or Canadian phone number signup for https://jmp.chat/ instead.

Before you signup for Vonage, check to see if they support your country, and how much a number there will cost. You can do so on their site or with handy tables we've made to show you the price/features by country and the price/features by region - note that in some countries Vonage's numbers support only SMS, while in others they support both calling and SMS.

Providing the below SGX services is not free; if you find them useful please consider supporting infrastructure costs on Liberapay, on Patreon, or by becoming a paying customer of JMP.

Get a Vonage account

You can signup at https://dashboard.nexmo.com/sign-up - they ask for name, email, and (in the next screen) phone number. We've confirmed that Vonage will accept a JMP number here.

The signup process appears to give you a test phone number in the country you signup from (and/or that your phone number is from), as well as €2 in your account for testing (note that it may take a few hours for the number and funds to appear). You can text between that test phone number and the signup number, but you need to add extra funds to the account if you want to text with other numbers.

Vonage SGX users have reported outgoing SMS failures (XMPP message appears to send but without receipt confirmation) even with an existing (but low) account balance. For example: if you have a €0.95 account balance and an existing number that costs €0.90/mo, the number may still be flagged as having insufficient balance. The issue is remedied immediately by topping up the Vonage account.

Note that with Vonage, very few countries support MMS. And we haven't implemented MMS in the SGX yet, so it won't yet work in any countries. Assume that any MMS sent to your Vonage number will be silently ignored for now.

Setup incoming call forwarding

We haven't written anything to specifically handle calls with Vonage. But you can just forward incoming calls on your Vonage number to another number through their dashboard. To do that, follow these steps:

1. Login to https://dashboard.nexmo.com/

2. In the left panel, click Numbers then "Your numbers"
3. Click the pencil icon under Manage next to the number you want to add forwarding to
4. Under Voice, change "Forward to" from None to Phone
5. Enter your phone number under Number
6. Leave "Event Webhook URL" empty and click Save

If you want to make outgoing calls, you can write a script to do that, or use https://callwithus.com/ and set your outgoing Caller ID to be your Vonage number.

Using the Vonage SGX run by Soprani.ca

If you don't want to run your own instance of our software to get SGX features on non-US/Canadian numbers, then you can use the one that we at Soprani.ca run. Here's how to do it:

1. Login to https://dashboard.nexmo.com/

2. Copy down the "API key" and "API Secret" values (the "two box" icons will copy them)
3. In the left panel, click Numbers then "Your numbers"
4. Decide which number from this list you're going to use with Cheogram
5. In the left panel, click your name (under Balance), then Settings
6. Under "Default SMS Setting" on the right, enter the following:

   • Delivery receipts: https://vonage.webhooks.soprani.ca/messages

   • Inbound messages: https://vonage.webhooks.soprani.ca/messages

   • HTTP Method: POST-JSON
7. Create a new XMPP account if your existing XMPP account is already used for JMP
8. Login to your XMPP account from a client that supports ad-hoc commands (Movim, Psi, Gajim)
9. Add "cheogram.com" to your roster
10. (Right-)click on cheogram.com and then click on Execute Command
11. Select "Register with backend" and then click Forward or Execute
12. Next to "Gateway JID:" enter "vonage.sgx.soprani.ca" (without the quotes) and click Next
13. Enter the API Key, API Secret, and number (starting with '+') from steps 2 and 4, click Next

14. Registration should succeed if all your info is correct; if not, ask us from your chat client or on the web

15. Send and receive messages as you would with JMP; see here for details

Using your own instance of the Vonage SGX

If you'd rather run your own instance of the Vonage SGX, start by cloning the SGX from https://gitlab.com/soprani.ca/sgx-vonagev0 . Next, download and compile https://ossguy.com/tai.c - the binary should be a "tai" file in the sgx-vonagev0 directory. Then run "bundle install" in that directory (installing ruby-bundler if needed). After that you can start the SGX by running "bundle exec ./sgx-vonagev0.rb" - this will give you the usage string.

These are the expected parameters that it lists, and the values you need to use:

• xmpp_component_jid - a JabberID for the SGX that your XMPP server is configured to host (e.g. vonage.sgx.example.com)

• xmpp_component_password - the password used to login to your component JID on your XMPP server (see here for an example)

• xmpp_server_hostname - the hostname of your XMPP server (could be 127.0.0.1 if run on the same host as the SGX)
• xmpp_server_port - the port your XMPP server uses for components (e.g. 5347)
• http_listen_port - the port that the SGX will listen on for incoming messages and delivery receipts from Vonage (used below)

Configuring components on an XMPP server is beyond the scope of this documentation. An example of where to find such resources would be the Prosody components documentation.

Additionally, the Vonage SGX requires Redis. Most distributions have a Redis package, or you can install it from source. See the Redis Quick Start guide for more details (note that the below assumes you're using the default port).

Now you can run the SGX, using a command like this:

$ REDIS_URL=redis://127.0.0.1:6379/ bundle exec ./sgx-vonagev0.rb vonage.sgx.example.com my_password 127.0.0.1 5347 12345

Assuming that it works (which it should if your XMPP server is correctly configured to accept the SGX component), you now have a working SGX! You just need to wire it up to Vonage in order to send and receive SMS:

1. Login to https://dashboard.nexmo.com/

2. Copy down the "API key" and "API Secret" values (the "two box" icons will copy them)
3. In the left panel, click Numbers then "Your numbers"
4. Decide which number from this list you're going to use with your SGX (via Cheogram)
5. In the left panel, click your name (under Balance), then Settings
6. Under "Default SMS Setting" on the right, enter the following (this is insecure - see below):

   • Delivery receipts: http://[your_hostname]:[http_listen_port]

   • Inbound messages: http://[your_hostname]:[http_listen_port]

   • HTTP Method: POST-JSON
7. Create a new XMPP account if your existing XMPP account is already used for JMP
8. Login to your XMPP account from a client that supports ad-hoc commands (Movim, Psi, Gajim)
9. Add "cheogram.com" to your roster
10. (Right-)click on cheogram.com and then click on Execute Command
11. Select "Configure direct message route" and then click Forward or Execute
12. Next to "Gateway JID:" enter [xmpp_component_jid] and click Next
13. Enter the API Key, API Secret, and number (starting with '+') from steps 2 and 4, click Next

14. Registration should succeed if all your info is correct; if not, ask us from your chat client or on the web

15. Send and receive messages as you would with JMP; see here for details

You're all set! If you're not receiving SMS or delivery receipts for some reason, make sure that http://[your_hostname]:[http_listen_port] is accessible from the Internet (you may need to configure the firewall on your server to allow the [http_listen_port] you picked). To ensure the messages coming from Vonage to your server are encrypted, we recommend you setup a proxy (e.g. using ProxyPass) to your SGX's HTTP port.

Why Vonage?

There are other API providers that we could have used for letting people use phone numbers from other countries through Cheogram, but Vonage was the only one we could find that let anyone signup. For example, Twilio requires a phone number to signup but doesn't let you use a JMP number. And Plivo requires you to use a "work email" address (they explicitly block @gmail.com addresses). If you find another API provider, feel free to write an SGX for it! Let us know from your chat client or on the web and we can promote it.