Import API

Available in 9.3 and above

Overview

The Import API allows ingesting 3rd party or Verba data into the system.

1 Overview
2 Prerequisites
3 General guidelines
- 3.1 HTTP GET, POST
- 3.2 URL encoding
- 3.3 Response type
- 3.4 Security
4 Authentication
- 4.1 Request
  - 4.1.1 Authentication request
- 4.2 Response
  - 4.2.1 Authentication response
5 Import request
- 5.1 Request
  - 5.1.1 Authentication request
- 5.2 Response
  - 5.2.1 Authentication response
  - 5.2.2 HTTP/1.1 201 OK
6 XML description
- - 6.1.1 Call example XML
  - 6.1.2 SMS example XML
  - 6.1.3 File share example XML
  - 6.1.4 Instant message example XML
  - 6.1.5 Instant message example im file
- 6.2 Conference example XML
- 6.3 Trader voice example XML
  - 6.3.1 CDR record
  - 6.3.2 Media record
- 6.4 Custom metadata example XML
7 Load Balancing

The primary goal of the interface is to enable ingesting records to the system using JSON or XML formatted metadata and the corresponding media file(s). The interface provides access to the Verba Import Service through a REST API. This API supports both the standard and the advanced (trader voice specific) database schemas: Data models.

The API can be reached at http(s)://media-repository-address:port/restapi/v093/import/<action>

Prerequisites

In order to utilize the API, the following configuration is needed in the Web Application: Prerequisite configuration for Import API

General guidelines

HTTP GET, POST

The functions of the API are available as simple HTTP GET and POST requests. For implementations, where HTTP POST is not available, you can use the HTTP GET method. The maximum length of the HTTP GET request is usually maximized either by the client or the server. The client should assume that the maximum length of a GET request is 4000 characters, although, some implementations may support longer URLs too.

URL encoding

All HTTP requests have to be URL encoded and all spaces and special characters have to be escaped and substituted with its URL encoded equivalent. For further information, see http://www.w3schools.com/TAGS/ref_urlencode.asp.

Response type

The API provides json formatted responses.

Security

The API provides the following mechanism to ensure that the communications between the external application and the recording system are secure:

- Authentication
- Token based sessions
- Option to limit the access to the API from preset network addresses
- Option to use SSL/HTTPS

Authentication

The Import API requires a valid session token to process import requests. The authentication expects an HTTP GET request to the auth action. The token generated after a successful authentication is valid for one hour after the last use.

If the authentication fails, the system will return a 500 HTTP Status Response, and a description of the problem encountered during the authentication

Request

Authentication request

GET /restapi/v093/import/auth
Host: hostname:port
apikey: D53B03F9-3A7D-4645-97E9-618FD38819A4
password: D87869A979DB0078521D5872944E966E
username: user
cache-control: no-cache

Request headers

Field	Description

Field	Description
apikey	The generated, unique GUID for the API key
username	The username of the Verba user used to authenticate. This user must have the Conversation Import role. (optional)
password	The password for the Verba user (optional) (Before 9.6 use the MD5 hash of the password here.)

Response

Authentication response

HTTP/1.1 200 OK
Date: Thu, 09 Jan 2019 10:42:57 GMT
Content-Type: application/json
Content-Length: 70

Response codes

Response Code	Description

Response Code	Description
200	Successful authentication
500	Error during authentication

Response headers

Field	Description

Field

Description

Date

The date and time of the request in EEE, DD MMM YYYY HH:MM:SS format

Type: String

Content-Type

The type of the HTTP content: application/json
Type: String

Content-Length

The length of the HTTP content
Type: Number

Response body

{
    "status" : "ok",
    "token" : "94557faa725211e980f300155d01545a"
}

{
    "status" : "error",
    "error_message" : "Internal Server Error. An unexpected error has occured while generating token: Bad token request. Provided userName and/or password is incorrect. (Note: password must be md5 hashed!)"
}

Field	Description

Field	Description
status	The result of the authentication, possible values are ok, error Type: String
token	The token for the authenticated session Only sent if status is ok Type: String
error_message	Description of the error encountered Only sent if status is error Type: String

Import request

Request

The type of the request should be multipart, the boundary, media and the CDR file are mandatory unless noted otherwise. After a successful request, the following reply will be sent:

Authentication request

POST /restapi/v093/import/conversation HTTP/1.1
Host: 10.110.78.29:12345
apikey: D29AC60E-5CC3-48AE-9787-29E60EC1892A
token: 9471f4019e5611e980f800155d001c23
cache-control: no-cache
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Content-Disposition: form-data; name=""; filename="C:\GenericImport\CDR.xml
Content-Disposition: form-data; name=""; filename="C:\GenericImport\teszt.wav

