Universal Contact Server API Reference Guide

This is the UCS 9.1 API Reference Guide.

It details, within the same topic:

• RESTful services and methods, which can be accessed by clients directly.
• ESP services and methods, which are accessed via Genesys PSDK.

Overview

HTTP Requests

An HTTP request needs the following elements:

• An HTTP verb (or method).
• A header
• A URI (Uniform Resource Identifier) which identifies the resource upon which to apply the request
• An optional message body

HTTP Responses

• Responses contain a list of '<key>:<value>' entries in JSON format.
• In the ESP protocol some UCS functions return some <key>:<value> entries in parameters and some others in user data. When used through HTTP those functions return all <key>:<value> entries in a unique JSON document.

The functions that behave this way are:

• Callback.Create
• Chat.Create
• Contact.findOrCreate
• Contact.Identify
• OMFieldCodes.RenderMessageContent

Methods

In UCS the following methods are used: POST, PUT, GET and DELETE.

The general rule is:

• POST when method creates a new object
• PUT when the method updates an object
• GET when the method reads object content
• DELETE when the method deletes an object

URI Form

The URI is built as follows:

• POST and PUT methods:

<http|https>://<ucs host>:<port http or https>/<optional base url>/ucs/v1/<ucs service>/<ucs method>

• GET and DELETE methods:

<http|https>://<ucs host>:<port http or https>/<optional base url>/ucs/v1/<ucs service>/<ucs method>?<key1>=<value1>&<key2>=<value2>...

The optional base URL corresponds to the value of the option base-url in the http section.

Syntax for POST and PUT

Syntax when using the verbs POST and PUT:

<verb> http://<host>:<port>/<base url>/ucs/v1/<service>/<method>

{ 
   "Parameters": {
              "key1": value1,
              "key2": value2
              ...
   },
   "UserData": {   
              "key3": value3, 
              "key4": value4,
             ...
   }
 }

where:

• <verb> depends on the type of operation
• <service> is UCS's service name
• <method> is UCS's method name
• "Parameters" contains a JSON document with parameters
• "UserData" contains a JSON document with user data (not used by PSDK but used by ChatServer, URS and IXNServer.)

And:

• Key-value pairs are separated with comma.
• Each key is surrounded with "
• Values of type string are surrounded with "
• Values of type integer are not surrounded with "

A value of type binary must be base64 encoded and provided with a key named ‘binary’. Here is an example using InsertInteraction with a binary content:

POST http://<host>:<port>/<base url>/ucs/v1/OMInteractions/InsertInteraction

{code}
{
	"InteractionContent":{
		"MimeType":"Base64",
		"Content":{
			"binary":"SGVsbG8gVW5pdmVyc2UgIQ=="
		}
	},
	"InteractionAttributes":{
		"Status":1,
		"TenantId":101,
		"TypeId":"Internal",
		"EntityTypeId":7,
		"MediaTypeId":"email"
	}
}
{code}

Syntax for GET and DELETE

Syntax when using verb GET and DELETE:

 
<verb> http://<host>:<port>/<base url>/ucs/v1/<service>/<method>?<key1>=<value1>&<key2>=<value2>...

In this case the request does not have a body, all parameters are provided in the URL. The parameters come after the character '?'. They are key-value pairs separated with character '&'. The syntax for each parameter is <key>=<value> except for the following:

• ESQuery (in GetInteractions, InteractionListGet and ContactListGet) must be JSON-formatted. It should contain an Elasticsearch 5.5-compliant request (documentation is at https://www.elastic.co/guide/en/elasticsearch/reference/5.5/query-dsl.html).
• OwnerIds in requests GetCategorizedInteraction and GetUnCategorizedInteraction must be JSON- formatted and the character ':' must be used instead of '='.
• AttributeList (in InteractionListGet or ContactListGet) must be provided as a JSON array—for example:AttributeList={"AttrName":["Subject","Id"]}
• SearchCriteria (in InteractionListGet or ContactListGet) must be provided as a JSON object—for example: SearchCriteria={"EQUAL":{"AttrName":"CreatorAppId","AttrValue":169}}
• SortCriteria (in InteractionListGet or ContactListGet) must be provided as a JSON object—for example: SortCriteria={"StartDate":"ASC"}