Cention Logio (login & logout) API:

  • To use Cention Contact Center logio API, a Bearer Token with ‘Access to logio API’ claim is needed (see steps and Screenshot below).
  • To create Bearer Token, go to Cention server → Administration tab → API → Access Tokens.
  • Click on Create New button and tick the checkbox beside ‘Access to logio API’ under Others.
  • Fill up the required Name & Key fields or otherwise the Save button will not be clickable.
Screenshot

 

Screenshot

The API could be called from any web agent with Bearer Token in the http header: Authorization: Bearer <token>. For example Authorization: Bearer eyJhbGci...<snip>...yu5CSpyHI


Usage:

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/custom/logio to call logio API. If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com then the endpoint would be: https://api.cention.com/s/demo/capi/custom/logio

API Query Parameters

FieldDescription
nameLogin name of an agent for retrieval, default (if not specified) is to retrieve records for all agents.
formatOutput format of an export, available choices are csv and json; default (if not specified) is to use csv format.
fromTimestamp of records to be retrieved in unix format; default (if not specified) is to retrieve records from last 7 days.
toTimestamp of records to be retrieved in unix format; default (if not specified) is to use current timestamp.

Sample of query

  • A query without parameter will retrieve last 7 days of login and logout records for all agents within a system group (which the Bearer Token was created), in csv format.
      curl -H "Authorization: Bearer <token>" "https://<cention api domain>/s/<workspace>/capi/custom/logio"
  • Use name (login name) parameter to retrieve login and logout records for a specific agent.
      curl -H "Authorization: Bearer <token>" \
      "https://<cention api domain>/s/<workspace>/capi/custom/logio?name=joe"
  • Use format parameter to retrieve login and logout records in specific format, current supported formats are csv and json.
      curl -H "Authorization: Bearer <token>" \
      "https://<cention api domain>/s/<workspace>/capi/custom/logio?format=csv"
  • Use from and to parameter to retrieve login and logout records within a specific time frame, these parameters are in unix timestampt format.
      curl -H "Authorization: Bearer <token>" \
      "https://<cention api domain>/s/<workspace>/capi/custom/logio?from=1554857192&to=1555980452"
  • Parameters could be combined into a single query, e.g. the following will retrieve login and logout records ranged between 1554857192 and 1555980452 for agent sysadmin, in csv format.
      curl -H "Authorization: Bearer <token>" \
      "https://<cention api domain>/s/<workspace>/capi/custom/logio?from=1554857192&to=1555980452&name=sysadmin&format=csv"

Output Response Fields

FieldDescription
idRunning number of the retrieved login/logout records.
nameLogin name of an agent
timestampTimestamp of login or logout action
actionLogin or Logout

Sample of response

  • csv (headerless, unix new line format)
     1,sysadmin,1554108462,Logout
     2,tester1,1554108529,Logout
     3,sysadmin,1554108536,Login
     4,sysadmin,1554108578,Logout
     5,tester1,1554108586,Login
  • json (there will be no line break between records in actual response)
     [{"id":1,"name":"sysadmin","timestamp":1554108462,"action":"Logout"},
      {"id":2,"name":"tester1","timestamp":1554108529,"action":"Logout"},
      {"id":3,"name":"sysadmin","timestamp":1554108536,"action":"Login"},
      {"id":4,"name":"sysadmin","timestamp":1554108578,"action":"Logout"},
      {"id":5,"name":"tester1","timestamp":1554108586,"action":"Login"}]

Notes

  • For security reason, logio will retrieve records within same system group; meaning if the API was created in system group A, the retrieval will pull records within system group A only.

  • Convertion between unix timestamp and human readable format could be done programatically or via online, e.g. epochconverter.Logi

Cention API for Create Errand:

  • To create errand, a JSON Web Token (JWT) with ‘Create Errand’ claim attached is needed.
  • To create JWT go to Cention server → Administration tab → API → Access Tokens.
  • Select the channel and account or area that the created errand will reside on. NOTE: Form channel should choose area to attach to JWT.
  • Make sure to fill up the Key field else Save button will not be activated.
  • Screenshot: 

The API follows JSONAPI specification: http://jsonapi.org/ . Following is some of the specification that must follow:

  • Use HTTP POST with endpoint: https:///s//capi/json/c3_new_errands for creating errand. If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com then the endpoint would be: https://api.cention.com/s/demo/capi/json/c3_new_errands
  • http://jsonapi.org/format/#content-negotiation-clients
  • Put the token in header: Authorization: Bearer . For example Authorization: Bearer eyJhbGci......yu5CSpyHI
  • HTTP request header Content-Type must be: application/vnd.api+json
  • Sample HTTP request body data format:
{
  "data": {
    "type": "c3_new_errands",
    "attributes": {
      "msg": {
        "message_id": "msgid_1485096554",
        "name": "David Liew",
        "from": "david.liew@test.se",
        "subject": "Creating test errand via API",
        "body": "Test message body at Sun, 22 Jan 2017 22:49:14 +0800",
        "html_body": "",
        "attachments": [
          {
            "content_type": "text\/plain",
            "name": "tst1.txt",
            "content": "QXBwbGUgUGVuIFBpbmVhcHBsZSBQZW4="
          },
          {
            "content_type": "text\/plain",
            "name": "tst2.txt",
            "content": "T3JhbmdlIEp1aWNlIQ=="
          }
        ]
      },
      "extradata": {
        "message_id": "msgid_1485096554",
        "case_number": 21345,
        "zone": "A"
      },
      "integrationData": {
        "integrationName": "aventa",
        "referenceId": "1",
        "deviceId": 1000,
        "extensionId": 1000,
        "link": "https:www.google.com",
        "endSession": false,
        "destNumber": "60374571234",
        "pagingNumber": "12345",
        "pagingName": "GP office",
        "queueName": "EHS",
        "queueNumber": "123",
        "extraData": {
            "comment": "internal comment",
            "callReason": "reschedule appointment",
            "appointmentTimestamp": "1593047865"
        }
      },
      "cuid": "5462-13-6485"
    }
  }
}

NOTE: attachment content is base64. All the fields under the sample data.attributes.msg is currently supported. Other relevant fields may be supported upon request.

data.type.attributes.msg (object)

FieldTypeDescription
message_idStringString to uniquely identify the mail.
nameStringWriter name.
fromStringWriter address (email address if email/web form channel)
subjectStringSubject of the mail.
bodyStringPlain text body.
html_bodyStringRich text body (supported for email/web form channel)
attachmentsArrayAttachment content of the errand.

data.type.attributes.msg.attachments (array of objects)

FieldTypeDescription
content_typeStringFile type RFC2616
nameStringAttachment file name.
contentStringBase64 encoded attachment content.

Use answer object below to create an closed errand (it will not show on New Workflow page).

data.type.attributes.answer (object)

FieldTypeDescription
subjectStringSubject of the answered mail.
bodyStringPlain text answer body.
html_bodyStringRich text answer body (supported for email/web form channel)
user_typeStringUser type eg: “cention”, “solidus” and “clearinteract”
user_idStringDatabase ID that identify the user that close the errand.

Use watemplate object below to send whatsapp manual errand as whatsapp template.

data.type.attributes.answer (object) During sending whatsapp template this answer object is needed, however the subject, body, html_body not necessarily needed. Bellow is the sample example:

"answer":{
  "user_type":"cention",
  "user_id": "<3C system USER_ID>"
}

data.type.attributes.watemplate (object)

FieldTypeDescription
elementnameStringElement name of the whatsapp template.
namespaceStringNamespace given by whatsapp.
paramsJSONJson array
"watemplate":{
  "elementname":"",
  "namespace": "",
  "params":[
      {"default": "$10", "order": "1234"}
    ]
  }

data.type.attributes.extradata (object)

  • Any data that conforms to JSON format can be sent. The data will be stored and presented as text in database. This object is optional.

data.type.attributes.integrationData (object)

  • Any data that conforms to JSON format can be sent. The data will only be applied if integration with external voice system is enable. This object is optional

Supported integrations

  • Only aventa integration is supported at the moment. The fields relevant this integration are as described below
FieldTypeMandatoryDescription
integrationNameStringYesname of the integration
referenceIdStringNoId used to identify a call by external system
deviceIdIntegerYesDevice id used by agent. Used as part of key to identify agent in Cention
extensionIdIntegerYesExtension id used by agent. Used as part of key to identify agent in Cention
linkStringNoURL to stored voice call in external system
endSessionBooleanNoFlag to indicate if the call has ended
destNumberStringYesThe number that was used to reach the external system. The called party number. Must be in MSISDN format.
pagingNumberStringNoThe number to use when calling Aventa’s call AP for outbound call
pagingNameStringNoThe number associated with paging number
queueNameStringYesName of the aventa queue where the voice call originated from
queueNumberStringYesID of the call in aventa’s queue
extraDataStructNoStructure to store extra information to be stored in errand

