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"}
Feedback
Comment on this article: