This Amazon Comprehend reference connection allows transcripts from your Vonage Voice API applications and text messages from your Vonage Messages API applications to be sentiment analyzed by AWS Comprehend. Multiple languages are supported.
In order to get started, you need to have an AWS account, retrieve your AWS key and secret, and take note of your AWS services default region.
To find your Access Key and Secret Access Key:
- Log in to your AWS Management Console.
- Click on your user name at the top right of the page.
- Click on the Security Credentials link from the drop-down menu.
- Find the Access Credentials section, and copy the latest Access Key ID.
- Click on the Show link in the same row, and copy the Secret Access Key.
Your Vonage API application uses HTTP POST to the reference connection address with the follwing requirements:
- The text to be sentiment analyzed is sent as a "text" element in a JSON formatted payload in the HTTP POST body, not as a query parameter! Thus your application must set the header "Content-Type:application/json",
- Must include at least the following query parameters:
- webhook_url (e.g. https://my_server.my_company.com:32000/sentiment_score) where the sentiment scores will be posted by the reference connection to your Vonage API application,
- language (e.g. en), which defines the transcription language as listed here,
- Your application may send/use any additional query parameter names and values for your application logic needs, except it may not use/send the following reserved query parameter names:
- sentiment,
- text,
- service.
A few seconds later, the reference connection posts back to your Vonage API application webhook_url a JSON formatted payload (in the body of an HTTP POST):
- the "sentiment", i.e. sentiment results,
- the "text",
- the name of the "service", which is "AWS Comprehend" in this case,
- and all other values sent as query parameters of the original request to the reference connection, e.g. "webhook_url", "language", and any additional query parameters that have been sent in the original HTTP POST.
You may select one of the following 4 types of deployments.
Copy the .env.example
file over to a new file called .env
:
cp .env.example .env
Edit .env
file,
set the 3 first parameters with their respective values retrieved from your AWS account,
set the PORT
value (e.g. 5000) where sentiment analysis requests will be received.
The PORT
value needs to be the same as specified in Dockerfile
and docker-compose.yml
files.
Launch the Comprehend reference connection as a docker container instance:
docker-compose up
Your docker container's public hostname and port will be used by your Vonage API application as the address to where to submit the transcription request https://<docker_host_name>:<proxy_port>/sentiment
, e.g. https://myserver.mydomain.com:40000/sentiment
To run your own instance locally you'll need an up-to-date version of Python 3.8 (we tested with version 3.8.5).
Copy the .env.example
file over to a new file called .env
:
cp .env.example .env
Edit .env
file,
set the 3 first parameters with their respective values retrieved from your AWS account,
set the PORT
value where sentiment analysis requests will be received.
Install dependencies once:
pip install --upgrade -r requirements.txt
Launch the reference connection service:
python server.py
Your server's public hostname and port will be used by your Vonage API application as the address to where to submit the transcription request https://<serverhostname>:<port>/sentiment
, e.g. https://abcdef123456.ngrok.io/sentiment
Install git.
Install Heroku command line and login to your Heroku account.
Download this sample application code to a local folder, then go to that folder.
If you do not yet have a local git repository, create one:
git init
git add .
git commit -am "initial"
Deploy this reference connection application to Heroku from the command line using the Heroku CLI:
heroku create myappname
On your Heroku dashboard where your reference connection application page is shown, click on Settings
button,
add the following Config Vars
and set them with their respective values retrieved from your AWS account:
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_DEFAULT_REGION
git push heroku master
On your Heroku dashboard where your reference connection application page is shown, click on Open App
button, that URL will be the one to be used by your Vonage API or Vonage Messages API application to submit sentiment analysis requests, e.g. https://myappname.herokuapp.com/sentiment
.
Click the 'Deploy to Heroku' button at the top of this page, and follow the instructions to enter your Heroku application name and the 3 AWS parameter respective values retrieved from your AWS account.
Once deployed, on the Heroku dashboard where your reference connection application page is shown, click on Open App
button, that URL followed by /sentiment
will be the one to be used by your Vonage API application as where to submit the HTTP POST, e.g. https://myappname.herokuapp.com/sentiment
.
Quickly test your reference connection as follows:
- Have your sample text to be sentiment analyzed
- Have your deployed reference connection server URL, e.g. https://myapp.herokuapp.com/sentiment
- Have the webhook call back URL to your client application, e.g. https://xxxx.ngrok.io/transcript
Test the transcription using this curl command:
curl -X POST "https://myapp.herokuapp.com/sentiment?webhook_url=https://xxxx.ngrok.io/sentiment_score&entity=customer&id=abcd&language_code=en" -d '{"text": "You provide such a fantastic service! I am a very happy customer!", "foo": "bar"}'
A JSON formatted response will be posted to the webhook_url URL, including the sentiment score, all custom query parameters, and sent JSON payload parameters needed by your application logic from the original POST request.