Call events screen pop tutorial
Screen pop presents call information, such as links to open support tickets, customer tier from a CRM, or upcoming appointments to your users. Use screen pop when your agents would benefit from extra information about the caller.
GoTo Connect offers calling capabilities and APIs to enable features like screen pop. In this tutorial we will setup an account, create our OAuth credentials, and setup a demo app which will utilize APIs in GoTo Connect to react to incoming calls.
OAuth Client Creation
Your OAuth client will be used to create tokens, which provide authorization to your API calls.
To create your first client,
-
Navigate to the OAuth Client Management Portal. You might have to login again. If you do, use the same account you created above for the trial setup. Note, the account used to create OAuth clients is the only account which can manage the clients. This demo app will use the implicit grant flow for authorization. Interactions with this flow have been created for you in the template.
-
Click create client to begin filling out your client information. Name your client something meaningful. For this tutorial we named our client "screen-pop-demo" to match the application we are creating it for. The redirect URI must equal
http://127.0.0.1:5000
for this tutorial. -
Check the GoToConnect scopes for your client. We will be interacting with the GoToConnect APIs for this tutorial and only require the following scope to be selected,
users.v1.lines.read
. Scopes are requests for access to user information and actions. When a user logs into their GoTo Connect account through your app, they will be prompted to accept or deny your application's request to act on their behalf. -
Your client ID and client secret will be displayed. For this tutorial you will only need the client id. Remember, you can re-view your client id in the OAuth Client Management Portal.
Development Setup
For this tutorial you will need
1. Project Setup
This tutorial will use a pre-setup template. We have created this template as boiler code for you to use in screen pop. The degit
tool provides a simple way to clone this template.
$ npm install -g degit
$ degit goto-opensource/screen-pop-demo#template screen-pop-demo
$ cd screen-pop-demo
$ npm install
All changes made during this tutorial will be done in the file index.html
.
2. Add Client Info
To obtain a token, add your client id to your application. Paste your client id as demonstrated below.
oauth: new OAuth({
clientId: 'your_client_id',
})
3. Get Line Info
Get the line information for the line you are using. The phone number provisioned on your account is associated to this line. We are getting the first line returned from the list of lines, but if you are using an existing account you may have multiple lines returned and need to select the line associated with the number you want to call.
getLineInfo: async function(){
const response = await fetch("https://api.goto.com/users/v1/lines", {
headers: { "Authorization": `Bearer ${this.token}` }
})
return response.json();
}
4. Create Realtime Session
Create a session for realtime data. A session
gives us a websocket to receive realtime data.
createSession: async function(){
const response = await fetch("https://realtime.jive.com/v2/session", {
headers: { "Authorization": `Bearer ${this.token}` },
method: "POST"
})
return response.json();
}
Response Example:
{
"self": "https://realtime.jive.com/v2/session/{your_session_id}",
"ws": "wss://realtime.jive.com/ws/v2/{your_session_id}",
"subscriptions": "https://realtime.jive.com/v2/session/{your_session_id}/subscriptions"
}
Note how the response body includes fields ws
and subscriptions
. ws
is the websocket url we will connect to and subscriptions
is the url to the sessions subscriptions. We will use the subscriptions
url when creating subscriptions which dictate what events we will see on the websocket.
5. Create Subscription
Create a subscription to indicate what events to receive on the websocket. For this tutorial, we want to know about incoming calls to our line. When we requested the line information we received a list of lines. These line objects include fields id
and organization
. We use these fields in the entity
field of the subscription request body. Inside entity
, id
will be your line id, and account
will be your organization id. The root attribute id
will be an id of your choice. It's recommended to use a unique id which also expresses what the subscription is for. In this tutorial we us mylinesubscription
, but you might also consider using the line id, the organization id, maybe even a base64 encoding of the entity itself, just something useful to you.
subscribe: async function(){
const firstLine = this.lines.items[0];
// For this tutorial we will use the first line returned from potentially a larger list of lines.
const account = firstLine.organization.id;
const data = JSON.stringify([{
"id": "mylinesubscription",
"type": "dialog",
"entity": {
"account": account,
"type": "line.v2",
"id": firstLine.id
},
}])
const response = await fetch(this.session.subscriptions, {
headers: {
"Authorization": `Bearer ${this.token}`,
"Content-Type": "application/json"
},
method: "POST",
body: data
})
return response.json();
}
6. Listen for events
After setting up a subscription we can listen on the websocket from our session for incoming events. For this demo we only care about the initial call start event which has the announce
type. From this event we pass the caller informations number to our lookup function.
listen: async function(){
this.socket = new WebSocket(this.session.ws)
this.socket.onmessage = (event) => {
const data = JSON.parse(event.data)
console.log(data)
if (data.type == "announce") {
const meta = this.lookup(data.data.caller.number)
this.events.unshift(meta)
}
else {
console.log("No handler")
}
}
}
The lookup
function will look up the caller number in your own meta data. This would normally be a call to an API or some other storage. For this tutorial we have filled out this method and return static data. A real application might use the data to look up the caller in a CRM system, lookup local call history and recognize back to back calls for urgency, show links to existing support tickets, or even notes from a previous call.
lookup: function(number) {
return {
name: 'John Doe',
lastCall: '1 Hour ago',
notes: 'VIP, loyal customer'
}
}
Demo
All the parts have been setup, so the demonstration can start.
- Run your application with
$ npm start
. - In your browser, navigate to
http://127.0.0.1:5000
. You will be prompted to accept the scopes the app is requesting before being redirected back to your application. If you are prompted to login, use the same account you used when setting up the trial.
- To see events sent to your app, your user must be online on GoTo Connect and ready to receive calls. Provisioned hardware phones or using the GoTo Connect Mobile app will also work.
- Test your app by calling this user at the provisioned number from the start, using another phone. You should see an event shown on the display as shown below:
This completes the screen pop tutorial. You have learned how to authenticate, get a users line information, subscribe and listen for events on this line, and react to an event when it occurs.
Final Project link
The completed demo for this tutorial can be found at goto-opensource/screen-pop-demo
Trial request
If you do not have a test PBX, please request access by contacting sales here. An SMS limit may apply.
- How do I get started?
- How to create a developer account
- How to create an OAuth client
- How to obtain an OAuth access token
- How to obtain an OAuth access token (in Node.js)
- How to Obtain and Use Refresh Tokens
- How to use GoToConnect API to fetch account users and lines
- How to create, update and delete account users via Admin API
- Call events screen pop tutorial
- Send SMS tutorial
- How to use Voice Admin APIs
- How to create a channel and receiving notifications from GoTo services
- How to subscribe to and get call events
- Fetching Call Events Reports
- GoToWebinar webhooks
- How to use GoToWebinar webhooks
- Introduction
- Java SDK
- .NET SDK
- Direct login migration
- How to use Postman API collections
- How much do the GoTo APIs cost?
- How do I get support for the APIs?
- Rate Limiting