------WebKitFormBoundary7MA4YWxkTrZu0gW--

Request headers

Field	Description

Field	Description
apikey	The generated, unique GUID for the API key
token	The token received in the authentication request body

Response

Authentication response

HTTP/1.1 200 OK
Date: Thu, 09 Jan 2019 10:42:57 GMT
Content-Type: application/json
Content-Length: 47

Response codes

Response Code	Description

Response Code	Description
200	Successful import
500	Error during import

HTTP/1.1 201 OK

JavaScript Object Notation: application/json     
Object
	Member Key: status 
		String value: ok 
	Key: status         
	Member Key: reason 
		String value: imported
	Key: token

Response headers

Field	Description

Field

Description

Date

The date and time of the request in EEE, DD MMM YYYY HH:MM:SS format

Type: String

Content-Type

The type of the HTTP content: application/json
Type: String

Content-Length

The length of the HTTP content
Type: Number

Response body

{
    "status" : "ok",
    "reason": "imported"
}

{
    "status": "error",
    "error_message": " Bad request. Failed to process CDR: String to parse is too short: , current position: 0"
}

Field	Description

Field	Description
status	The result of the authentication, possible values are ok, error Type: String
reason	Verification if the import is sucessful. Only sent if status is ok. Type: String
error_message	Description of the error encountered Only sent if status is error Type: String

XML description

The description of the Verba XML file can be found at Metadata XML fields. The id of the call is optional, if no ID is provided, the system will generate one.

Call example XML

<?xml version="1.0" encoding="utf-8"?>
<verbacdr state="1">    <!-- Finished Call State -->
<id>ff83f076-9e4e-11e9-80f8-00155d001c23</id>   
<recorded_cid>testuser@verbalabs.com</recorded_cid>
<start_time>2019.06.21 14:40:15.618</start_time>
<end_time>2019.06.21 14:40:57.768</end_time>
<destination_caller_id>kakas@verbalabs.com</destination_caller_id>
<source_caller_id>6010</source_caller_id>
</verbacdr>

SMS example XML

<?xml version="1.0" encoding="utf-8"?>
<verbacdr>
<source_caller_id>15198274350</source_caller_id>
<destination_caller_id>12038894142</destination_caller_id>
<start_time>2019.07.15 14:40:15.618</start_time>
<end_time>2019.07.15 14:40:15.618</end_time>
<modality_id>sms</modality_id>
<sms>test message</sms>
</verbacdr>

File share example XML

<?xml version="1.0" encoding="utf-8"?>
<verbacdr>
    <source_caller_id>user1@verbatest.local</source_caller_id>
    <destination_caller_id>user2@verbatest.local</destination_caller_id>
    <start_time>2019.10.22 10:10:32.673</start_time>
    <end_time>2019.10.22 10:15:32.673</end_time>
    <modality_id>file_share</modality_id>
    <recorded_party>0</recorded_party>
</verbacdr>

Instant message example XML

<?xml version="1.0" encoding="utf-8"?>
<verbacdr state="1">
  <source_caller_id>user1@verbatest.local</source_caller_id>
  <source_name />
  <destination_caller_id>user2@verbatest.local</destination_caller_id>
  <recorded_cid>user2@verbatest.local</recorded_cid>
  <start_time>2018.11.08 14:03:54.566</start_time>
  <end_time>2018.11.08 14:05:43.806</end_time>
  <direction_id>4</direction_id>
  <modality_id>im</modality_id>
  <recorded_party>1</recorded_party>
</verbacdr>

Instant message example im file

<?xml version="1.0" encoding="utf-8"?>
<im>
<messages>
  <message id="1">
    <timestamp>2018-11-08T14:03:54.5662219Z</timestamp>
    <source>user1@verbatest.local</source>
    <destination>user2@verbatest.local</destination>
    <plain_message>Test message</plain_message>
    <subject />
  </message>
   <message id="2">
    <timestamp>2018-11-08T14:03:54.5662219Z</timestamp>
    <source>user2@verbatest.local</source>
    <destination>user1@verbatest.local</destination>
    <plain_message>Reply message</plain_message>
    <subject />
  </message>
</messages>
</im>

Conference example XML

The conference call direction is supported with all modalities except SMS. Verba creates the conference with the destination_caller_id as conference and the destination_name as Conference (platform_call_id), but this is not mandatory.

