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

$3

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

$3

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)




$3

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 -s -l `

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
cd
nvm use
npm install
`
then run it with:

` conversation-api-function run `


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 .

`

$3

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

git_repo (example 2, transcribe by conversation):

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

$3

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

$3

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.

$3


After you have create the .env.prod file as described above, follow those steps:

1) 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'

`

2) be sure you have an heroku account: https://dashboard.heroku.com/apps

3) insatall the heroku cli with `npm install -g heroku`

4) then you can create an heroku app :

`
heroku login
heroku apps:create my_capi_heroku_app
`

5) 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"
`

6) now go to https://my_capi_heroku_app.herokuapp.com/hello` to check is working