I work at Vonage , in the API department.
Our product is often involving real time communication, so is a bidirectional communication. Is making easy to do very complicated stuff like managing phone call, audio, sms, IM messages (whatsapp, facebook, etc..) and much more.
It’s “easy” but not trivial, and the initial configuration and setup can be still pretty tricky for new developers.
That’s why I’ve created this internal tool https://github.com/jurgob/conversation-api-function
In this article I m gonna explain why I did this and what the tool is doing for you, but first I suggest you do the following:
go to the link above, follow the instruction, call your Vonage phone number (you will have one after you follow the tutorial) and hear a computer voice telling you “hello world”. I bet you are gonna do everything in less then 20 minutes!. That’s just to keep you exited! If you have some more time, look also the
Examples list to see how many thing you can do.
What the tool is doing for me? the short version
You want to share an example with someone else? just publish it on Github, if another person want to test it, he can just download it, eventually run `npm install` and run the example. You are gonna run the same code, but you will not share any data or information!.
You may already have everything you need at this point, and you may prefer digging into the examples rather then reading the rest of the article. It’s fine! do it! Possibly have fun and create a new example of a use case I still didn’t think about, I accept pull requests in the read me!
What the tool is doing for me?
note: again, you can use the tool without really knowing all of the following, but is gonna help you in a deeper understanding of the tool and the vonage api itsefls.
In general, when you use our api, you need to do the following steps:
- The very first time, you need to create an account (e.g. My Company)
- once you’ve got an account, (with the related api_key and api_secret), you need to create an application (e.g: My Chat Application or My Telephony Support System)
- Once you create an application you get a private key, you need that to generate a JWT token.
- If you want to program an incoming call or incoming facebook message(e.g. you want to say “hello” to everyone calling you), you need to have Vonage phone number (so called LVN, Long Virtual Number) , and you need to bind it to your application. Also, you need to configure a set of webhook urls with your back end url in order to be notified about something happend in your application (e.g. someone is calling your lvn number)
- if you are implementing the use case in the step 4 and you want to test it locally, then you have to expose your laptop with some tool like localtunnel or ngrok and then update your application’s webhook in order to reach your laptop.
conversation-api-functions is gonna to the step 1/2/3 once you run the
fist_config command. Every time you use
run to run your node function, is gonna do the step 4 and 5.
As soon as the
first_config is creating a new Vonage application, this app is gonna be used for every conversation function you are gonna run in your laptop, and every device where you are gonna run that is gonna use a different application. That’s why if someone else is using your code, the data are not gonna be shared anyhow.
The anatomy of a conversation function
in the same way, all you need to do when you write a conversation function, is to write an
index.js file where you export a js module which export certain methods.
what those methods do, are document here.
you may notice that excluding the handler
routethat is a bit of an exception, every other handler has a 1:1 relationship with the webhook capatilities you can configure in your application. Check the Webhook types section in this link: https://developer.nexmo.com/application/overview, you will notice as instance the first row is
In the cli you just need to implement the
voiceAnswer handler, which is an express middleware.
As you can see you don’t need to be concerned on the part where you configure/update your vonage app, or even spin up your express server.
I’ve briefly introduced this new internal tool to quickly use the Vonage Comunication API, if you have reached this part of the article, probably you now have a working example in your laptop and you’ve learn some notion about the Vonage API echo system. Your next step should now go in the Examples section here: https://github.com/jurgob/conversation-api-function#examples and see how many crazy things you can do!