Cention
API Documentation
Cention Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Cention API

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://<cention api domain>/s/<workspace>/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 <token>. For example Authorization: Bearer eyJhbGci...<snip>...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",
		"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)

Field Type Description
message_id String String to uniquely identify the mail.
name String Writer name.
from String Writer address (email address if email/web form channel)
subject String Subject of the mail.
body String Plain text body.
html_body String Rich text body (supported for email/web form channel)
attachments Array Attachment content of the errand.

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

Field Type Description
content_type String File type RFC2616
name String Attachment file name.
content String Base64 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)

Field Type Description
subject String Subject of the answered mail.
body String Plain text answer body.
html_body String Rich text answer body (supported for email/web form channel)
user_type String User type eg: “cention”, “solidus” and “clearinteract”
user_id String Database 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)

Field Type Description
elementname String Element name of the whatsapp template.
namespace String Namespace given by whatsapp.
params JSON Json array
"watemplate":{
  "elementname":"<template element name>",
  "namespace": "<template 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
Field Type Mandatory Description
integrationName String Yes name of the integration
referenceId String No Id used to identify a call by external system
deviceId Integer Yes Device id used by agent. Used as part of key to identify agent in Cention
extensionId Integer Yes Extension id used by agent. Used as part of key to identify agent in Cention
link String No URL to stored voice call in external system
destNumber String Yes The number that was used to reach the external system. The called party number. Must be in MSISDN format.
pagingNumber String No The number to use when calling Aventa’s call AP for outbound call
pagingName String No The number associated with paging number
queueName String Yes Name of the aventa queue where the voice call originated from
queueNumber String Yes ID of the call in aventa’s queue
extraData Struct No Structure to store extra information to be stored in errand

data.type.attributes.extraData (object)

Field Type Mandatory Description
comment String No Additional comments to be stored as errand’s internal comment
callReason String No Description for the reason the call was made
appointmentTimestamp String No unix 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://<cention api domain>/s/<workspace>/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)

Field Type Description
subject String Subject for answer
body String Plain text answer body
html_body String Rich text answer body (supported for email/web form channel)
user_type String User type: “cention”, “solidus” or “clearinteract”
user_id String Identifier 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://<cention api domain>/s/<workspace>/capi/json/c3_end_obcall

Sample HTTP request body:

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

data.attributes(object)

Field Type Mandatory Description
integrationName String Yes Name of the integration used for the outbound call
referenceId String No Id used to identify a call by external system
dialedNumber String No The dialed phone number for outbound call
deviceId Integer Yes Device id used by agent. Used as part of key to identify agent in Cention
extensionId Integer Yes Extension 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": "<div style=\"font-size:;font-family:;\"><div>sadadad<img src=\"cid:12\" \/><img alt=\"\" src=\"cid:attachment_788\" \/><\/div>\n\n<br \/><br \/><div>\u00a0<\/div>\r\n<a href=\"http:\/\/localhost\/errands\/satisfaction\/meter\/-\/answer\/4d6a49314e673d3d\/1b7f046991d401785264fc4d35ca3db6\" style=\"font-family:Verdana; font-size:10pt; color:black; font-style:normal;\">optionONE<\/a><br \/><a href=\"http:\/\/localhost\/errands\/satisfaction\/meter\/-\/answer\/4d6a4931AAA73d3d\/73d05e8f6ec0ca1AAAa6608b78debd9\" style=\"font-family:Verdana; font-size:10pt; color:black; font-style:normal;\">optionTWO<\/a><br \/><br \/>\n--------- Cention Contact Center - Original message ---------<br \/>\nErrand: #2256-1<br \/>\nFrom: Sany Liew (david.liew@test.se)<br \/>\nSent: 2017\/01\/22 16:53<br \/>\nTo: test-services-area<br \/>\nSubject: Creating test errand via API<br \/>\nQuestion: <br \/>\n<br \/>\nTest message body at Sun, 22 Jan 2017 16:53:04 +0800<br \/>\n<br \/>--------- 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 ID Description
1 Answer errand.

included (array of objects)

Object type Type Description
c3_answer_errands Object Detail of the answered errand.
c3_response_attachments Object Attachment that attached to the answered errand.
c3_area_archives Object Image that is embedded inside the HTML body of the errand.

c3_answer_errands attributes.answer.response

Field Type Description
subject String Errand’s subject.
body Object Errand’s plain text.
html_body Object Errand’s rich text.
to Array The errand intended target.

c3_answer_errands attributes.answer.response.to

Field Type Description
email_address String Email address of the errand intended target.
name String Name of the intended target.

c3_answer_errands attributes.service

Field Type Description
name String Errand’s service/channel name.
type Integer Identifier of the errand’s service/channel.

c3_response_attachments c3_area_archives

Field Type Description
links.self.href or links.self String HTTP 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

Field Type Description
content_type String File type RFC2616
name String Attachment file name.
content String Base64 encoded attachment content.

References:

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