CallData Service and API

Save and Access Details from a Call After It Has Ended

Parloa's CallData Service and Retrieval API offer a structured way to save and retrieve essential information from a call, even after the Parloa segment of the call has concluded. This functionality is crucial when Parloa transfers a call back to the contact center, allowing the agent to access important data from the interaction, such as recognized intent or authentication status. While data can also be transmitted back to the customer via SIP headers (if the connection is via SIP), there are limitations on the number of characters that can be sent using this method; moreover, this option is unavailable for PSTN connections. The CallData API provides an effective alternative to bypass these limitations.

Understanding the Process

Step 1: Data Storage During a Call

During a call, a bot-builder or Solution Engineer configures a Parloa Service block to write data into the CallData database. This data is stored at Parloa for up to 30 days for later retrieval, essentially through a POST request to a Parloa-hosted resource.

Step 2: Data Retrieval Post-Call

After a call has ended on Parloa, the stored data can be retrieved via a simple GET request to a specified endpoint. This makes the data accessible to agents through most enterprise contact center systems that support API integrations.

Setting Up and Using CallData with Parloa

Service Configuration

If you are new to configuring Parloa services, please first visit the Technical Configuration page. The following steps are necessary to add the CallData Service under the "Services" tab in the Parloa frontend.

Branches

• success: Indicates the service call was successful, and the desired data was written to the database.

• else: Triggers for an unsuccessful request. For more information, see Services -> Branches.

Input

• callid (required): A unique identifier for the call.

• callerid (required): The phone number or unique user ID of the caller.

• Additional user-defined fields (optional): Fields defined by the user, which can be stringified JSON, simple strings, or other content fields.

  • Commonly used fields include content, conversationId, queue, intent, status.

Output

• None

Technical Configuration

URL: https://parloaservices.azurewebsites.net/api/CallData?clientId=<CLIENTID> Header: x-functions-key: <AUTHCODE>

You can obtain your AUTHCODE and CLIENTID from your Parloa representative.

Additional Service Details

Purpose/Function

The CallData service temporarily stores relevant call data in a Parloa-hosted database (for a maximum of 30 days) to allow for querying within the customer's system after the call has ended and left Parloa. This is useful for use in the agent frontend.

Target Users/Audience

• Customers who wish to store call data in a database for retrieval in the agent frontend, instead of passing it through SIP headers.

• Customers who need to store larger amounts of data from a call than SIP headers allow.

• Customers connecting to Parloa via PSTN.

Key Features

• Flexible data storage format (supports JSON with user-defined fields).

• Storage of larger data volumes (more than can be passed through SIP headers).

Sample CURL

Please refer to the following sections for examples.

Usage in Parloa

Sample Configuration Using Storage Variables

As noted, users can define additional fields for the CallData database. An example transaction might record the chosen hero and location during a call to the "SuperHero Hotline". Note that the CallData service does not return any output to the Parloa frontend; success is indicated by the triggering of the success branch, confirming the data has been stored.

Post-Call Data Retrieval

To fetch data, you'll need two required parameters: callerID and callId.

• The callerid parameter from the POST request is equivalent to the caller parameter in the GET request. Ensure these identifiers are available in your client system for data retrieval, even if SIP header transfer is not possible.

• Data retrieval requires the same CLIENTID and AUTHCODE used for writing to the database, ensuring data security.

GET Request Parameters

The request can include additional optional parameters such as format, timeLimit, lang, and countryCode. These parameters allow you to narrow down results or expand your search. More details on these parameters are available in the next section.

You can find more information on these parameters in the table in the next section.

Below is an illustrative example of how a request and its corresponding response look:

The GET request for CallData shown via the REST-Client plugin in VSCode (for visual clarity)

Testing the API

Both the writing and the retrieval of data can be tested outside of the Parloa frontend for debugging and troubleshooting purposes.

POSTing Sample Data

To test the API endpoint, you can POST sample data directly. An example CURL could look like the following:

curl --location 'https://parloaservices.azurewebsites.net/api/CallData?code=<AUTHCODE>&clientId=<CLIENTID>' \
--header 'Content-Type: application/json' \
--data '{
    "input": {
        "callerid": "[phone]",
        "callid": "145644644ff",
        "content": "Postman tests"
    }
}'

A more complex request might look like this:

Sample Request Body

{
  "input": {
    "callerid": "[phone]",
    "callid": "12345",
    "content": "The user spoke to the bot",
    "destination": "someServiceQueue",
    "intent": "doSomeCoolThing",
    "sessionid": "d69130c6fe02bf8110a25d191c5ec6de"
  }
}

Sample Response: Success

{
    "choice": "success",
    "output": {}
}

The most common cause of failure is missing (or misnaming) one of the required input fields:

Sample Request Body (Incomplete)

{
  "input": {
    "callerid": "[phone]",
    "content": "The user spoke to the bot",
    "whichCall": "12345",
    "destination": "someServiceQueue",
    "intent": "doSomeCoolThing",
    "sessionid": "d69130c6fe02bf8110a25d191c5ec6de"
  }
}

Sample Reponse: Failed

{
  "choice": "fail",
  "output": {
    "error": "Required Attributes: callid, callerid"
  }
}

POST Request Parameters

