This article explains how to import conversations into Zendesk QA using the API. By following these steps, you can seamlessly integrate your customer interactions into Zendesk QA for review and analysis.

This article contains the following sections:

  • Setting up the API connection
  • Importing conversations
  • Example payload
  • Sending the request

Setting up the API connection

Before you can import conversations, you need to set up an API connection in your Zendesk QA account. You will need the API token from that step to continue.

Importing conversations

To import conversations, you need to make a POST request to https://pub.klausapp.com/v1/tickets and set the API token as a Bearer token in the Authorization header.

Payload properties

Here are the properties you need to include in your payload:

  • id: 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: Simple strings displayed to the user.
  • created: A timestamp in the format yyyy-mm-ddThh:mm:ss.
  • updated: An optional field that can be provided later to enhance filtering capabilities in Zendesk QA (the expected format is the same as for the created field).
  • assigneeEmail: Must match an internal user's email on Zendesk QA for the conversation to be reviewable. Alternatively, a comment's authorEmail must match an internal user's email for a specific comment to be reviewed.
  • ticketFields: Optional fields that can 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, the authorEmail will be added as an external user, allowing you to connect or invite them.

Example payload

Here is an example payload for a 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": "Zendesk QA",
          "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, Zendesk QA",
          "created": "2020-04-16T11:24:51",
          "id": "c4t-syst3m-335-1"
        },
        {
          "authorEmail": "robert@example.com",
          "authorIsNotClient": true,
          "authorName": "Robert",
          "comment": "Hi, Zendesk QA!\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": "Zendesk QA",
          "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 Zendesk QA, 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": "Zendesk QA",
          "comment": "That is wonderful news, Jane! Yes, feel free to use the same address. I'll be eagerly waiting\n-Zendesk QA",
          "created": "2020-04-17T12:09:43",
          "id": "c4t-syst3m-335-5"
        }
      ]
    }
  ]
}

Sending the request

To send the request, use the following curl 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": "Zendesk QA", "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, Zendesk QA", "created": "2020-04-16T11:24:51", "id": "c4t-syst3m-335-1" }, { "authorEmail": "robert@example.com", "authorIsNotClient": true, "authorName": "Robert", "comment": "Hi, Zendesk QA!\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": "Zendesk QA", "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 Zendesk QA, 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": "Zendesk QA", "comment": "That is wonderful news, Jane! Yes, feel free to use the same address. I will be eagerly waiting\n-Zendesk QA", "created": "2020-04-17T13:48:26", "id": "c4t-syst3m-335-5" } ] } ] }'

You can now see your conversation on Zendesk QA and 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.

Powered by Zendesk