Import API
AVAILABLE IN 9.3 AND ABOVE
Overview
The Import API allows ingesting 3rd party or Verba data into the system.
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
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 |
---|---|
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
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 |
---|---|
200 | Successful authentication |
500 | Error during authentication |
Response headers
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 |
---|---|
status | The result of the authentication, possible values are ok, errorType: 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:
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 |
---|---|
apikey | The generated, unique GUID for the API key |
token | The token received in the authentication request body |
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 |
---|---|
200 | Successful import |
500 | Error during import |
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 |
---|---|
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 |
---|---|
status | The result of the authentication, possible values are ok, errorType: 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.