data.type.attributes.extraData (object)

FieldTypeMandatoryDescription
commentStringNoAdditional comments to be stored as errand’s internal comment
callReasonStringNoDescription for the reason the call was made
appointmentTimestampStringNounix timestamp

data.type.attributes.cuid (string)

  • Can be used to store unique identifier from external systems. The value will be stored as part of Contact Card information but will not be checked for uniqueness within Cention’s database. Example values could be Passport Number or Social Security Number. This field is otpional.

HTTP request return body:

{
    "data": {
        "type": "c3_new_errands",
        "id": "511055"
    }
}

Cention API for Close Errand:

  • To close an errand a JSON Web Token (JWT) with ‘Create Errand’ claim attached is needed (see above for how to create the JWT).
  • Use HTTP POST with endpoint: https:///s//capi/json/c3_end_errands

Sample HTTP request body:

{
    "data": {
        "type": "c3_end_errands",
        "attributes": {
            "errand_id": 4321,
            "answer": {
                "user_type": "cention",
                "user_id": "1234",
                "subject": "Answer subject",
                "body": "",
                "html_body": ""
            }
        }
    }
}

data.attributes.answer (object)

FieldTypeDescription
subjectStringSubject for answer
bodyStringPlain text answer body
html_bodyStringRich text answer body (supported for email/web form channel)
user_typeStringUser type: “cention”, “solidus” or “clearinteract”
user_idStringIdentifier for user that closed the errand

Cention API for End Outbound Call:

  • To notify cention of an ended call a JSON Web Token (JWT) with ‘Create Errand’ claim attached is needed (see above for how to create the JWT).
  • Use HTTP POST with endpoint: https:///s//capi/json/c3_end_obcall

Sample HTTP request body:

{
    "data": {
        "type": "c3_end_errands",
        "attributes": {
            "integrationName": "aventa",
            "dialedNumber": "01211112222",
            "deviceId": 1000,
            "extensionId": 1000
        }
    }
}

data.attributes(object)

FieldTypeMandatoryDescription
integrationNameStringYesName of the integration used for the outbound call
dialedNumberStringNoThe dialed phone number for outbound call
deviceIdIntegerYesDevice id used by agent. Used as part of key to identify agent in Cention
extensionIdIntegerYesExtension id used by agent. Used as part of key to identify agent in Cention

Cention Callback API:

  • Callback settings can be found at Cention server → Administration tab → API → Callback
  • Provide the server URL that Cention server will send HTTP(s) request to as Endpoint field.
  • Secret Key field is optional and if not empty it’ll be sent together inside the callback JSONAPI payload.
  • Choose Areas for the respective Event to trigger the Event. Currently only Areas selection is working.
  • Save button inactive until there is changes between UI data and backend server.
  • Callback JSONAPI payload format is following JSONAPI specification: http://jsonapi.org/
  • Callback will use HTTP(s) POST method.
  • Screenshot: 
  • Sample callback payload format:
{
  "data": {
    "type": "c3_callback_answer_errands",
    "id": "76",
    "attributes": {
      "event": 1
    },
    "relationships": {
      "errand": {
        "data": {
          "type": "c3_answer_errands",
          "id": "2256"
        }
      }
    }
  },
  "included": [
    {
      "type": "c3_response_attachments",
      "id": "789",
      "attributes": {
        "c3_id": 789
      },
      "links": {
        "self": {
          "href": "http:\/\/localhost\/capi\/json\/c3_response_attachments\/789"
        }
      }
    },
    {
      "type": "c3_response_attachments",
      "id": "790",
      "attributes": {
        "c3_id": 790
      },
      "links": {
        "self": {
          "href": "http:\/\/localhost\/capi\/json\/c3_response_attachments\/790"
        }
      }
    },
    {
      "type": "c3_area_archives",
      "id": "12",
      "attributes": {
        "c3_id": 12
      },
      "links": {
        "self": {
          "href": "http:\/\/localhost\/capi\/json\/c3_area_archives\/12"
        }
      }
    },
    {
      "type": "c3_answer_errands",
      "id": "2256",
      "attributes": {
        "answer": {
          "c3_id": 1189,
          "response": {
            "body": "text",
            "c3_id": 3304,
            "html_body": "

\”font-size:;font-family:;\”>

sadadad\”cid:12\” \/></span\”\” src=\”cid:attachment_788\” \/><\/div>\n\n
\/>
\/>

 
\u00a0<\/div>\r\n\"http:\/\/localhost\/errands\/satisfaction\/meter\/-\/answer\/4d6a49314e673d3d\/1b7f046991d401785264fc4d35ca3db6\" style=\"font-family:Verdana; font-size:10pt; color:black; font-style:normal;\">optionONE<\/a>
\/>\"http:\/\/localhost\/errands\/satisfaction\/meter\/-\/answer\/4d6a4931AAA73d3d\/73d05e8f6ec0ca1AAAa6608b78debd9\" style=\"font-family:Verdana; font-size:10pt; color:black; font-style:normal;\">optionTWO<\/a>
\/>
\/>\n--------- Cention Contact Center - Original message ---------
\/>\nErrand: #2256-1
\/>\nFrom: Sany Liew (david.liew@test.se)
\/>\nSent: 2017\/01\/22 16:53
\/>\nTo: test-services-area
\/>\nSubject: Creating test errand via API
\/>\nQuestion: 
\/>\n
\/>\nTest message body at Sun, 22 Jan 2017 16:53:04 +0800
\/>\n
\/>--------- Cention Contact Center - Original message - End ---------<\/div>",
            "subject": "Creating test errand via API",
            "to": [
              {
                "c3_id": 279,
                "email_address": "david.liew@test.se",
                "name": "David Liew"
              }
            ]
          }
        },
        "c3_id": 2256,
        "service": {
          "c3_id": 16,
          "name": "Form",
          "type": 19
        }
      },
      "relationships": {
        "attachments": {
          "data": [
            {
              "type": "c3_response_attachments",
              "id": "788"
            },
            {
              "type": "c3_response_attachments",
              "id": "789"
            },
            {
              "type": "c3_response_attachments",
              "id": "790"
            }
          ]
        },
        "embedded_archives": {
          "data": [
            {
              "type": "c3_area_archives",
              "id": "12"
            }
          ]
        }
      }
    },
    {
      "type": "c3_response_attachments",
      "id": "788",
      "attributes": {
        "c3_id": 788
      },
      "links": {
        "self": {
          "href": "http:\/\/localhost\/capi\/json\/c3_response_attachments\/788"
        }
      }
    }
  ],
  "meta": {
    "api_secret": "123456"
  }
}

data.type.attributes.event (integer)

  • Identifier of the incoming event.
Event IDDescription
1Answer errand.

included (array of objects)

Object typeTypeDescription
c3_answer_errandsObjectDetail of the answered errand.
c3_response_attachmentsObjectAttachment that attached to the answered errand.
c3_area_archivesObjectImage that is embedded inside the HTML body of the errand.

c3_answer_errands attributes.answer.response

FieldTypeDescription
subjectStringErrand’s subject.
bodyObjectErrand’s plain text.
html_bodyObjectErrand’s rich text.
toArrayThe errand intended target.

c3_answer_errands attributes.answer.response.to

FieldTypeDescription
email_addressStringEmail address of the errand intended target.
nameStringName of the intended target.

c3_answer_errands attributes.service

FieldTypeDescription
nameStringErrand’s service/channel name.
typeIntegerIdentifier of the errand’s service/channel.

c3_response_attachments c3_area_archives

FieldTypeDescription
links.self.href or links.selfStringHTTP GET endpoint to request the attachment content.

meta.api_secret (string)

  • Non-empty string that was inserted in callback setting’s Secret Key field.