Paramter	Type	Mandatory	Description	Example
callerid	String	Yes	The user's Caller ID can appear as either an international number (starting with +49...) or a local number (starting with 0...).	[phone]
callid	String	Yes	The unique ID of the call that needs to be returned.	12345
content	String	No, but recommended	The content you want to collect from the user.	The user spoke to the bot
conversationid	String	No but recommended	Internal Parloa ID. Useful for debugging.	d69130c6fe02bf8110a25d191c5ec6de
countrycode	String	No	Specify the country code to recognize local numbers.	+41 || any other country code Country Codes
timestamp	String	No	-

GETing Sample Data

To check whether your sample data has written to the DB, you can GET the sample data using the following CURL command:

curl --location --request GET 'https://parloaservices.azurewebsites.net/api/CallData?code=<AUTHCODE>&clientId=<CLIENTID>&caller=%2B111111111&callid=145644644ff' 

Note that for the GET request, parameters are passed in directly in the URL of the request.

In the case of conflicting entries, which are possible if the callid is a simplified custom string, the service will return the most recent one. Additional parameters can be used in the CURL to adjust the results, e.g. returning in html format.

Sample CURL: JSON

curl --location 'https://parloaservices.azurewebsites.net/api/CallData?code=<AUTHCODE>&clientId=<CLIENTID>&caller=%2B111111111&callid=145644644ff'

Response: JSON

{
    "caller": "[phone]",
    "callid": "145644644ff",
    "timestamp": "2024-02-27T12:16:23.926Z",
    "content": "Postman tests"
}

Sample CURL: html

curl --location 'https://parloaservices.azurewebsites.net/api/CallData?code=<AUTHCODE>&clientId=<CLIENTID>&caller=%2B111111111&callid=145644644ff&format=html'

Response: html

<!DOCTYPE html>
<html lang='de'>

<head>
    <meta charset='utf-8'>
    <title>Botgespräch vom 27.02.2024 13:16:23</title>
</head>

<body>
    <!--h1>Botgespräch vom 27.02.2024 13:16:23</h1-->
    <table>
        <tr>
            <th>Telefonnummer</th>
            <td>[phone]</td>
        </tr>
        <tr>
            <th>Datum</th>
            <td>27.02.2024 13:16:23</td>
        </tr>
        <tr>
            <th>Inhalt</th>
            <td>Postman tests</td>
        </tr>
        <tr>
            <th>Anruf-ID</th>
            <td>145644644ff</td>
        </tr>
        <tr>
            <th>Parloa-ID</th>
            <td>undefined</td>
        </tr>
    </table>
</body>

</html>

The generalized html field names (returned for all entries, regardless of custom fields) are German by default, but can be returned in English using the lang parameter.

Sample CURL: English field names

curl --location 'https://parloaservices.azurewebsites.net/api/CallData?code=<AUTHCODE>&clientId=<CLIENTID>&caller=%2B111111111&callid=145644644ff&lang=en&format=html'

Sample Response: English field names

<!DOCTYPE html>
<html lang='en'>

<head>
    <meta charset='utf-8'>
    <title>Bot conversation from 2024-02-27T12:16:23.926Z</title>
</head>

<body>
    <!--h1>Bot conversation from 2024-02-27T12:16:23.926Z</h1-->
    <table>
        <tr>
            <th>Phone number</th>
            <td>[phone]</td>
        </tr>
        <tr>
            <th>Date</th>
            <td>2024-02-27T12:16:23.926Z</td>
        </tr>
        <tr>
            <th>Content</th>
            <td>Postman tests</td>
        </tr>
        <tr>
            <th>Call ID</th>
            <td>145644644ff</td>
        </tr>
        <tr>
            <th>Parloa-ID</th>
            <td>undefined</td>
        </tr>
    </table>
</body>

</html>

There are 2 common ways that this request can fail; most often, either there is a misconfiguration in the GET request, or the record was created outside the default time range of the service. To avoid misconfigurations (incorrect phone number, callerid instead of caller, etc.), check the GET request carefully. If the time range might be the issue, it can be adjusted using the timeLimit parameter in the request.

Sample CURL (misconfigured)

curl --location 'https://parloaservices.azurewebsites.net/api/CallData?code=<AUTHCODE>&clientId=<CLIENTID>&caller=%2B111111111&callid=145644644ff&lang=en'

Sample Reponse: Failed

{
    "error": "no result found"
}

The service does not differentiate error types in its response and will simply say "no result found".

GET Request Parameters

Parameter	Type	Mandatory	Description	Example
caller	String	yes	Caller ID (phone number) of the user. Either international format (+49...), or local format (0...). Be sure to encode the + properly for the URI component (becomes %2B)	%2B4917670919361 (encoded [phone])
callid	String	yes	unique identifier of the call	CAd69130c6fe02bf8110a25d191c5ec6de
timeLimit	Integer	no	maxiumum age of the data to be returned in seconds	Default is 60 seconds. Adjust this to a higher number if calls are queued for a longer time before the data is being requested.
format	String	no	Return data in either json (default), xml , html or text	json
countryCode	String	no	Specify the country code to recognize local numbers	+41 || any other country code Country Codes
lang	String	no	two-letter language code to determine the language of the returned field names (relevant for html formatted response)	de || en (additional languages not yet supported)