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://<cention api domain>/s/<workspace>/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.