Note

  • Errand data is reside inside Resource Objects (http://jsonapi.org/format/#document-resource-objects) c3_answer_errands. Other relevant errand fields can be supported upon request.
  • Callback API payload don’t provide attachment but only the information how to get it. HTTP(s) GET is needed to get attachments of errand. The endpoint of each is provided in JSONAPI recommended links field.
  • Sample format requested attachment’s response body (this requires JSON Web Token carry get attachment claim):
{
  "data": {
    "id": "1270",
    "type": "c3_response_attachments",
    "attributes": {
      "attachment": {
        "c3_id": 1270,
        "content_type": "text\/plain",
        "name": "tst1_1.txt",
        "content": "QXBwbGUgUGVuIFBpbmVhcHBsZSBQZW4="
      }
    }
  }
}

c3_response_attachments c3_area_archives data.attributes.attachment

FieldTypeDescription
content_typeStringFile type RFC2616
nameStringAttachment file name.
contentStringBase64 encoded attachment content.

References:

  1. Cention SDK (golang).
  2. Sample create errand program.
  3. Sample server receiving callback API.
  4. JSONAPI specification.

Cention Errand Report:

  • To access Cention Errand Report, a JSON Web Token (JWT) with ‘Access to errand data’ claim attached is needed.
  • To create JWT go to Cention server → Administration tab → API → Access Tokens.
  • Check (tick) ‘Access to errand data’ from Others.
  • Make sure to fill up the Key field else Save button will not be activated.
  • Screenshot: 

The API follows JSONAPI specification: http://jsonapi.org/ . Following is some of the specification that must follow:


Migration from old endpoint

  • Must compliance with JSONAPI negotiation.
  • No cookie. Use token with Authorization header.
  • errand/listWhoHasChanged → c3_dirty_errand_list/<id>
  • errand/complete/<id> → c3_errand_reports/<id>
  • facebook/ratings/listWhoHasChanged → c3_dirty_facebook_ratings
  • facebook/ratings/fetch/<id> → c3_facebook_ratings/<id>
  • Old format of returned JSON data of X now encapsulate inside {data: {attributes: X}} because of JSONAPI format requirement.

Errand Reports

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_errand_reports/<id> to GET single errand with database ID id (without angle bracket). If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com and the id is 101 then the endpoint would be: https://api.cention.com/s/demo/capi/json/c3_errand_reports/101
  • Errand fetch by this endpoint will clear its dirty flag and will not appears in the request to c3_dirty_errand_list endpoint.
  • Use sparse fields query param to select only required attribute field. Refer to sparse fields specification. For example: https://api.cention.com/s/demo/capi/json/c3_errand_reports/101?fields%5Bc3_errand_reports%5D=sla can be used to only fetch SLA attribute.
  • Sample HTTP request body data format:
{
  "data": {
    "type": "c3_errand_reports",
    "id": "33",
    "attributes": {
      "actions": [
        {
          "id": 83,
          "note": "Errand 33 was opened by agent System Administrator at 2015-07-16 20:50:17 +0800 MYT.",
          "origin": "System Administrator",
          "time": "2015-07-16 20:50:17 +0800 MYT",
          "timeStamp": 1437051017
        },
        {
          "id": 111,
          "note": "Errand 33 was opened by agent System Administrator at 2015-07-17 17:07:48 +0800 MYT.",
          "origin": "System Administrator",
          "time": "2015-07-17 17:07:48 +0800 MYT",
          "timeStamp": 1437124068
        },
        {
          "id": 112,
          "note": "Errand 33 was answered and closed by agent System Administrator at 2015-07-17 17:08:26 +0800 MYT.",
          "origin": "System Administrator",
          "time": "2015-07-17 17:08:26 +0800 MYT",
          "timeStamp": 1437124106
        }
      ],
      "basic": {
        "acquired": false,
        "data": {
          "id": 33,
          "displayId": "33",
          "status": "<img src=\"\/ng\/img\/icons\/ACTION_ANSWER.png\" style=\"vertical-align:middle;\" title=\"Errand has been answered\" border=\"0\"\/> ",
          "service": 1,
          "serviceName": "Email",
          "organisationId": 3,
          "organisationName": "cention-org",
          "area": 1,
          "areaName": "test-services-area",
          "priority": "",
          "agentId": 2,
          "agent": "System Administrator",
          "from": "Cention \u0108\u0108\u0108, Leader (test.account@cention.se)",
          "fromAddress": "test.account@cention.se",
          "fromName": "Cention \u0108\u0108\u0108, Leader",
          "to": "test.tester@cention.asia",
          "toAddresses": [
            "test.tester@cention.asia"
          ],
          "copy": "",
          "copyAddresses": null,
          "subject": "test",
          "iconicSubject": "<img src=\"\/Cention.app\/Resources\/Images\/unassuming-icon.gif\" title=\"From Cention\" style=\"vertical-align:middle;\" border=\"0\"\/> test",
          "body": "<div dir=\"ltr\">test222<\/div>\r\n",
          "date": "2015\/07\/16 20:47",
          "answeredDate": "2015\/07\/17 17:08",
          "donedate": "No Date",
          "attachments": "0",
          "closed": true,
          "deleted": false,
          "answered": true,
          "wasForwardedToExternal": false,
          "wasClonedAndForwardedExternal": false,
          "feedbackAnswer": "",
          "feedbackLink": "",
          "fbPms": false,
          "fbLikes": "",
          "fbAction": "",
          "sendPm": false,
          "hasAnswer": false,
          "answerDeleted": false,
          "retweet": false,
          "twitterPm": false,
          "secureUserId": ""
        },
        "groupWith": 0,
        "hasChild": false,
        "id": 33,
        "style": {

        },
        "threadId": 32
      },
      "c3_id": 33,
      "changed": true,
      "extended": {
        "answer_body": "test body",
        "answer_subject": "test",
        "errand_tags": [
            {
              "desc": "Test High Tag",
              "id": 32
            }
        ],
        "feedback": {
          "Answer": "",
          "QuestionHTML": "",
          "QuestionText": "",
          "value": 0
        }
      },
      "sla": {
       "done_due": false,
       "expiry": 0,
       "handling_time": 0,
       "response_time": 0,
       "within_sla": false
      }
    }
  }
}

Data.attributes.actions

FieldTypeDescription
idIntegerDatabase unique ID of the action object.
noteStringHuman readable note of the action detail.
originStringAgent name that trigger the action.
timeStringHumann readable time format.
timeStampIntegerTimestamp.

Data.attributes.basic

FieldTypeDescription
idIntegerDatabase unique ID the errand object.
acquiredBooleanWhether errand had been acquired by an agent.
groupWithIntegerWhether errand within threaded errands.
hasChildBooleanWhether this errand is parent of another errand (reply to this errand).

Data.attributes.extended

FieldTypeDescription
answer_bodyStringAnswer text for this errand (agent’s reply).
answer_subjectStringSubject of this errand’s reply.
errand_tagsArrayNon-system tags.
feedbackObjectFeedback data.
reportObjectReport SLA data.

Data.attributes.sla

FieldTypeDescription
done_dueBooleanIf the errand done date due. NOTE: this is just compare done date with current date.
expiryIntegerExpiry state: 0: no expiry. 1: warning. 2: expired.
handling_timeIntegerTotal handling time in seconds.
response_timeIntegerTotal response time in seconds.
within_slaBooleanIf the errand handling within SLA.
  • NOTE: attribute sla return null if the report is processing the data which occur every minute. Expiration may has roughly 5 minutes update delay.

Dirty Errand List

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_dirty_errand_list to get all the errands ID that have changed its content.
  • Use HTTP POST with sam endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_dirty_errand_list to force list of errand marks as changed.
  • Sample HTTP GET request body data format:
{
  "data": {
    "type": "c3_dirty_errand_list",
    "id": "0",
    "attributes": {
      "errands": [
        34,
        3203,
        3204,
        3216,
        3217
      ]
    }
  }
}
  • Sample HTTP POST request body data format (request):
{
  "data": {
    "type": "c3_dirty_errand_list",
    "attributes": {
      "errands": [
        35
      ]
    }
  }
}
  • Sample HTTP POST request body data format (response):
{
  "data": {
    "type": "c3_dirty_errand_list",
    "id": "0"
  }
}

Dirty Facebook Rating List

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_dirty_facebook_ratings to get all the database Facebook rating ID that have changed its content.
  • Sample HTTP GET request body data format:
{
  "data": [
    {
      "type": "c3_dirty_facebook_ratings",
      "id": "3"
    },
    {
      "type": "c3_dirty_facebook_ratings",
      "id": "4"
    }
  ]
}

Facebook Rating

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_facebook_ratings/<id> to get the database for Facebook rating with database ID id (without angle bracket).
  • Facebook rating fetch by this endpoint will clear its dirty flag and will not appears in the next request to c3_dirty_facebook_ratings endpoint.
  • Sample HTTP GET request body data format:
{
  "data": {
    "type": "c3_facebook_ratings",
    "id": "3",
    "attributes": {
      "c3_id": 3,
      "data": {
        "isChanged": false,
        "message": "Hi its a really great page. It helps to find more people:)",
        "rating": 5,
        "ratingId": 3,
        "reviewerId": 2117249628,
        "reviewerName": "Jessica Elizabeth",
        "timestampCreated": 1489569020
      }
    }
  }
}

References:

  1. JSONAPI specification.

Cention Contact Cards JSONAPI:

  • To create Cention contact card, a JSON Web Token (JWT) with ‘Access and create customer contacts’ claim attached is needed.
  • To create JWT go to Cention server → Administration tab → API → Access Tokens.
  • Check (tick) ‘’Access and create customer contacts’ from Others.
  • Make sure to fill up the Key field else Save button will not be activated.
  • Screenshot: 

The API follows JSONAPI specification: http://jsonapi.org/ . Following is some of the specification that must follow:


Contact Cards

  • Use HTTP POST with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_contact_cards to create contact cards. If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com then the endpoint would be: https://api.cention.com/s/demo/capi/json/c3_contact_cards
  • To ease the contact card creation and avoid duplication, the same endpoint will not create duplicate contact if any of the provided contacts found inside database. In such situation, the contact will be updated by appending on the found contact. NOTE: this is not compatible with JSONAPI specification.
  • Sample HTTP POST request body data format for creating/updating contact cards:
{
  "data": {
    "type": "c3_contact_cards",
    "attributes": {
      "contacts": {
        "email": [
          "tester.c3@cention.se",
          "tester.c3.2@cention.se"
        ],
        "facebook": [
          "12345@facebook.com"
        ],
        "name": "Tester Cention"
      }
    }
  }
}
  • Sample HTTP POST response data format for creating/updating contact cards (include id field):
{
  "data": {
    "type": "c3_contact_cards",
    "id": "13",
    "attributes": {
      "c3_id": 13,
      "contacts": {
        "name": "Tester Cention",
        "email": [
          "tester.c3@cention.se",
          "tester.c3.2@cention.se"
        ],
        "facebook": [
          "12345@facebook.com"
        ]
      }
    }
  }
}

Data.attributes

FieldTypeDescription
contactsObjectObject with supported contact fields such as email, facebook, etc.
nameStringPerson name of the contacts belong to.

Data.attributes.contacts

FieldTypeDescription
emailArray of StringEmails.
facebookArray of StringFacebook account, ex: 12345@facebook.com.
vkArray of StringVKontakte account, ex: centionvk-cc-12345.
lineArray of StringLINE messenger, ex: centionline-c12345.
voiceArray of StringPhone number (with plus sign).

References:

  1. JSONAPI specification.

Cention Library JSONAPI:

  • To access Cention library, a JSON Web Token (JWT) with ‘Access to library’ claim attached is needed.
  • To create JWT go to Cention server → Administration tab → API → Access Tokens.
  • Check (tick) ‘Access to library’ from Others.
  • Make sure to fill up the Key field else Save button will not be activated.
  • Screenshot: 

The API follows JSONAPI specification: http://jsonapi.org/ . Following is some of the specification that must follow:


Library

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_libraries to GET all. If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com then the endpoint would be: https://api.cention.com/s/demo/capi/json/c3_libraries
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_libraries/<id> to GET single library with database ID id.
  • Sample HTTP request body data format for GET all:
{
  "data": [
    {
      "type": "c3_libraries",
      "id": "3",
      "attributes": {
        "c3_id": 3,
        "external": false,
        "name": "cention-org - area-named-second"
      },
      "relationships": {
        "categories": {
          "data": [
            {
              "type": "c3_library_categories",
              "id": "3"
            }
          ]
        },
        "questions": {
          "data": [
            {
              "type": "c3_library_questions",
              "id": "2"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "c3_library_attachments",
      "id": "2020",
      "attributes": {
        "attachment": {
          "c3_id": 2020,
          "content_type": "text\/plain",
          "name": "tst1_1.txt"
        },
        "c3_id": 2020
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_attachments\/2020"
        }
      }
    },
    {
      "type": "c3_library_questions",
      "id": "4",
      "attributes": {
        "answer": "New answer!",
        "c3_id": 4,
        "question": "",
        "subject": "asdadasdas"
      },
      "relationships": {
        "attachments": {
          "data": [
            {
              "type": "c3_library_attachments",
              "id": "2020"
            }
          ],
          "links": {
            "related": {
              "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/4\/attachments"
            },
            "self": {
              "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/4\/relationships\/attachments"
            }
          }
        }
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/4"
        }
      }
    },
    {
      "type": "c3_library_questions",
      "id": "2",
      "attributes": {
        "answer": "done!",
        "c3_id": 2,
        "question": "11th body<br\/>2nd line<br\/>",
        "subject": "11th title"
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/2"
        }
      }
    },
    {
      "type": "c3_library_questions",
      "id": "5",
      "attributes": {
        "answer": "done 2",
        "c3_id": 5,
        "question": "<div dir=\"ltr\">first HELP me!<\/div>\n",
        "subject": "help me!"
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/5"
        }
      }
    },
    {
      "type": "c3_libraries",
      "id": "4",
      "attributes": {
        "c3_id": 4,
        "external": false,
        "name": "cention-org - test-services-area"
      },
      "relationships": {
        "questions": {
          "data": [
            {
              "type": "c3_library_questions",
              "id": "5"
            },
            {
              "type": "c3_library_questions",
              "id": "4"
            }
          ]
        }
      }
    },
    {
      "type": "c3_library_categories",
      "id": "3",
      "attributes": {
        "c3_id": 3,
        "name": "old_libraries"
      },
      "relationships": {
        "libraries": {
          "data": [
            {
              "type": "c3_libraries",
              "id": "4"
            }
          ]
        }
      }
    }
  ]
}

Data.attributes

FieldTypeDescription
externalBooleanFlag indicate if the library external or not.
nameStringLibrary name.

Data.relationships

FieldTypeDescription
librariesObjectSub-libraries (c3_libraries).
categoriesObjectSub-categories (c3_library_categories).
questionsObjectQuestions under this library (c3_library_questions).

Query parameters

FieldTypeDescription
data_urlBooleanWhen true, any inlined area file archive image within library question will be parsed with data URL format where the file content is base64 encoded and embed inside library content.

External Library

  • Similar to library but only match library with external flag true and don’t return external attribute.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_external_libraries to GET all libraries with external flag true.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_external_libraries/<id> to GET single library with database ID id.
  • Sample HTTP request body data format GET single:
{
  "data": {
    "type": "c3_external_libraries",
    "id": "3",
    "attributes": {
      "c3_id": 3,
      "name": "cention-org - area-named-second"
    },
    "relationships": {
      "categories": {
        "data": [
          {
            "type": "c3_library_categories",
            "id": "3"
          }
        ]
      },
      "questions": {
        "data": [
          {
            "type": "c3_library_questions",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "c3_library_questions",
      "id": "2",
      "attributes": {
        "answer": "ok one",
        "c3_id": 2,
        "question": "11th body<br\/>2nd line<br\/>",
        "subject": "11th title"
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/2"
        }
      }
    },
    {
      "type": "c3_library_questions",
      "id": "1",
      "attributes": {
        "answer": "n",
        "c3_id": 1,
        "question": "dfdgfd",
        "subject": "asdasda"
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/1"
        }
      }
    },
    {
      "type": "c3_libraries",
      "id": "4",
      "attributes": {
        "c3_id": 4,
        "external": false,
        "name": "cention-org - test-services-area"
      },
      "relationships": {
        "questions": {
          "data": [
            {
              "type": "c3_library_questions",
              "id": "1"
            },
            {
              "type": "c3_library_questions",
              "id": "2"
            }
          ]
        }
      }
    },
    {
      "type": "c3_libraries",
      "id": "3",
      "attributes": {
        "c3_id": 3,
        "external": true,
        "name": "cention-org - area-named-second"
      },
      "relationships": {
        "questions": {
          "data": [
            {
              "type": "c3_library_questions",
              "id": "2"
            }
          ]
        }
      }
    },
    {
      "type": "c3_library_categories",
      "id": "3",
      "attributes": {
        "c3_id": 3,
        "name": "old_libraries"
      },
      "relationships": {
        "libraries": {
          "data": [
            {
              "type": "c3_libraries",
              "id": "4"
            },
            {
              "type": "c3_libraries",
              "id": "3"
            }
          ]
        }
      }
    }
  ]
}

Data.attributes

FieldTypeDescription
nameStringLibrary name.

Data.relationships

FieldTypeDescription
librariesObjectSub-libraries (c3_libraries).
categoriesObjectSub-categories (c3_library_categories).
questionsObjectQuestions under this library (c3_library_questions).

Query parameters

FieldTypeDescription
data_urlBooleanWhen true, any inlined area file archive image within library question will be parsed with data URL format where the file content is base64 encoded and embed inside library content.

Category

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_categories to GET all.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_categories/<id> to GET single category with database ID id.
  • Data format return similar endpoint c3_libraries and c3_external_libraries.
  • Sample HTTP request body data format GET all:
{
  "data": [
    {
      "type": "c3_library_categories",
      "id": "2",
      "attributes": {
        "c3_id": 2,
        "name": "greeting"
      },
      "relationships": {
        "questions": {
          "data": [
            {
              "type": "c3_library_questions",
              "id": "5"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "c3_library_questions",
      "id": "5",
      "attributes": {
        "answer": "ok\n",
        "c3_id": 5,
        "question": "<div dir=\"ltr\">first HELP me!<\/div>\n",
        "subject": "help me!"
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/5"
        }
      }
    }
  ]
}

Data.attributes

FieldTypeDescription
nameStringCategory name.

Data.relationships

FieldTypeDescription
librariesObjectSub-libraries (c3_libraries).
categoriesObjectSub-categories (c3_library_categories).
questionsObjectQuestions under this category (c3_library_questions).

Query parameters

FieldTypeDescription
data_urlBooleanWhen true, any inlined area file archive image within library question will be parsed with data URL format where the file content is base64 encoded and embed inside library content.

Library Question

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_questions to GET all.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_libraries/<id>/questions to GET all questions belong to library id.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_questions/<id> to GET single question with database ID id.
  • Sample HTTP request body data format for single question:
{
  "data": {
    "type": "c3_library_questions",
    "id": "4",
    "attributes": {
      "answer": "New answer!",
      "c3_id": 4,
      "question": "",
      "subject": "asdadasdas"
    },
    "relationships": {
      "attachments": {
        "data": [
          {
            "type": "c3_library_attachments",
            "id": "2020"
          }
        ],
        "links": {
          "related": {
            "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/4\/attachments"
          },
          "self": {
            "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/4\/relationships\/attachments"
          }
        }
      }
    }
  },
  "included": [
    {
      "type": "c3_library_attachments",
      "id": "2020",
      "attributes": {
        "attachment": {
          "c3_id": 2020,
          "content_type": "text\/plain",
          "name": "tst1_1.txt"
        },
        "c3_id": 2020
      },
      "links": {
        "self": {
          "href": "https:\/\/test.example.com\/capi\/json\/c3_library_attachments\/2020"
        }
      }
    }
  ],
  "links": {
    "self": {
      "href": "https:\/\/test.example.com\/capi\/json\/c3_library_questions\/4"
    }
  }
}

Data.attributes

FieldTypeDescription
subjectStringSubject field.
questionStringQuestion field.
answerStringAnswer field.

Data.relationships

FieldTypeDescription
attachmentsObjectAttachments for the library question (c3_library_attachments).

Query parameters

FieldTypeDescription
data_urlBooleanWhen true, any inlined area file archive image within library question will be parsed with data URL format where the file content is base64 encoded and embed inside library content.

Query parameters for GET all

FieldTypeDescription
filter[toplist]BooleanShown only the top list questions.
q_filter[phrase]StringSearch phrase.
q_filter[option]StringEither ‘all’, ‘question’, or ‘answer’. Search phrase on which part of the library.

Library Attachment

  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_attachments/<id> to GET single library attachment with database ID id.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_questions/<id>/attachments to GET all attachments belong to question with database ID id.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_area_archives/<id> to GET single library inlined area file archive image with database ID id.
  • Use HTTP GET with endpoint: https://<cention api domain>/s/<workspace>/capi/json/c3_library_questions/<id>/embedded_archives to GET all inlined area file archived images belong to question with database ID id.
  • Sample HTTP request body data format single attachment:
{
  "data": {
    "id": "1270",
    "type": "c3_library_attachments",
    "attributes": {
      "attachment": {
        "c3_id": 1270,
        "content_type": "text\/plain",
        "name": "tst1_1.txt",
        "content": "QXBwbGUgUGVuIFBpbmVhcHBsZSBQZW4="
      },
      "c3_id": 1270
    }
  },
  "links": {
    "self": {
      "href": "https://test.example.com/capi/json/c3_library_attachments/1270"
    }
  }
}

Data.attributes

FieldTypeDescription
content_typeStringFile type RFC2616
nameStringAttachment file name.
contentStringBase64 encoded attachment content.

Query parameters

FieldTypeDescription
without_contentBooleanFile content will not be returned when true.

References:

  1. JSONAPI specification.

Cention Export JSONAPI:

  • To use Cention Contact Center export API, a JSON Web Token (JWT) with ‘Access to export API’ claim attached is needed.
  • To create JWT go to Cention server → Administration tab → API → Access Tokens.
  • Check (tick) ‘’Access to export API’ from Others.
  • Make sure to fill up the Key field else Save button will not be activated.
  • Screenshot: 

The API follows JSONAPI specification: http://jsonapi.org/ . Following is some of the specification that must follow:


Trigger Export Generation

  • Use HTTP POST with endpoint: https:///s//capi/json/c3_trigger_exports to trigger a preset export. If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com then the endpoint would be: https://api.cention.com/s/demo/capi/json/c3_trigger_exports
  • Sample HTTP POST request body data format for trigger export:
  • Sample HTTP POST response data format for trigger export (include id field):

Data.relationships

FieldTypeDescription
exportArray of ObjectJSONAPI formatted object which represent the preset-ed export to be triggered.

Data.relationships.export

FieldTypeDescription
dataArray of ObjectJSONAPI formatted object which represent the preset-ed export to be triggered.

Data.relationships.export.data

FieldTypeDescription
typeStringExport type.
idStringExport ID from Cention application.

Data.attributes

FieldTypeDescription
c3_idIntegerGenerated export content’s database ID.
use_closure_dateBooleanIf true the generated content base on errand’s closure date instead of arrival date.
errand_from_dateStringIf set export will search errand from this date, format “2019/01/01”.
errand_to_dateStringIf set export will search errand until this date, format “2019/01/01”.
contentArray of ObjectThe content of generated data of the export.

Data.attributes.content

FieldTypeDescription
errand_idStringErrand identification number.
from_addressStringErrand from address.
to_addressStringErrand to address.
subjectStringErrand subject.
questionStringErrand question message.
answerStringErrand answer message.
errand_notesStringErrand note message.
timestamp_arrivedStringErrand arrival time.
timestamp_openedStringErrand open time.
timestamp_answeredStringErrand answer time.
timestamp_closedStringErrand closing time.
agent_idIntegerErrand assigned agent id.
agent_nameStringErrand assigned agent name.
area_idIntegerErrand container area id.
area_nameStringErrand container area name.
tag_namesStringErrand tags name.
client_idIntegerErrand sender id.
priorityStringErrand priority level.
satisfaction_meter_answer_1IntegerErrand feedback level 1.
satisfaction_meter_answer_2IntegerErrand feedback level 2.
satisfaction_meter_answer_3IntegerErrand feedback level 3.
satisfaction_meter_answer_4IntegerErrand feedback level 4.
satisfaction_meter_answer_5IntegerErrand feedback level 5.
channelStringErrand source name.
area_external_idStringExternal id for Area.

References:

  1. JSONAPI specification.

Cention Contact Centre – Standard Chat Advanced Functions Manual

WhenUpdate
2013-01-24Create initial version for document
2014-05-14Add new section about starting chat
2014-05-24Extend section about status with information about JSONP
2015-02-03Extend section about status with information about status 4
2016-02-23Update document for version 4.1
2016-10-13Update document for version 4.3 – Update for API URL (Chat URL Name)

1 Introduction

The Cention Standard Chat is a pre-built chat client that can be used with Cention Contact Centre to offer chat on your web site. This chat client is used instead of building your own client by following the Cention Contact Centre Chat Developers Manual. This manual describes advanced functions found in the standard chat that. You are in not in any way required to make use any of these functions to use the Cention Standard Chat. These advanced functions have been made available to make it possible to further integrate your web site with the Cention Standard Chat.

2 Get status

The chat client has three different statuses. Either it is open and agents are available, closed because no agents are available or closed because the chat client’s opening hours at the current time of the request says the chat as closed.

It is possible to find out what the current status with a web service. The web service is invoked is by performing a HTTP GET request to the right URL.

The corresponding Cention Chat Area Chat URL Name must be configured. This value will be referred to as {ChatURLName} in the rest of this document.

2.1 URL

https://api.cention.com/s/demo/external/{ChatURLName}/chat/-/status

2.1.1 Example URL

https://api.cention.com/s/demo/external/marketing/chat/-/status

The web service will return a JSON object with information about the chat area status.

2.1.2 Example return value

{
    status: 1,
    message: "Chat is open with available agents"
}

It is possible to have the status web service return JSONP instead of plain JSON. To that invoke the the following URL.

2.2 URL (JSONP)

https://api.cention.com/s/demo/external/{ChatURLName}/chat/-/status/jsonp/mycallback

2.2.1 Example URL

https://api.cention.com/s/demo/external/marketing/chat/-/status/jsonp/mycallback

2.2.2 Example return value

mycallback({ status: 1, message: "Chat is open with available agents" });

2.3 Available statuses

StatusMessage
1Chat is open with available agents
2Chat is open but no agents are available
3Chat is closed
4Chat is open but queue is full

3 Note about queue

If chat in your Cention system is configured to put new chat requests in a queue this web service will never return status 2.

This is because when new chat requests are not put in a queue it is not possible to start a new chat if there is no available agent which can be assigned the chat at the exact moment you try to start the chat.

When new chat requests are put in a queue to wait for an available agent it can never be closed because there are no available agents because you will always be allowed to start a chat if the current time is within the chat client’s defined opening hours because you will then wait in the queue until an agent has been assigned to you.

However there is one optional setting which allows you to configure the amount of chat requests that are allowed to wait in the queue at the same time. Status 4 will be returned when the limit is reached.

4 Start chat

When you visit the chat client in a web browser the first thing you have to do to start a chat with an agent is enter your name and email address and optionally if the chat has been configured that way also enter the first question.

By performing a HTTP POST request to the right URL with the right parameters it is possible to immediately start a chat and in that way bypass the first view were you enter your information. The information is then instead passed in as parameters in the HTTP POST request.

The HTTP POST request will return the HTML for the chat client’s chat view.

4.1 Parameters

All parameters are required. However some of them can be empty strings.

ParameterTypeEmptyDescription
nameStringNoName of the person starting the chat
emailStringNoEmail address to person starting the chat
questionStringYesFirst question from person starting the chat
dataStringYesExternal data that will be made available as the externalData field in Chat message object

4.2 URL

https://api.cention.com/s/demo/external/{ChatURLName}/chat/-/create

4.2.1 Example URL

https://api.cention.com/s/demo/external/marketing/chat/-/create

4.2.2 Example HTTP POST

POST /external/marketing/chat/-/create HTTP/1.0
Content-Type: application/x-www-form-urlencoded
Content-Length: 166

name=John%20Doe&email=john.doe%40example.com&question=Where%20is%20your%20office%20located%3F&data=%3Cstrong%3EThis%20is%20an%20important%20customer%21%3C%2Fstrong%3E

Cention Contact Center – Standard Chat Design Manual

WhenUpdate
2015-08-27Add new section about close button.
2016-10-17Update for 4.3. Document the seven different views.

1 Introduction

The Cention standard chat is a chat client for the Chat module in Cention Contact Center. The Cention standard chat is hosted by Cention on Cention’s servers and you will be provided with a link to your installation of the standard chat that you can put on your web site to enable your customers to engage in live chats with you.

This document describes how to customise the look and feel of the standard chat.

2 Views

The Cention standard chat has seven different views. These views have been provided to you with this documentation as seven HTML template files. By opening these files in a web browser you are able to see how these views will look (sans CSS). Unfortunately chatting and clicking any buttons will not work in the files that has been provided to you. For these things to work the files needs to be installed in the Cention standard chat on Cention’s servers.

The templates are:

NoFileDescription
1StartView.htmlForm for starting a new chat
2NoAgentsView.htmlShown when no agents are available for chat
3ClosedView.htmlPage shown when outside of chat opening hours
4EmailView.htmlForm for client to send email
5AfterEmailView.htmlShown after customers clicked the send button in EmailView.html
6ChatView.htmlThis is where chat takes place
7AfterCloseChatView.htmlShown when client closes the chat

Note on required and optional fields

Each view has required and optional fields. The required fields must be included in your views as instructed by this documentation otherwise the Cention standard chat will not work after your customizations have been installed.

Unless otherwise stated required and optional fields have names that must be present within the id attribute of the HTML tags. The HTML tags must be either <input> or <textarea> and if the tag is <input> the attribute type must be equal to text.

The following are examples of required and optional HTML tags.

2.1 StartView.html

The start view is the view that will be displayed to the customer if there are agents available for chat within Cention Contact Center. This view is the view the customer will see when he/he will be allowed to start a chat with one of the available agents.

This view has four required fields and one optional field. The required fields are StartViewNameStartViewEmailAddressStartViewAddressError and StartViewStartButton and the optional field is StartViewQuestion.

2.1.1 Field StartViewName

In this field the customer should enter his/her name. This field is required and must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to StartViewName.

2.1.2 Field StartViewEmailAddress

In this field the customer should enter his/her email address. It is used by Cention Contact Centre to link the chat session to other communication from the customer. This field is required and must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to StartViewEmailAddress.

2.1.3 Message StartViewAddressError

This HTML tag is hidden by default and only displayed if the customer enters an invalid email address. This HTML tag is required. It can be of any type but it must have the id attribute and the attribute must be equal to StartViewAddressError.

2.1.4 Field StartViewQuestion

This field allows the customer to enter his/her question before the chat session is started so that the agent which is assigned to the chat will know the customer’s question without having to ask first. Having this field present also allows the system to automatically search for an answer to the customer’s question that will be available to the agent as soon as the agent sees the chat. This field is optional. If it is present it must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to StartViewQuestion.

2.1.5 Button StartViewStartButton

This is the button that the customer should click to start a live chat session with one of your agents. This HTML tag is required. It can be of any type but it must have the id attribute and the attribute must be equal to StartViewStartButton.

2.2 NoAgentsView.html

The no agents view is displayed if there are no agents available for chat within Cention Contact Centre. You can use this view to show a button that will navigate the customer to the EmailView.html which allow the customer to send an email instead.

This view has one optional button. The optional button is NoAgentsViewGoToEmailButton.

2.3 ClosedView.html

The closed view is displayed if the client is opened outside of the configured opening hours. You can use this view to show a button that will navigate the customer to the EmailView.html which allow the customer to send an email instead.

This view has one optional button. The optional button is ClosedViewGoToEmailButton.

2.3.1 Button NoAgentsViewGoToEmailButton, ClosedViewGoToEmailButton

These buttons will navigate the customer to the EmailView.html which will allow the customer to send an email to you. Both are optional.

2.4 EmailView.html

This view allows the customer to send an email to you. The customer can have this choice if you so require if there are no agents available for chat. The email view has five required fields/buttons. Those are EmailViewNameEmailViewAddressEmailViewAddressErrorEmailViewQuestion and EmailViewSendButton.

2.4.1 Field EmailViewName

In this field the customer should enter his/her name. This field is required and must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to EmailViewName.

2.4.2 Field EmailViewAddress

In this field the customer should enter his/her email address. This field is required and must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to EmailViewAddress.

2.4.3 Message EmailViewAddressError

This HTML tag is hidden by default and only displayed if the customer enters an invalid email address. This HTML tag is required. It can be of any type but it must have the id attribute and the attribute must be equal to EmailViewAddressError.

2.4.4 Field EmailViewQuestion

In this field the customer should enter his/her question. This field is required. It must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to EmailViewQuestion.

2.4.5 Button EmailViewSendButton

This is the button that the customer should click to send a new email to you with the information he/she has entered. This HTML tag is required. It can by of any type but it must have the id attribute and the attribute must be equal to EmailViewSendButton.

2.5 AfterEmailView.html

This view is displayed after the customer has clicked the send button in the in the EmailView.html. It can tell the customer to close the window. This view has no required or optional fields.

2.6 ChatView.html

The chat view is the main view for the chat. It is in this view that chat between the agent and the customer takes place.

These are the fields/buttons in this view:

FieldRequiredDescription
ChatViewMessageListYesShows the chat messages
ChatViewQuestionYesInput for new chat message
ChatViewSendButtonYesButton that sends the new chat message
ChatViewAgentNameNoThe assigned agent name
ChatViewPrintButtonNoLink for printing the chat session
ChatViewSaveButtonNoLink for saving the chat session
ChatViewCloseButtonNoButton for ending the chat
ChatQueueNoShows the client chat queue number, if chat queue feature is used.

2.6.1 List ChatViewMessageList

This HTML tag will contain the list of messages that are sent between the agent and the customer. The tag can be of any type except <input><textarea><select> or any other type of form element.

When a new message is appended to the list it will be appended using the HTML displayed below.

There are five templates values in the HTML. The templates values are [CLASS][TIME][NAME][MESSAGE] and [TICKS]. The template value [CLASS] will be replaced with either client-reply or agent-reply, depending on who sent the message. The template value [TIME] will be replaced by the time the message was sent. The template value [NAME] will be replaced by the name of the person who sent the message. It could be either the customer’s name, agent’s name, or “System”. The template value [MESSAGE] will be replaced by the message the customer or the agent sent. For the message that the customer send the template value [TICKS] will be replaced with a two-ticks indicator for indicating the status of the message (✓✓). The first tick indicates whether the message is received by the server, and the second tick indicates whether the message has been sent to the agent. The tick changes its color from light gray (css color name: lightgray) to green (css color name: green) to indicate a positive response.

2.6.1.1 Custom message template

It is possible to specify your own HTML for messages if the default HTML does not suit your needs. To do this you need to assign your HTML to a global JavaScript variable called CustomMessageTemplate inside the chat view. An example of how to do this you can see below.

2.6.1.2 Custom message template values

When the client uses your custom message template it puts the values in the right place depending on where you put the template values. There are five template values that the custom message template can contain.

  • {0} is replaced by the time the message was sent.
  • {1} is replaced by the name of whom sent the message.
  • {2} is replaced by the body of the message.
  • {3} is replaced by either client-reply or agent-reply depending on who sent the message.
  • {4} is replaced by the two-ticks client message status indicator.
2.6.1.2.1 Custom client name

When the client sends a message the default message header will read (11:34) Carl Swordstone. In this case the client would have entered Carl Swordstone as his/her name before starting the chat.

If instead you would like something other then the name entered by the client displayed in the message header you can specify a custom client name. To do this you assign a global JavaScript variable called CustomClientName inside the chat view with what you would like to display instead of the name entered. An example of how to do this you can see below.

2.6.2 Field ChatViewQuestion

In this field the customer should enter his/her question. This field is required. It must be either <input> or <textarea>. The HTML tag must have the id attribute and the attribute must be equal to ChatViewQuestion.

2.6.3 Button ChatViewSendButton

This is the button the customer should click to the send a new message to the agent. This button is required. It can be of any type but it must have the id attribute and the attribute must be equal to ChatViewSendButton.

2.6.4 Message ChatViewAgentName

This HTML tag will contain the name of the agent the customer has been connected to. This HTML tag is optional. It can be of any type but it must have the id attribute and the attribute must be equal to ChatViewAgentName.

2.6.5 Button ChatViewPrintButton

This button allows the customer to print the ongoing or finished chat session at any time during the chat session. This button is optional. It can be of any type but it must have the id attribute and the attribute must be equal to ChatViewPrintButton.

2.6.6 Button ChatViewSaveButton

This button allows the customer to save the ongoing or finished chat session at any time during the chat session. This button is optional. It can be of any type but it must have the id attribute and the attribute must be equal to ChatViewSaveButton.

2.6.7 Button ChatViewCloseButton

This button allows the customer to close the current ongoing chat. It can be of any type but it must have the id attribute and the attribute must be equal to ChatViewCloseButton.

2.6.8 Message ChatQueue

If the chat queue feature is used, this HTML tag will contain the client chat queue number. This HTML tag is optional. It can be of any type but it must have the id attribute and the attribute must be equal to ChatQueue.

2.7 AfterCloseChatView.html

This view is displayed after the client closes the chat. For example the view be used to tell the customer to close the window.

This view has no required or optional fields.

3 Translation

In addition to the text in the view files, there are also text that are generated server-side during the chat. You can provide your own translation to these text by providing the file templates/translation.js.

4 Putting it all together

Once you have finished your customizations and sent those to the developers at Cention then the Cention developers will install this in your standard chat that has been provided with your installation of Cention Contact Center.

The view files will be converted into template files that the Cention standard chat understands and can use. Simply put the header and footer in the view files – everything between HEADER_BEGINHEADER_END and FOOTER_BEGINFOOTER_END – will be taken out and placed in their own files. When customizing the view files it can be a good idea to think about this to make this process easier.

In the default standard chat view files provided to you the header and footer would be what you can see below.

4.1 Standard chat header

5 Questions

If you have any questions regarding the customizations process feel free to ask your excellent support team at which you can reach by emailing support@cention.se.

Cention Contact Center – Cention Chat API 5.1.0

WhenUpdate
2016-01-26Create initial version of document.
2016-10-11Updated for 4.3
2017-06-06Updated for 4.4

1 Introduction

The purpose of this document is to describe the Cention Chat API which you can use to build your own chat client for Cention Contact Center. You should have received this document together with a fully working example. If you have not received this please contact Cention Support by emailing support@cention.se to receive the full documentation with examples. Please note that the provided example does not work when opened as a file directly from your hard disk. It must be put in a server and served through a web server in order to work correctly.

Among the files in the package you’ve received you will find a file named CentionChatAPI.js. This file is meant to be included in your web site so that you can use the functionality it provides to build your own chat client for your web site that can start chats with your agents that are working in Cention Contact Center. CentionChatAPI.js contains a JavaScript library that handles all the communication with the Cention chat server. A variable called FOR_THIRD_PARTY_USE defined on top of the CentionChatAPI.js needs to be set to true in order for this it to work properly with your web site.

CentionChatAPI.js has two dependencies which are the Socket.IO Client library, and the sockwrap.js library. In order for the Cention Chat API to work you must also include the Socket.IO Client library in your web site. There are multiple ways to do this. One way is to include the Socket.IO Client JavaScript file from the Socket.IO CDN with the following code.

<script src="https://cdn.socket.io/socket.io-1.4.8.js"></script>

For more information please see http://socket.io/download/.

A copy of sockwrap.js is available in at chat/sockwrap.js, and you can serve it from your web site.

In order for your server to be allowed to connect to your Cention Contact Center system using the Cention Chat API you must first provide Cention with the name of the domains where your connections will come from. Provide this to Cention by emailing support@cention.se with the details.

2 Version compatibility

The API as described in this document and the corresponding example code is designed to work with Cention Contact Center version 4.4.

3 Cention Chat API

3.1 Initialization

This is the first step towards the integration of Cention Chat into your system. Create an instance of of the Cention Chat API object and initialize the mandatory field baseURL. Also identify the Cention Contact Center area id that we are going to connect to.

FieldTypeDescription
baseURLStringThe base URL for the Cention Contact Center in https://<cention api domain>/s/<workspace> format

3.1.1 Example

If the name of your Cention workspace is “demo” and the cention api domain is api.cention.com

var CentionAreaId = 2;
var CentionChat = _CentionChat();
CentionChat.baseURL = 'https://api.cention.com/s/demo';

3.1.2 Internationalization

Messages sent to the client may come from the system. You might want to intercept these messages in order to translate it, for example:

var translation = {
    "Agent(s) removed: {AGENT_NAMES}": "Agent(s) removed: {AGENT_NAMES}",
    "Agent(s) added: {AGENT_NAMES}": "Agent(s) added: {AGENT_NAMES}",
    "{AGENT_NAME} has left the chat.": "{AGENT_NAME} has left the chat.",
    "Client ended the chat.": "Client ended the chat.",
    "{NAME} ended the chat.": "{NAME} ended the chat.",
    "{NAME} attached a file.": "{NAME} attached a file."
};
CentionChat.I = function(text) {
    return translation[text];
};

For the full list of translatable messages please refer to the example file.

3.2 CentionChat.registerAction()

Description: Register an action handler in the form of a callback function that will be invoked when the specified event occurs.

NameType
actionString
handlerFunction

The function requires two parameters. The first parameter is the name of the event. The second parameter is the action callback that should be invoked when the event specified in the first parameter occurs. When an event occurs data may be passed to the action callback as its sole argument. The following events are available.

3.2.1 Chat events

Event idDescriptionArgument
agent previewAgent is typingAgent preview object
agent unavailableThere were no agent available for chatNone
chat closedChat is already closedNone
chat messageNew message receivedChat message object
connectConnection was succesfulNone
connect_errorConnection failedError object
finish chat sessionChat session is closed by agent or expiredNone
message ackedMessage was sent to the agent successfullyMessage acked object
message sentMessage was sent to the server successfullyMessage sent object
queueQueue number changeQueue number
queue fullQueue is fullNone

3.2.1.1 Chat message object

FieldTypeDescription
agentStringName of the agent currently assigned to the chat. Empty if no agent is assigned yet.
chatArrayList of message objects that the client has not seen. In rare cases it may contain messages that are already received.
clientStringName of the client as recorded in the Cention Contact Center.

3.2.1.2 Message object

This contains a message that should be displayed to the client. It may be a message that was already displayed.

FieldTypeDescription
idNumberThe Cention Contact Center message id.
senderStringOne of CLIENTAGENT or SYSTEM.
sentNumberThe unix timestamp of when the message was received.
sentHumanStringHuman readable timestamp (HH:MM) of when the message was received, expressed in the configured timezone for the chat area.
textStringThe chat message.
umidStringThe unsent message id. For messages originating from the client, this the same id that was generated at the client side when the message was sent. This string can be empty on the rare occasion that the Cention chat server is restarted.

3.2.1.3 Message acked object

This can be used to tell the client that the agent has seen the message that they sent.

FieldTypeDescription
idsArrayList of message ids that has been successfully sent to the agent.

3.2.2 Example

CentionChat.registerAction('message acked', function(msg) {
    console.log("messages received by agent", msg.ids);
});

3.2.2.1 Message sent object

FieldTypeDescription
idStringNormally this will contain the Cention Contact Center message id. In rare cases it will contain the string ‘already-seen-’ + umid.
umidStringThe unsent message id (generated client side).
sentNumberThe unix timestamp of when the message was received.
sentHumanStringThe timestamp (HH:MM) of when the message was received, expressed in the configured timezone for the chat area.

3.2.2.2 Agent preview object

FieldTypeDescription
messageLenNumberThe length of the message that the agent is typing

3.2.3 Example

CentionChat.registerAction("chat message", function(data) {
    console.log("Chat message received", data);
});

3.3 CentionChat.connect()

Description: Connect the web browser to Cention Contact Center and start a new chat.

NameType
parametersObject

The function requires one parameter in the form of an object with required key-value pairs that must be set within the object.

NameTypeDescription
areaNumberCention Contact Center area id
emailStringClient’s email address.
messageStringClient’s initial question.
nameStringClient’s name.

3.3.1 Example

CentionChat.connect({
    area:    1,
    email:   "john.smith@gmail.com",
    message: "Hello! Where can I find Cention's office?"
    name:    "John Smith",
});

3.4 CentionChat.resetChat()

Description: Reset the internal chat state variables. When the chat ends, call this function before starting a new one.

3.5 CentionChat.tryResume()

Description: Connect the web browser to Cention Contact Center and try resume an ongoing chat that was previously associated with the current cookie session. This can be used to continue a chat session after the client navigates to another page of your website.

NameType
handlerFunction

On a successful resume, the handler is passed an msg object that contains the client and chat session details:

NameType
areaIdNumber
clientNameString
sessionIdNumber
sessionSecretString

If the resume was not successfull the msg object contains an error field that describes why the resume failed.

3.5.1 Example

CentionChat.tryResume(function(msg) {
    if (msg.error) {
        // resume failed, show the chat form instead...
        console.log("resume failed", msg.error);
        $('StartView').show();
        return;
    }
    $('ChatView').show();
});

3.6 CentionChat.disconnect()

Description: Disconnect the ongoing chat.

This function will do nothing if you haven’t successfully connected using the CentionChat.connect() function.

3.7 CentionChat.message()

Description: Queue a message to be sent to the agent which the chat is connected to. The message remains in the queue until it is successfully sent, at which point the message sent event is generated.

The function returns an Unsent message object which allows you to immediately add the message to the client chat message list and display it as sending and mark it as sent after its corresponding message sent event is received.

NameType
messageString

This function will do nothing if you haven’t successfully connected using the CentionChat.connect() function.

3.7.1 Example

var sending = CentionChat.message("Hello! Are you there?");

The return value is an Unsent message object

3.7.2 Unsent message object

FieldTypeDescription
idStringA unique message id, generated client-side.
messageStringThe message to be sent.

3.8 CentionChat.attachFile()

Description: This function allows sending files as attachments to the agent. It would upload the selected file to the server, and queue a message to the agent that client has sent a file (similar to CentionChat.message() API).

The function takes 3 parameters: Name Type —- —- file Object cbOnDone callback function

3.8.1 Example

var fileInput = document.getElementById('ChatViewSendFileButton');
if(fileInput.files.length > 0){
    for (var i = 0; i < fileInput.files.length; i++) {
        CentionChat.attachFile(
        fileInput.files[i],     /*the file object*/
        function(um){       /*the callback function cbOnDone*/
            // value 'um' is an [Unsent message object],
            // handle similar to CentionChat.message() API above
        });
    }
}

3.8.2 Uploaded file object

FieldTypeDescription
nameStringthe client name
fileObjectThe file object that has been uploaded

3.9 CentionChat.preview()

Description: Send preview of the message the client is typing.

NameType
previewString

The purpose of this function is to notify the agent that the client is typing a message. The agent can within Cention Contact Center configure the system to either show the actual message being typed or only show that the client is typing something. This function will do nothing if you haven’t successfully connected using the CentionChat.connect() function.

3.9.1 Example

CentionChat.preview("Hello! Are y");

3.10 CentionChat.canChat(handler, area)

Description: Find out if it is possible to start a chat.

NameType
handlerFunction
areaNumber

The first parameter is the callback function that is called once the call to the server returns. The callback is passed an object that represent whether it is possible to start a chat for the given Cention Chat Area.

The following object is passed to the handler:

FieldTypeDescription
chatOpenBooleanWhether the chat is open
agentsAvailableNumberThe number of agents available
featureObjectThe related chat features that was setup from cention contact center (Features available can be referred in the example)
resumableBooleanWhether the chat can be resumed
errorStringAn error message

The presence of a non-empty error message means that it is not possible to start a chat.

Working hours can be configured in Cention Contact Center. As an example your chat for the specific area might only be open between 08:00 and 17:00. Use this function to determine if the chat for the specific area is open and whether there are agents available. If the chat isn’t open you can display a message saying that the chat is only open between 08:00 and 17:00. Or if the chat is open but there are no agents available you can display a message saying all of your agents are busy at the moment but please try again later.

3.10.1 Example

CentionChat.canChat(function(o) {
    if (o.error) {
        // It is not possible to start a chat
        return;
    }

    if (!o.chatOpen) {
        // Chat is not open (outside of working hours)
        return;
    }

    if (o.agentsAvailable <= 0) {
        // No agents available
        return
    }

    if(o.resumable) {
        resume: true,
            area: -1,
            callback: function(msg) {
                if(msg.sessionId) {
                    // Show current chat
                }else {
                    // Show chat start view
                }
            }
    }

    if(o.feature) {
        //Features included to be used if necessary
        var sendAttacmentAllowed = o.feature["chat.attachment"];
        var externalSourcePage = o.feature["chat.external-source-page"];
        var maxAttachmentSize = o.feature["chat.max-attachment-size"];
        var maxImageSize = o.feature["chat.max-image-size"];
    }

    // It is possible to start a chat
}, CentionAreaId);

3.11 CentionChat.close()

Description: CentionChat.close() function closes chat connection between user and agent.

3.12 Save Chat History

Description: Register event handler for when the “Save a copy” link is clicked. User can save and download the chat history by this event.

3.12.1 Example

$('#CentionChatSaveButton').on('click', function() {
    var url = CentionChat.baseURL
        + "/socket/external.api/savehistory?area="+ CentionAreaId
        + "&secret=" + CentionChat.sessionSecret
        ;
    window.open(url, '_self');
});

Description: Register event handler for when the print button is clicked. User can print the chat history by clicking print button. The popup window will appear with save button to print the chat history.

3.13.1 Example

$('#CentionChatPrintButton').on('click', function() {
    var url = CentionChat.baseURL
        + "/socket/external.api/printhistory?area=" + CentionAreaId
        +"&secret=" + CentionChat.sessionSecret
        ;
    var popup = window.open(url, 'window', 'width=640,height=480,scrollbars=yes,status=no');
    if( window.focus ) {
        popup.focus();
    }
});

3.14 Close Chat

Description: Register event handler for when the “Finish chat” link is clicked.

3.14.1 Example

$('#CentionChatFinishButton').on('click', function() {
    // CentionChat.close() function close chat connection between user and agent.
    CentionChat.close();
});

Cention Contact Center – Cention Chat Widget 5.2.0

1 Introduction

This document describes embedding of Cention Chat Widget inside your webpages so that users of the website can chat with your agents. Conversations started from one page are resumed when the user navigate to other pages of your website, provided that the other pages also load the same chat widget.

1.1 Requirements

  • Jquery library is needed to run the chat widget.
  • The hostnames and ports combination of the websites that will serve the widget must be added to the Cross Origin Resource Control (CORS) whitelist in your Cention Contact Center system configuration.

You can embed the chat widget anywhere on your page by inserting the html code similar to the ones in the example below.

1.2 Chat Widget Configuration Examples

The following examples use https://api.cention.com/s/demo as the url where Cention Contact Center is hosted, and connects the chat to Cention area 1. You will have to replace them with the appropriate values for the example to work with your Cention Contact Center.

1.2.1 No customization

At the minimum the following must be specified when loading the widget:

Field Description
areaId The Cention area id (number) where the chat should be started in, or a list of area id (array of objects) for example, areaId: [{id: 1, name: Area 1},{id: 2, name: Area 2}]
CentionBaseURL Global javascript variable. This is the url where your Cention Contact Center is hosted.
   

1.2.1.1 Example – no customization

<script type="text/javascript" src="https://api.cention.com/s/demo/cention/chat/js/jquery.min.js"></script>
<script type="text/javascript">var CentionBaseURL = "https://api.cention.com/s/demo";</script>
<script src="https://api.cention.com/s/demo/cention/chat/js/widget.js" type="text/javascript"></script>
<div id="cention-chat-container"></div>
<script type="text/javascript">
if(typeof CentionChat !== "undefined") {
  CentionChat("cention-chat-container", { areaId: 1 });
}
</script>

1.2.2 Full customization

Many aspects of the chat widget can be customized. The following example list all the customizable settings at their default values.