on - edited on by
AmyBoss
This is the second article in a series teaching you everything you need to set up, support, and succeed with the Invoca for Five9 integration.
- Sending Invoca data to Five9 (PreSense) (You are here)
As we discussed in the Invoca for Five9 integration overview, you can connect your Invoca and Five9 accounts to accomplish three different use cases:
- Intelligent Routing: Use pre-call digital intent data to route every phone call in the ideal way, by the ideal agent.
- Real-time context: Share Invoca pre-call data with live agents to provide details about what led the customer to call, arming your agents to exceed customer expectations.
- Share agent, call, and disposition information from Five9 back to Invoca
This article includes instructions to help set up the first two, as part of our solution.
Developer expertise required:
Unlike a lot of other Invoca integrations which can be set up with a simple no-code process, sending Invoca data to Five9 requires some developer resources. If you're not sure if your team has this capability or you want help estimating the workload required, talk to your Invoca Customer Success Manager and set up a consultation with our friendly Technical Support team.
Before we begin: Which Invoca and Five9 account packages do I need to send Invoca pre-call data to Five9?
To install this integration, you'll need an account package that gives you access to the following features:
- In Invoca, the Integrations library and the Calls In Progress API
- In Five9, your IVR Scripts from your Virtual Call Center (VCC) admin
If you don't have access to these features, get in touch with your Invoca Customer Success Manager, email success@invoca.com, or reach out to your Five9 Account Executive to discuss adding them to your account.
Step 1: Build your Invoca Calls In Progress API Endpoint
Required for use cases: Intelligent routing & real-time context
Developer resources required: Yes
To send Invoca pre-call data, Five9 will ping the Invoca Calls In Progress API — but you'll need to build an API endpoint to connect to it. Our detailed Calls In Progress API documentation in the Invoca developer’s portal has a full list of the API's parameters and fields, along with the endpoint URL and required values. It also includes a thorough set of sample API calls and response codes for your developer to consult.
Is your Calls In Progress API enabled?
As noted above, not every Invoca account has access to the Calls In Progress API out of the box. If you don't have it already, contact your Customer Success Manager, Account Executive, or success@invoca.com to request access.
Additionally there are three required values specific to your Invoca account that we'll need to complete your Calls In Progress API endpoint. Here's how to find them:
- Organization Type
Your Invoca organization type is either Network or Advertiser.
To figure out your organization type, log in to your Invoca account and click the Invoca logo in the upper left to confirm you are viewing the top level for your user.
After clicking the logo, you will see a green box with the text “Network” if your organization type is Network. This is the top-admin-level in the Invoca account hierarchy. Alternatively, if you do not see the word Network, you will see a light blue box and text that reads Profile, Advertiser, or it may be a custom name other than Network. In this case, your Organization Type is Advertiser. See to learn more.
- Organization ID
While you are at the dashboard page of the organization-level with which you are integrating, look in the URL address bar. The first numeric value you see is your organization ID. See our article for more details.
- An Invoca API OAuth token
This is a custom authentication token unique to this integration. Follow our guide and enter Five9 as the token description, then click Save. This unique token you create in this step will only be shown to you once, so copy your new token immediately and save it somewhere secure. For security, it is not viewable or accessible again and Invoca cannot retrieve it for you. When you're ready, click close.
Now that you have gathered these three pieces of information, you can construct the URL that will be entered in the Five9 Query Module.
From the Calls In Progress API documentation, scroll down to the third example, "get calls in progress by phone numbers":
https://invoca.net/api/latest/calls_in_progress/current_calls.json
oauth_token=YOUR_OAUTH_TOKEN
id=YOUR_ORG_ID
organization_type=YOUR_ORG_TYPE
calling_phone_number=
destination_phone_number=
Copy and paste the URL in a text editor and replace the text in red with the values you obtained from your account. You will enter a Five9 substitution token for the calling phone number and the destination phone number in a later step, so you can skip those for now.
Step 2: Configure your Five9 IVR Script
Required for use cases: Intelligent routing & real-time context
Developer resources required: Yes
Your Five9 account routes the phone calls you receive based on a feature called IVR Scripts. In this step, we'll be adding a new module to your IVR Script to include a query to ping the Calls In Progress API endpoint URL you just created in step 1.
- Log in to your Five9 Virtual Call Center Admin. Click IVR Scripts, then open the IVR Script you want to use with Invoca data. If you want to set up more than one IVR script, just repeat these instructions.
- Find the Query module, then drag it into your IVR Script at the point in your call flow where you want Five9 to ping Invoca for data. This should be early in the call flow. Once you have it in place, double click the icon.
- Fill in your Query Module Properties with the following:
- Module Name: Ping Invoca for Pre-Call Data
- Base URL path: https://invoca.net/api/latest/calls_in_progress/current_calls.json
- Method: GET
- Select the Request tab to add the other parameters you obtained from your Invoca account. Click the Add button near the bottom to add parameters to the request. First you will replace param with the correct field name, then you’ll add the value from the text editor. Be sure to copy the parameter name from the text editor to capture it exactly. The name is case and punctuation sensitive.
The calling_phone_number and destination_phone_number values will be dynamic. Choose call.ANI and call.DNIS from the variable drop down list.
- Select the Responses tab. This is where you can write a function to take the pre-call data fields from Invoca and map them to variables in Five9. This is extremely customizable and may require a deeper working knowledge of code and Five9. You may benefit from enlisting the help of the person that manages the technical aspects of your IVR Scripts or, if you do not have anyone internally at your company, contact your Five9 Account Director.
In this section we can map any field from the Invoca Calls In Progress API to a Five9 variable, but first, start by mapping the Invoca Transaction ID for the call to the Five9 buffer variable for more precise matching of call records between Invoca and Five9.
Which Five9 variable should you connect to your Invoca Transaction ID?
We strongly recommend you map the Invoca Transaction ID to a Five9 Contact or Call variable for more precise matching of call records between Invoca and Five9 — especially important if you plan to follow the next part of our Invoca for Five9 guide to . You might wish to use a different variable than the one we use in this example, such as the call variable or call attached variable, based on your IVR Script. If you need technical help from Five9 to determine the best variable to use, get in touch with your Account Director to scope a project.
The following is an extremely simplified example of the process you can take to map Invoca data to your Five9 variables:
- In the Responses tab, click the “Add” button. For 200 status codes, you will have Five9 execute a Function. In this example, we use the __BUFFER__ variable to temporarily store the Invoca value.
- Next, we define a “New” function and name it parseQueryResponse.
- Now click “Add” to add a function argument. Enter “data”.
- Next, write some JavaScript to look for a specific key value for the first call Invoca returns when Five9 pings the Invoca endpoint to get pre-call data. In this case, the code is looking for the transaction ID value.
- Confirm your work by clicking on Test to do a very rudimentary test. This will make sure your JavaScript is set up correctly and runs without errors. In the example listed in these screenshots, we've sent a simple Invoca API response and entered it in the test box. The JavaScript function correctly returns123, as expected, so we can assume our code is in good working order.
- Now that you've finished mapping one Invoca pre-call field to a Five9 variable, you can repeat the previous step for each Invoca data point you want to pass along. Each field you include can be used in the next steps of this guide to help route your phone calls to the best qualified agents or pass along data about your customer's intent for your agents to view on their call.
- In the Responses tab, click the “Add” button. For 200 status codes, you will have Five9 execute a Function. In this example, we use the __BUFFER__ variable to temporarily store the Invoca value.
You have free reign to map more data from the Invoca API response and store or expose that data in Five9 in different ways! It is best to strategize and consult with the Admin or technical resource on your side that typically configures your Five9 IVR Scripts.
If your technical resource wants to get acquainted with the format of the Invoca JSON response to help them build a custom JavaScript function, they can use Postman to ping the Invoca system. If they exclude the calling phone number and destination phone number from the request URL, the API will return information for all calls in progress. Some noteworthy points:
- For a given call, only parameters that have a value will be included in the response.
- Only data captured at call start will be returned. Data added to Invoca post-call, such as Signals that rely on transcript data and call outcomes, will not be available in the Calls In Progress API response.
In addition to testing in Postman, you can also run a Call Details report in Invoca to get an idea about the data available to pass to Five9. Select all the Marketing Data fields and run your report to get a feel for the data you have Invoca set to capture.
Step 3: Route Based on Invoca Data
Required for use cases: Intelligent routing
Developer resources required: No
Let’s walk through an example of how you might route the call based on the Invoca data point we just mapped.
- Return to the IVR Script you edited above in step 2. After the Query module we created above, add a new If/Else module.
- In our example criteria, we are referencing the __BUFFER__ variable that we just mapped our Invoca transaction ID to. In this very basic example, we are routing to one skill if the __BUFFER__ variable does not have a transaction ID present and another skill if it does.
- Building on that, this use of Invoca precall data gives you the ability to use Invoca data to priority-route based on an array of data points, such as the page someone is on when they call or if they have placed products in their shopping cart. Of course, your options here are virtually endless and you can customize this based on your data and what you have mapped!
Step 4: Map Invoca Data to Five9 Variables
Required for use cases: Real-time context
Developer resources required: No
The final piece to cover in this guide is an example of how to get the Invoca data mapped and available to view in the Five9 Contact record. This makes the information available to the agent answering the call and provides that extra bit of context about the caller’s intent.
- If you don't already have variables in your Five9 account that correspond to the Invoca data you'd like to send, go to the Contact record that you will map the Invoca data to and create those variables. In this example, we will use the Contact.call_record_id variable.
You will be adding three modules to your IVR Script. These should be placed after the Query module step.
- The first is a lookup contact module and defines how Five9 will find the correct Contact record. In this example, we are finding the Contact record based on the phone number stored in the number1 field of the Contact record and the ANI of the caller.
- The second is a SetVariable module which defines the actual data mapping. In this example we are choosing the contact.call_record_id call variable and setting the value to what was captured and mapped to the __BUFFER__ variable back in my Query module step.
- The third is the ContactUpdate module and triggers updating the contact record with the new information.
That's it! Your sample mapping project is complete — on to the real data. Repeat this step for each Invoca pre-call data field you want to deliver to your contact center agents in Five9. When you're finished, click save.The changes to your IVR Script will take effect immediately and you’ll be able to receive and use Invoca data in Five9.
