conversation-api-function
v0.0.17
Published
conversation-api-function is an opnionated tool to start using vonage conversation api https://developer.nexmo.com/conversation
Downloads
6
Readme
conversation-service-functions
what is this project?
this is a cli tool that will allow you to write simple application for the Vonage conversation api https://developer.nexmo.com/conversation in your local env with minimal configuration.
install prerequisites
nexmo credentials
To make this app running, you need
- a nexmo api key, api secret : https://dashboard.nexmo.com
- a nexmo phone number (also known as LVN, Long Virtual Number) : https://dashboard.nexmo.com/buy-numbers
install node 14+
suggested way to install node is via nvm (https://github.com/nvm-sh/nvm/pulls). so:
install nvm
if you have brew install, just run
brew install nvm
if not, then
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
(read here for more details: https://github.com/nvm-sh/nvm)
install node with nvm
now that nvm is installed, just run:
nvm install 14
install the tool
npm install -g conversation-api-function
first time config
the first time you run this, you need to have your api-key, api-secret and an lvn (look the prerequisites section above):
conversation-api-function config-new -a <api-key> -s <api-secret> -l <lvn>
if you struggle with this, run:
conversation-api-function config-new -h
create a new conversation function
conversation-api-function new my_capi_fn
run it
conversation-api-function run my_capi_fn
now call you lvn, you should hear an "hello world" mesage
open the following file my_capi_fn/index.js
for more info
run it part 2, make your life easier
you can now run every example you find in the examples
section without the need to configure the app again.
you can also run the app in an alternative way:
cd my_capi_fn
npm install
npm run
in this way you are gonna install the dependencies and run it without the need to use the global tool
further docs:
check the internal conversations api here: https://jurgob.github.io/conversation-service-docs/#/openapiui and the possible events here: https://jurgob.github.io/conversation-service-docs/#/custom
some tricks
This project use a logging library called bunyan
whitch is producing json logs.
if you install bunyan ( npm install -g bunyan
) then you can run:
conversation-api-function run my_capi_fn | bunyan
. you will now see a formatted log.
p.s. bunyan is producing standard json, so you can also use standard unix tools like jq to format the logs: tail -f vapi_hello_world.log | jq
how to write a function
when you start a new project, there's documentation in the example. If you are curious, take.a look here:
https://github.com/jurgob/conversation-api-function/blob/main/template/index.js
Examples
Once you have configured conversation-api-functions, you can run every project without configuring this tools again. Here are some examples you can run just coloning it and executing it with the following commans:
downloding / installing the repo:
git clone <GIT_REPO> <MY_DIR>
cd <MY_DIR>
nvm use
npm install
then run it with:
conversation-api-function run <MY_DIR>
e.g:
git clone https://github.com/jurgob/phone_inbound_asr my_capi_fn
cd my_capi_fn
nvm use
npm install
conversation-api-function run .
Examples
Automatic Speech Recognition
git_repo: https://github.com/jurgob/phone_inbound_asr
description: Call a number and trascribe your voice
UI react example
git_repo: https://github.com/jurgob/react_client_example
description: a very ugly react interface (genereated using react-create-app) for debuging ip calls. (aka calls from your browser). There's also simple login/subscribe mechanism.
NCCO talk action - hello world
git_repo: https://github.com/jurgob/capi-fn_ncco_hello_world
description: NCCO stands for Nexmo Call Control Object. Is an easy way to script your calls
NCCO websocket echo repeat
git_repo: https://github.com/dimitrisniras/websocket-echo-repeat
description: Simple Vonage Voice API demo that connects to a websocket endpoint and echoes audio back to caller
tags: ncco, phone-call, pstn, websocket-call, text-to-speech
NCCO input of DTMF and Speech
git_repo: https://github.com/JohnPeters7116/capi-fn_ncco_dtmf
description: Simple Vonage Voice API demo that takes dtmf input from customer and sends to customers event url
tags: ncco, phone-call, pstn, dtmf, speech, text-to-speech
IVR to get Date or Weather info via DTMF
git_repo: https://github.com/salvodicara/ivr_weather_or_date
description: An IVR example asking for user interaction to retrieve date or weather information
tags: ncco, phone-call, pstn, dtmf, speech, text-to-speech, ivr
Conversations API And facebook messages inbound
git_repo: https://github.com/bilalkabat/conversation-messages-inbound-example
description: Let your customer write a message to your facebook page and store them in conversation api
tags: conversataion-api, messages-api, facebook-messages, ip-messages,
Conversations API, facebook messages and SMS, both inbound and outbound
git_repo: https://github.com/andradaioanabogoi/conversation-messages-outbound-example
description: Store inbound facebook (and whatsapp, viber, sms message) in a conversation. Also respond to them via api (aka outbound messages)
tags: conversataion-api, messages-api, facebook-messages, ip-messages, whatsapp, facebook messenger, sms, viber
Hangup incomming phone calls but send back an SMS
git_repo: https://github.com/jurgob/capi-fn-hangup-call-and-send-messages
description: every phone called received to your LVN are gonna automatically hanged up, but the caller will receive
tags: conversataion-api, phone-call, pstn, custom-data, text-to-speech
Phone call authenication for IP calls using conversation custom data
git_repo: https://github.com/jurgob/capi-fn-pstn-call-authentication
description: someone is calling your nexmo number (LVN), he will be asked to say his/her name, The agent on the browser will se the incomming call and the name of the caller.
tags: conversataion-service, phone call, pstn, custom-data, text-to-speech
Record a leg or a conversation
git_repo (example 1, record by leg): https://github.com/jurgob/capi-fn_record_leg
git_repo (example 2, record by conversation): https://github.com/JohnPeters7116/capi-fn_record_conversation
description: the call in conversations follow the MCU model (https://bloggeek.me/webrtc-multiparty-video-alternatives/). In a nutshell, there's a mixer (in our case the conversations) where every leg (aka every call partecipant) are mixed togheter. If you want to record the call from a leg point of view, that's the example 1 is gonna show how to do it. if you are interested in record all the leg, then check the example 2. question: what 's the difference between recording a leg or a converstion?. Immagine leg a is earmuffing leg b. in the leg recording, you will not have the record of the leg b, while in the conversaion record you will have both the legs in the recoring
Conversations API And facebook messages with events using Vonage Client JS SDK
git_repo: https://github.com/dimitrisniras/inbound-message-chat
description: Let your customer write a message to your facebook page and store them in conversation api and see all the events that are coming through.
tags: conversataion-api, messages-api, facebook-messages, ip-messages
Inbound PSTN call using Vonage Client JS SDK
git_repo: https://github.com/dimitrisniras/inbound-call-example
description: Perform an inbound PSTN call, calling your nexmo number (LVN) and then connect to an
app
user, transmitting audio and using the JS SDK.tags: conversataion-service, phone call, pstn, client sdks
Outbound PSTN call using Vonage Client JS SDK
git_repo: https://github.com/dimitrisniras/outbound-call-example
description: Perform an outbound PSTN call to a number, using the JS SDK.
tags: conversataion-service, phone call, pstn, client sdks
Websocket audio phone
git_repo: https://github.com/jurgob/wsphone
description: receive a phone call and respond using your computer microphone via websocket.
Outbound phone call with NCCO
git_repo: https://github.com/jurgob/phone_outbound_call_ncco
description: call a phone number from your application (you could as instance do an automatic phone marketing campaign with this) .
Transcribe a conversation
git_repo (example 1, transcribe by leg): https://github.com/dimitrisniras/record-leg-transcription
git_repo (example 2, transcribe by conversation): https://github.com/dimitrisniras/record-conversation-transcription
description: Perform an inbound PSTN call, calling your nexmo number (LVN). The call (or a single leg) will be recorded and transcribed.
Use a Real Redis
by default the storage client is saving your data in-memory, so every time you restart you loose al your data. To use a real redis server instead, you just need to set the env var CONV_API_FUNC_REDIS_URL. See the example below for more details
use a docker redis for local deployment
be sure you have installed docker
to install redis in your local host, you just need to run:
docker run --name capifn-redis -p 6379:6379 -d redis
now open your config runnig conversation-api-function config
this is gonna open an editor with your configs. Add this line:
CONV_API_FUNC_REDIS_URL="redis://localhost:6379"
deploy in production
create deployment credentials
From the project directory, run the following command:
conversation-api-function deploy-new . -a API_KEY -s API_SECRET -l LVN_LIVE
this is gonna create a .env.prod
file with the credential to go live
remember, the LVN_LIVE you are using here should be a differnt one then the one you have used in prod. If you use the same, you risk to break your prod application.
deploy in heroku.
After you have create the .env.prod
file as described above, follow those steps:
- after you have created a deployment credentials, for the first thing you need to init your project on git:
git init
git add -A
git commit -m 'first commit'
be sure you have an heroku account: https://dashboard.heroku.com/apps
insatall the heroku cli with
npm install -g heroku
then you can create an heroku app :
heroku login
heroku apps:create my_capi_heroku_app
- now you can finally push the app live.
git push heroku main
if you look the app logs with heroku logs
you will see that's the app is failing. that's becouse you need to configure the env vars. An easy way is the following:
cat .env.prod | grep -v PRIVATE_KEY | xargs heroku config:set
# set private key
PRIVATE_KEY="`cat .env.prod | grep PRIVATE_KEY | cut -c 27-`"
echo -e $PRIVATE_KEY > private.key
heroku config:set CONV_API_FUNC_PRIVATE_KEY="$PRIVATE_KEY"
# set webhook url
heroku config:set CONV_API_FUNC_SERVER_URL="https://my_capi_heroku_app.herokuapp.com"
- now go to
https://my_capi_heroku_app.herokuapp.com/hello
to check is working