Chat API
Working with Puzzel Chat API
Puzzel Chat API is a tool designed for integrating communication into your applications. It supports a range of features including message handling, connection management, and conversation tracking. Additionally, it offers real-time data processing, allocation, queues and the use of Puzzel time module. With clear endpoints, the API is built to allow customers to create integrations to the chat channel in Puzzel Contact centre, allowing them to implement and manage chat functionalities inside their own application areas.
To see and interact with the API visit this Swagger page where it is possible to read the API, and the Swagger also includes a example client with illustrative code samples in different languages.
The Swagger can be found here: https://app-cdn.puzzel.com/public/chat-api-swagger/index.html
Using the sample test client
In the swagger link above Puzzel provide a reference implementation and a working sample test client that can be used to kick start development efforts. To use this in your Puzzel Contact Center chat you will need to have your solution id and your visual queue id ready. See Puzzel help for Puzzel Contact Center for where to find this information.
Creating a session
To communicate with the API you need to use a token. You obtain a token from the endpoint “connect/token” and you can see an example of this using the link above. A token is the holder of the session. Tokens follow an OICD standard and the response also contains a refresh token to refresh you token before expiry. The “expires_in” property returned from the connect/token call will give the time untill the token need to be refreshed. See OICD standard for details.
Requesting an agent
The chat client can check for opening hours and using the /api/queue/info/<id> call if needed
After this the client can call the method /api/conversation/<ID>/route/ to ask the contact center to find and assign an agent. The api expects partners to set their own chat conversation id.
After the route command it is possible to call the /api/allocation/requestStatus/{id} to get status on finding and agent for the conversation
Polling for messages
New messages should be polled at interval. For example every second and the endpoint /api/conversation is used for this. See Swagger for details
Sending messages
The chat support a rich content model with interactive elements, these can be sent from the server, the model is described below.
Rich Content Model
The rich content model defines the structure of the interactive elements that can be sent in chat messages. Below are the root properties and different types of rich content elements.
Root Properties
Property | Required/Optional | Description |
| type | REQUIRED | The type of rich content. Should be set to options. |
| name | OPTIONAL | A human-readable name for the message for easier tracking. |
| externalId | OPTIONAL | A unique ID for the rich content message. |
| bodyCss | REQUIRED | The CSS applied to the body container. |
| body | REQUIRED | An array of objects that the user can interact with. |
| afterResponse | OPTIONAL | Defines what happens to the UI after a user interaction. |
| responseMethod | OPTIONAL | Defines what should be sent after user interaction. |
| submitType | OPTIONAL | Defines if a response should be sent on a single selection or using a button. |
| testFlow | OPTIONAL | Used for end-to-end testing of bot flows. |
Rich Content Elements
Button
A button element that users can click.
Property | Required/Optional | Description |
| type | REQUIRED | Set to button. |
| id | REQUIRED | The ID of the button. |
| label | REQUIRED | The label displayed on the button. |
| value | REQUIRED | The value of the button. |
| icon | OPTIONAL | Adds an icon in front of the label. |
| group | OPTIONAL | Used for grouping buttons as radio buttons. |
| css | OPTIONAL | The CSS applied to the container. |
| sticky | OPTIONAL | Keeps the item active after the rich content is disabled. |
Symbol
A symbol element that works like a button (e.g., thumbs up or down).
Property | Required/Optional | Description |
| type | REQUIRED | Set to symbol. |
| id | REQUIRED | The ID of the symbol. |
| value | REQUIRED | The value of the symbol. |
| icon | REQUIRED | The icon of the symbol. |
| size | OPTIONAL | The size of the symbol. |
| group | OPTIONAL | Used for grouping symbols. |
| css | OPTIONAL | The CSS applied to the container. |
| sticky | OPTIONAL | Keeps the item active after the rich content is disabled. |
Checkbox
A checkbox element for multi-choice selections.
Property | Required/Optional | Description |
| type | REQUIRED | Set to checkbox. |
| id | REQUIRED | The ID of the checkbox. |
| label | REQUIRED | The label displayed next to the checkbox. |
| value | REQUIRED | The value of the checkbox. |
| group | REQUIRED | The group that the checkbox belongs to. |
| css | OPTIONAL | The CSS applied to the container. |
| sticky | OPTIONAL | Keeps the item active after the rich content is disabled. |
| attributes | OPTIONAL | Supported attributes like required. |
SubmitButton
A button to submit the form.
Property | Required/Optional | Description |
| type | REQUIRED | Set to submitButton. |
| label | REQUIRED | The label displayed on the button. |
| icon | OPTIONAL | Adds an icon in front of the label. |
| css | OPTIONAL | The CSS applied to the container. |
LinkButton
A button that opens a link.
Property | Required/Optional | Description |
| type | REQUIRED | Set to linkButton. |
| id | REQUIRED | The ID of the button. |
| label | REQUIRED | The label displayed on the button. |
| icon | OPTIONAL | Adds an icon in front of the label. |
| url | REQUIRED | The URL to open. |
| target | OPTIONAL | Defines where to open the link. |
| css | OPTIONAL | The CSS applied to the container. |
| sticky | OPTIONAL | Keeps the item active after the rich content is disabled. |
Input
A text input field.
Property | Required/Optional | Description |
| type | REQUIRED | Set to input. |
| id | REQUIRED | The ID of the input. |
| label | OPTIONAL | The label displayed next to the input. |
| value | OPTIONAL | The default value of the input. |
| css | OPTIONAL | The CSS applied to the container. |
| sticky | OPTIONAL | Keeps the item active after the rich content is disabled. |
| attributes | OPTIONAL | Supported attributes like required, placeholder. |
Text
A text element that supports markdown.
Property | Required/Optional | Description |
| type | REQUIRED | Set to text. |
| text | OPTIONAL | The displayed text. |
| afterResponseText | OPTIONAL | The text shown after user interaction. |
| css | OPTIONAL | The CSS applied to the container. |
Rich Content Examples
This section provides detailed examples of different rich content configurations.
Sticky Example
A simple example with two choices using flex for styling. AfterResponse is set to sticky so the user can reselect. Using responseMethod both to send both an optionsResponse and a chatMessage.
Example Payload:
{
"type": "options",
"name": "sticky, flex",
"externalId": "externalId1",
"afterResponse": "sticky",
"responseMethod": "both",
"bodyCss": {
"display": "flex",
"flexDirection": "column",
"alignItems": "center",
"gap": "4px"
},
"body": [
{
"type": "text",
"text": "sticky, flex"
},
{
"type": "button",
"label": "Choice 1",
"id": "id1",
"value": "value1"
},
{
"type": "button",
"label": "Choice 2",
"id": "id2",
"value": "value2"
}
]
}Thumbs Example
Two choices and a link button. When the user has made a choice, the buttons are disabled. The layout uses grid to place two thumb buttons next to each other on the right side. The thumb buttons are sticky and continue to work after the other options have been disabled.
Example Payload:
{
"type": "options",
"name": "grid, thumbs",
"externalId": "externalId2",
"bodyCss": {
"display": "grid",
"gridTemplateColumns": "2fr 1fr",
"gridAutoRows": "1fr",
"gridGap": "4px"
},
"body": [
{
"type": "text",
"text": "grid, thumbs",
"css": {
"gridColumn": "1 / span 2",
"justifySelf": "center"
}
},
{
"type": "button",
"label": "Choice 1",
"id": "id1",
"value": "value1",
"css": {
"gridColumn": "1 / span 2",
"justifySelf": "center"
}
},
{
"type": "button",
"label": "Choice 2",
"id": "id2",
"value": "value2",
"css": {
"gridColumn": "1 / span 2",
"justifySelf": "center"
}
},
{
"type": "linkButton",
"label": "link",
"url": "https://www.puzzel.com",
"id": "id4",
"value": "value2",
"css": {
"gridColumn": "1 / span 2",
"justifySelf": "center"
}
},
{
"type": "symbol",
"icon": "faThumbsUp",
"id": "id5",
"group": "yesNo",
"value": "yes",
"sticky": true,
"css": {
"gridColumn": "1",
"justifySelf": "right"
}
},
{
"type": "symbol",
"icon": "faThumbsDown",
"id": "id6",
"group": "yesNo",
"value": "no",
"sticky": true,
"css": {
"gridColumn": "2",
"justifySelf": "left"
}
}
]
}
Submit Example
An example using submitType multiChoice. A grid with three check boxes and a submit button, thumb buttons, a markdown link, and an after-response text. The thumb buttons have been resized using size.
Example Payload:
{
"type": "options",
"name": "submit example",
"externalId": "externalId3",
"submitType": "multiChoice",
"bodyCss": {
"display": "grid",
"gridTemplateColumns": "2fr 1fr 1fr",
"gridAutoRows": "auto",
"gridGap": "10px"
},
"body": [
{
"type": "text",
"text": "Submit example",
"css": {
"gridColumn": "1 / span 3",
"justifySelf": "center"
}
},
{
"type": "checkbox",
"label": "Stay hungry",
"id": "id1",
"value": "stayHungry",
"group": "checkboxGroup",
"css": {
"justifySelf": "start",
"gridColumn": "1 / span 3"
}
},
{
"type": "checkbox",
"label": "Built on trust",
"id": "id2",
"value": "builtOnTrust",
"group": "checkboxGroup",
"css": {
"justifySelf": "start",
"gridColumn": "1 / span 3"
}
},
{
"type": "checkbox",
"label": "Stronger together",
"id": "id3",
"value": "strongerTogether",
"group": "checkboxGroup",
"css": {
"justifySelf": "start",
"gridColumn": "1 / span 3"
}
},
{
"type": "submitButton",
"label": "Submit",
"css": {
"justifySelf": "center",
"gridColumn": "1 / span 3"
}
},
{
"type": "text",
"text": "",
"afterResponseText": "Thank you",
"css": {
"justifySelf": "center",
"gridColumn": "1 / span 3"
}
},
{
"type": "text",
"text": "[link](https://www.puzzel.com)",
"css": {
"gridColumn": "1",
"justifySelf": "start",
"alignSelf": "center"
}
},
{
"type": "symbol",
"icon": "faThumbsUp",
"id": "id4",
"group": "yesNo",
"value": "yes",
"size": "20px",
"sticky": true,
"css": {
"gridColumn": "2",
"justifySelf": "right",
"alignSelf": "center"
}
},
{
"type": "symbol",
"icon": "faThumbsDown",
"id": "id5",
"group": "yesNo",
"value": "no",
"size": "20px",
"sticky": true,
"css": {
"gridColumn": "3",
"justifySelf": "left",
"alignSelf": "center"
}
}
]
}
Form Example
A form example with multiple input fields, check boxes, and a submit button.
Example Payload:
{
"type": "options",
"name": "form example",
"externalId": "externalId3",
"submitType": "multiChoice",
"responseMethod": "both",
"bodyCss": {
"display": "grid",
"gridTemplateColumns": "1fr 1fr 1fr .5fr",
"gridAutoRows": "auto",
"gridGap": "10px"
},
"body": [
{
"type": "text",
"text": "Form example",
"css": {
"gridColumn": "1 / span 4",
"justifySelf": "center"
}
},
{
"type": "input",
"label": "name",
"id": "id1",
"value": "",
"css": {
"justifySelf": "center",
"gridColumn": "1 / span 4"
},
"attributes": {
"required": true,
"placeholder": "Enter your name",
"autoComplete": "given-name"
}
},
{
"type": "input",
"label": "lastName",
"id": "id2",
"value": "",
"css": {
"justifySelf": "center",
"gridColumn": "1 / span 4"
},
"attributes": {
"required": true,
"placeholder": "Enter your last name",
"autoComplete": "family-name"
}
},
{
"type": "input",
"label": "email",
"id": "id3",
"value": "",
"css": {
"justifySelf": "center",
"gridColumn": "1 / span 4"
},
"attributes": {
"required": true,
"placeholder": "Enter your email",
"autoComplete": "email"
}
},
{
"type": "checkbox",
"label": "Agree to terms",
"id": "id4",
"value": "test",
"group": "checkboxGroup",
"css": {
"alignSelf": "center",
"justifySelf": "center",
"gridColumn": "1 / span 2"
},
"attributes": {
"required": true
}
},
{
"type": "text",
"text": "[terms](https://www.puzzel.com)",
"css": {
"gridColumn": "3",
"justifySelf": "start",
"alignSelf": "center"
}
},
{
"type": "submitButton",
"label": "Submit",
"css": {
"justifySelf": "center",
"gridColumn": "1 / span 4"
}
},
{
"type": "symbol",
"icon": "faThumbsUp",
"id": "id5",
"group": "yesNo",
"value": "yes",
"size": "20px",
"sticky": true,
"css": {
"gridColumn": "3",
"justifySelf": "right",
"alignSelf": "center"
}
},
{
"type": "symbol",
"icon": "faThumbsDown",
"id": "id6",
"group": "yesNo",
"value": "no",
"size": "20px",
"sticky": true,
"css": {
"gridColumn": "4",
"justifySelf": "left",
"alignSelf": "center"
}
}
]
}