<?xml version="1.0" encoding="utf-8"?>
<verbacdr state="1">    <!-- Finished Call State -->
    <id>77251f8c-501c-11e6-80c5-00155d001c32</id>
	<platform_call_id>K6LNPTM1</platform_call_id>
    <source_caller_id>user1@verbalabs.com</source_caller_id>
    <source_name>User1</source_name>
    <destination_caller_id>conference</destination_caller_id>
    <destination_name>Conference (K6LNPTM1)</destination_name>
    <recorded_cid>user1@verbalabs.com</recorded_cid>
    <start_time>2019.07.22 14:56:28.833</start_time>
    <end_time>2019.07.22 14:57:45.800</end_time>
    <modality_id>voice</modality_id>
<!--Conference information -->
    <direction_id>14</direction_id>    <!-- Conference -->
    <recorded_party>0</recorded_party>    <!-- Source caller -->
    <conference>true</conference>
    <participants>
        <participant>
            <callerid>user1@verbalabs.com</callerid>
            <name>User1</name>
			<role>conferee</role>
            <start_time>2019.07.22 14:54:50.310</start_time>
            <end_time>2019.07.22 14:57:45.800</end_time>
            <end_cause>1</end_cause>
        </participant>
        <participant>
            <callerid>user2@verbalabs.com</callerid>
            <name>User2</name>
			<role>host</role>
            <start_time>2019.07.22 14:55:15.177</start_time>
            <end_time>2019.07.22 14:57:45.800</end_time>
            <end_cause>1</end_cause>
        </participant>
    </participants>
</verbacdr>

With the instant message IM file, the communication is between the conference participants and the conference bridge, the source is the user sending the message, and the destination is the conference bridge.

Trader voice example XML

The Turret data model does not require a one-to-one relationship between metadata and media, it is allowed to have multiple CDR for one media file, or multiple media files for one CDR. The link between the media and CDR is the media_record_ids field. The media is found based on the CDR record by searching for the matching media record IDs, then limiting the search for media end time before CDR start time, and media start time after CDR end time.

CDR record

<?xml version="1.0" encoding="utf-8"?>
<verbacdr state="1"> <!-- Finished Call State -->
<type>1</type> <!-- CDR only -->
<source_caller_id>6001</source_caller_id>
<destination_caller_id>588</destination_caller_id>
<start_time>2019.03.06 11:42:05.552</start_time>
<call_start_time>2019.03.06 11:42:05.552</call_start_time>
<end_time>2019.03.06 11:42:37.868</end_time>
<modality_id>voice</modality_id>
<media_record_ids>
<id>BT_IPSI-6-1-3</id>
</media_record_ids>
</verbacdr>

Media record

<?xml version="1.0" encoding="utf-8"?>
<verbacdr state="1"> <!-- Finished Call State -->
<type>2</type> <!-- Media only -->
<native_id>BT_IPSI-6-1-3</native_id>
<source_caller_id>6001</source_caller_id>
<destination_caller_id>6001</destination_caller_id>
<recorded_cid>6001</recorded_cid>
<start_time>2019.03.06 11:42:17.131</start_time>
<call_start_time>2019.03.06 11:42:11.191</call_start_time>
<media_start_time>2019.03.06 11:42:17.131</media_start_time>
<end_time>2019.03.06 11:42:42.131</end_time>
<modality_id>voice</modality_id>
<media_record_ids>
<id>BT_IPSI-6-1-3</id>
</media_record_ids>
</verbacdr>

Custom metadata example XML

In order to import custom metadata, a Metadata template has to be created in Verba prior to the import process. For the process of creating a metadata template, please refer to Metadata designer. The metadata fields are referred by the Field Identifier propery defined in the Web UI.

<?xml version="1.0" encoding="utf-8"?>
<verbacdr state="1">    <!-- Finished Call State --> 
<recorded_cid>testuser@verbalabs.com</recorded_cid>
<start_time>2019.06.21 14:40:15.618</start_time>
<end_time>2019.06.21 14:40:57.768</end_time>
<destination_caller_id>kakas@verbalabs.com</destination_caller_id>
<source_caller_id>6010</source_caller_id>
   <metadata>
        <metadata_template type="standard" name="Custom metadata">
            <field1>00478811846</field1>
        </metadata_template>
    </metadata>
</verbacdr>

Load Balancing

The Import API for import service is a single server solution with no built-in load balancing capabilities. If multiple servers are required for the volume of the calls imported, client-side load balancing can be set up, as each separate server needs a session token unique to the server.