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,

1. 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.

2. 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://localhost:5000 for this tutorial.

3. 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.

4. 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

• node
• git
• a code editor of your choice. A popular choice is VSCode.

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.

1. $ npm install -g degit
2. $ degit goto-opensource/screen-pop-demo#template screen-pop-demo
3. $ cd screen-pop-demo
4. $ 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.

1. Run your application with $ npm start.
2. In your browser, navigate to http://localhost: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.

3. 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.
4. 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.