Role: Admin, Account Manager
First, if you haven't already, go ahead and set up an API connection in your Klaus account. You will only need the API token from that step to continue.
We can now help Klaus discover our conversations, which can then be reviewed in the app by you and your teammates. We'll need to make a POST request to https://pub.klausapp.com/v1/tickets & set the API token as a Bearer token in the Authorization header.
Here's a look at the entire payload:
{
"id": "string",
"subject": "string",
"description": "string",
"created": "string",
"updated": "string",
"assigneeEmail": "string",
"assigneeName": "string",
"ticketFields": [
{
"id": "string",
"label": "string",
"values": [
{
"label": "string",
"value": "string"
}
]
}
],
"comments": [
{
"authorEmail": "string",
"authorIsNotClient": true,
"authorName": "string",
"comment": "string",
"created": "string",
"id": "string",
"updated": "string"
}
]
}
Let's walk through its properties:
- id is a unique identifier, preferably the same as in your system (you can later update a conversation or a comment via this ID).
- subject, description and assigneeName are simple strings displayed to the user.
- created is a timestamp in the format yyyy-mm-ddThh:mm:ss
- updated is an optional field and can be provided later on to enhance the filtering capabilities in Klaus (the expected format is the same as it is for the created field).
- assigneeEmail has to match an internal user's e-mail on Klaus for the conversation itself to be reviewable; alternatively, a comment's authorEmail has to match an internal user's e-mail (then a specific comment can be reviewed).
- ticketFields are also optional and can be of great help when filtering for specific conversations.
- comments represents the replies under a conversation; you can send in Markdown or HTML in the reply's comment field. If you set authorIsNotClient to true, then the authorEmail will be added as an external user (same as if you would import users), so you could Connect or Invite them.
- Comments with authorIsNotClient are also shifted to the right side of the conversation flow for better readability.
Equipped with this new knowledge, let's put together an example conversation and send it to Klaus with curl.
Our example conversation:
{
"data": [
{
"id": "c4t-syst3m-335",
"subject": "My fish bowl looks fishy",
"description": "Hi, I just received my fish bowl. But it is fishless, which makes the situation quite fishy",
"created": "2020-04-16T11:24:51",
"updated": "2020-04-17T13:48:26",
"assigneeEmail": "jane@example.com",
"assigneeName": "Jane",
"ticketFields": [
{
"id": "channel",
"label": "Channel",
"values": [
{
"label": "Chat",
"value": "chat"
}
]
}
],
"comments": [
{
"authorEmail": "klaus@cat.design",
"authorIsNotClient": false,
"authorName": "Klaus",
"comment": "Hi, I just received my fish bowl. But it is fishless, which makes the situation quite fishy. Please get back to me ASAP on this.\n\nBest, Klaus",
"created": "2020-04-16T11:24:51",
"id": "c4t-syst3m-335-1",
},
{
"authorEmail": "robert@example.com",
"authorIsNotClient": true,
"authorName": "Robert",
"comment": "Hi, Klaus!\n\nI looked into your order and it seems you ordered our fishless fish bowl. I will loop in Jane who handles our orders to get this sorted out. We will get back to you shortly.\n\nBest, Robert",
"created": "2020-04-16T11:29:16",
"id": "c4t-syst3m-335-2",
},
{
"authorEmail": "klaus@cat.design",
"authorIsNotClient": false,
"authorName": "Klaus",
"comment": "Thank you Robert. If I would cover the difference in costs and ship back the fishless bowl, could you please send out the fishy fish bowl?",
"created": "2020-04-16T11:24:51",
"id": "c4t-syst3m-335-3",
},
{
"authorEmail": "jane@example.com",
"authorIsNotClient": true,
"authorName": "Jane",
"comment": "Hey Klaus, Jane here\n\nIt seems that our system had not marked the fishy fish bowl as out of stock and that is why you were able to pay for one. Sorry for this mistake, we will cover the shipping costs and send out a fishy bowl. Is the address still valid?\n\nBest, Jane",
"created": "2020-04-17T10:04:29",
"id": "c4t-syst3m-335-4",
},
{
"authorEmail": "klaus@cat.design",
"authorIsNotClient": false,
"authorName": "Klaus",
"comment": "That is wonderful news, Jane! Yes, feel free to use the same address. I\'ll be eagerly waiting\n-Klaus",
"created": "2020-04-17T12:09:43",
"id": "c4t-syst3m-335-5",
},
]
}
]
}
And when we insert that into our payload, we get our final request command:
curl 'https://pub.klausapp.com/v1/tickets' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <api_token>' \
--request POST \
--data '{ "data": [ { "id": "c4t-syst3m-335", "subject": "My fish bowl looks fishy", "description": "Hi, I just received my fish bowl. But it is fishless, which makes the situation quite fishy", "created": "2020-04-16T11:24:51", "updated": "2020-04-17T13:48:26", "assigneeEmail": "jane@example.com", "assigneeName": "Jane", "ticketFields": [ { "id": "channel", "label": "Channel", "values": [ { "label": "Chat", "value": "chat" } ] } ], "comments": [ { "authorEmail": "klaus@cat.design", "authorIsNotClient": false, "authorName": "Klaus", "comment": "Hi, I just received my fish bowl. But it is fishless, which makes the situation quite fishy. Please get back to me ASAP on this.\n\nBest, Klaus", "created": "2020-04-16T11:24:51", "id": "c4t-syst3m-335-1" }, { "authorEmail": "robert@example.com", "authorIsNotClient": true, "authorName": "Robert", "comment": "Hi, Klaus!\n\nI looked into your order and it seems you ordered our fishless fish bowl. I will loop in Jane who handles our orders to get this sorted out. We will get back to you shortly.\n\nBest, Robert", "created": "2020-04-16T11:29:16", "id": "c4t-syst3m-335-2" }, { "authorEmail": "klaus@cat.design", "authorIsNotClient": false, "authorName": "Klaus", "comment": "Thank you Robert. If I would cover the difference in costs and ship back the fishless bowl, could you please send out the fishy fish bowl?", "created": "2020-04-16T11:24:51", "id": "c4t-syst3m-335-3" }, { "authorEmail": "jane@example.com", "authorIsNotClient": true, "authorName": "Jane", "comment": "Hey Klaus, Jane here\n\nIt seems that our system had not marked the fishy fish bowl as out of stock and that is why you were able to pay for one. Sorry for this mistake, we will cover the shipping costs and send out a fishy bowl. Is the address still valid?\n\nBest, Jane", "created": "2020-04-17T10:04:29", "id": "c4t-syst3m-335-4" }, { "authorEmail": "klaus@cat.design", "authorIsNotClient": false, "authorName": "Klaus", "comment": "That is wonderful news, Jane! Yes, feel free to use the same address. I will be eagerly waiting\n-Klaus", "created": "2020-04-17T13:48:26", "id": "c4t-syst3m-335-5" } ] } ] }'
That's it! You can now see your conversation on Klaus & review it!
Please refer to our public API's specification page for all the available query parameters, including filtering by scorecard tags, comment hashtags, and more!