Data Dip - Web Service Connection

This article is focused on the requirements for a data dip to successfully work with your web service.

🚧

Web Service Required

In order for Xima CCaaS' IVR to perform a data dip, there must be a web service provided by your database, CRM, or other data service. Xima will reach out with your provided web service URL, a bearer token, and a JSON payload. Your web service must be able to authenticate our request and reply with a customized JSON payload.

Pro-services are available for assistance. Your database and web service cannot be managed by our traditional support channel.

Create and Note Necessary Integration Values Needed for Xima

To successfully integrate with Xima for data dipping, you'll need the following details to enter into our configuration menu. You may learn more about the configuration on the Xima side by reviewing this section of our documentation.

  • API URL - Xima CCaaS needs the URL endpoint where it should send it's data dip requests
  • Bearer/Auth API Token - For your data web service to remain secure, you should require a token to accompany all requests. Xima will need that token
  • Parameter Key(s) - When a request is submitted by Xima, it should include at least one Key name and value that should be used to find the applicable record in your data. As an example, the Xima request may come with a request parameter of Key=PhoneNum Value=8015551234. With that, your data could return the applicable record details for the contact with that phone number. Another example could be the caller's account number (as previously collected in their IVR flow). Xima will need to know the exact name of the "Key" we should use tied to the searching values
    • You may provide more than one key. The request will include all keys and their value as configured in Xima
      • NOTE: It will be up to your web service configuration to determine how to prioritize the keys requested

Requests from Xima

Here is an example request that Xima would send

POST

Header:

   Authorization: Bearer <your provided token>
{
    "account-num": "76541643",
    "phone-num": "8015551234"
}

In this example, our request included to request parameters: account-num and phone-num for the calling party.

Xima would rely on your webservice to:

  • Authenticate our request with the provided token
  • Identify if you want to prioritize your internal query by the provided account number or the phone number
    • *Only applicable if multiple request parameters are returned
  • Take the provided values and search for them using the key name. i.e. Search for a contact with a phone-num of 8015551234
  • Return the data you'd like Xima to access as outlined below

Expected Response from Your WebService to Xima

Note the keys, values, and display requests listed below are only examples, the format is required.

Xima is expecting the payload returned to be in JSON format.

{
"parameters": {
"": {
"value": "",
"displayToAgent": <true/false>,
"saveToDatabase": <true/false>
},
}
}

Here is a return example with multiple values returned:

{
    "parameters": {
        "account-manager": {
            "value": "Sam Whitecar(112)",
            "displayToAgent": true,
            "saveToDatabase": false
        },
        "account-num": {
            "value": "76541643",
            "displayToAgent": true,
            "saveToDatabase": true
        },
        "age": {
            "value": "28",
            "displayToAgent": true,
            "saveToDatabase": true
        },
        "email": {
            "value": "[email protected]",
            "displayToAgent": true,
            "saveToDatabase": true
        },
        "is-vip": {
            "value": "true",
            "displayToAgent": true,
            "saveToDatabase": true
        },
        "language": {
            "value": "English",
            "displayToAgent": false,
            "saveToDatabase": false
        },
        "name": {
            "value": "Tom Callahan",
            "displayToAgent": true,
            "saveToDatabase": true
        },
        "past-due-amount": {
            "value": "575.00",
            "displayToAgent": true,
            "saveToDatabase": false
        },
        "ssn-last-four": {
            "value": "3456",
            "displayToAgent": true,
            "saveToDatabase": false
        }
    }
}

Display to Agent and Save to Database Parameters

As you likely noticed above, two of the expected parameters for each returned value are "displayToAgent" and "saveToDatabase".

Though every value returned will be used as a Session Parameter in Xima, it is possible that they will never be logged or seen.

Hide Values from Agents and Do Not Log in Xima Database

To not log the values in Cradle to Grave, Reports, or to display to an agent, use:

"displayToAgent": false,

"saveToDatabase": false

Show Values to Agents During the Call

If you want the specific value to displayed to an agent, set:

"displayToAgent": true

This will result in each value configured as such displaying here:

Display the Value in Cradle to Grave and Reports

Values that should be added to Xima's historical database and visible in Cradle to Grave and Reports should use

"saveToDatabase": true

This will result in those associated values being displayed like so:

This will allow calls to be searched for or reported upon based on values obtained from the data dip.