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 apid.cention.com then the endpoint would be: https://apid.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.