Setting up Vonage

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

JMP lets you send/receive SMS, picture messages, group texts and more, with international texting and short code support as well. However, we currently can only provide US and Canadian phone numbers there. In order to get a phone number in a different country to use with Cheogram, we currently recommend Vonage. Here's how to set that up:

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

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 "Configure direct message route" 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; ask us if not
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 . 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
• xmpp_component_password
• xmpp_server_hostname
• xmpp_server_port
• http_listen_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). Let us know if you find another API provider we should recommend and/or build an SGX for.

A word from our sponsors...

Providing the above 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.