Exporting Conversation Data

Conversations in Gladly are a data structure that include all correspondence between the customer and the agent on one or more particular topics. A conversation can span anywhere from a few minutes to several days, include one to many agents, and even be seamlessly conducted across multiple channels.

All of this data holds powerful information that can be crucial to the success of your customer service center. Fortunately, Gladly provides an easy way to export it so your team can get to work on figuring out what it all means.

Data Flow

Step 1: Ask your Gladly Customer Success Manager to schedule a Conversation Export job

The export job will create files of data about successful communications that happened within the scheduled timeframe. You can choose to have your jobs scheduled in hourly or daily intervals.

For more information on how the jobs are scheduled and run, check out the export section of the developer docs.

Step 2: Create webhooks for job run events in Gladly

Gladly gives the ability to receive a webhook on both failed and successful jobs.

Step 2a: Create a webhook for successfully completed conversation export

Using the Webhooks Admin UI

Using the REST API

For more information on using the REST API––request body schema, response object, error states––you can view the docs.

POST /api/v1/webhooks
{
  "name": "Conversation Export Success",
  "url": "https://gateway.organization.com/gladly/webhook",
  "events": [
    "EXPORT_JOB/COMPLETED"
  ],
  "credentials": {
    "username": "integrations@organization.com",
    "password": "fxdUfTcejVxVs9bQ8DizKccq"
  },
  "headers": {
    "X-Gladly-Token": "123"
  }
}

Response

Once your webhook is set up, your endpoint will receive the following data every time an export job is finished successfully. You will receive the jobId of the scheduled job that was run.

POST https://gateway.organization.com/gladly/webhook
{
    "id": "q0uyHLIvSo61d5uL5qtTBQ",
    "timestamp": "2019-07-09T09:00:10.00Z",
    "type": "EXPORT_JOB/COMPLETED",
    "content": {
        "jobId": "UNdV3UdbTrulVRefCWV3fQ"
    }
}

Step 2b: Create a webhook for failed conversation export

The steps are the same as 2a, except you will choose EXPORT_JOB/FAILED. If you receive a webhook about a failed job, contact your Customer Success Manager at Gladly and they will help you.

Step 3: Request job information from Gladly

Once you have the jobId of the job that was successfully completed, you can make a request to get the names of the files that were generated in the job. Once you have the file names, you can request the files.

GET /api/v1/export/jobs/{jobId}
{
  "id": "UNdV3UdbTrulVRefCWV3fQ",
  "scheduleId": "OOrlNMXeS72gs_WEX2TtMg",
  "status": "COMPLETED",
  "updatedAt": "2019-07-09T09:00:10.00Z",
  "parameters": {
    "type": "CONVERSATIONS",
    "startAt": "2019-07-09T07:15:18.07272933Z",
    "endAt": "2019-07-09T08:15:18.07272933Z"
  },
  "files": [
    "agents.jsonl",
    "conversation_items.jsonl",
    "customers.jsonl",
    "topics.jsonl"
  ]
}

Step 4: Request conversation export files

Every conversation export job creates four distinct files containing data about successful communications that happened in the timeframe of the scheduled job.

The files are:

  • conversation_items.jsonl
  • agents.jsonl
  • topics.jsonl
  • customers.jsonl

Use the jobId from the webhook you received to request each file from Gladly.

GET /api/v1/export/jobs/{jobId}/files/{filename}

Conversation Items

Conversation items are individual communications between the customer and company. The items included in this file are a list of all conversation items that were transmitted without error during the export job scheduled range.

You will receive a jsonl file with the following schema:

[
    {
        "id": "ybP4szYCSy6LdV4DNwEd6g",
        "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
        "customerId": "OOrlNMXeS72gs_WEX2TtMg",
        "timestamp": "2019-07-01T11:46:45.01Z",
        "initiator": {
            "id": "OOrlNMXeS72gs_WEX2TtMg",
            "type": "CUSTOMER"
        },
        "content": {
            "type": "CHAT_MESSAGE",
            "sessionId": "5k04bYuTRGqyT6uoSQfWVA",
            "content": "Hi! I have a question."
        }
    },
    {
        "id": "9lQDrx-HTz-JMoP2T4CtZA",
        "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
        "customerId": "OOrlNMXeS72gs_WEX2TtMg",
        "timestamp": "2019-07-02T06:30:12.07Z",
        "initiator": {
            "id": "WmeA3Y51Q5ayCAaZ1AotIA",
            "type": "AGENT"
        },
        "content": {
            "type": "EMAIL",
            "from": "amy.agent@company.com",
            "to": ["martha.williams@gmail.com"],
            "subject": "Account upgrade",
            "content": "I would be happy to help you!"
        }
    }
]

It's important to note that each conversation item type has a different payload under content and will be one of CHAT_MESSAGE, SMS, EMAIL, FACEBOOK_MESSAGE, PHONE_CALL, or TOPIC_CHANGE.

SMS Item

Phone Call Item

Topic Change Item

Email Item

Chat Message Item

Read the docs for more information on conversation item content types.

Use the conversationId to identify data that is part of the same conversation. This can be done with data from the other files as well.

Agents

This file contains a list of all agents that were involved in a communication during this interval. The biggest advantage of using the agents.jsonl file is that it saves you from having to make numerous individual requests to Gladly.

You will receive a jsonl file with the following schema:

[
    {
        "id": "WmeA3Y51Q5ayCAaZ1AotIA",
        "name": "Amy Agent",
        "emailAddress": "amy.agent@company.com"
    }
]

When parsing conversation_items.jsonl, you can find the agentId under initiator, then match it with the id in the agents.jsonl file.

    {
        "id": "9lQDrx-HTz-JMoP2T4CtZA",
        "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
        "customerId": "OOrlNMXeS72gs_WEX2TtMg",
        "timestamp": "2019-07-02T06:30:12.07Z",
        "initiator": {
            "id": "WmeA3Y51Q5ayCAaZ1AotIA",
            "type": "AGENT"
        },
        "content": {
            "type": "EMAIL",
            "from": "amy.agent@company.com",
            "to": ["martha.williams@gmail.com"],
            "subject": "Account upgrade",
            "content": "I would be happy to help you!"
        }
    }

Topics

This file contains a list of all topics applied to and removed from communications during this interval. Similar to the agents.jsonl, you can save time requesting additional information by instead matching topicIds to the id in topics.jsonl.

You will receive a jsonl file with the following schema:

[
    {
        "id": "uu4t00vITaKQ3bVjU2UrGQ",
        "name": "Order Returns",
        "disabled": false
    }
]

When parsing conversation_items.jsonl, you can find the topicId under content on a TOPIC_CHANGE item type, then match it with the id in the topics.jsonl file. If the topic was added, the payload will have a field called addedTopicIds. If the topic was removed, the payload will have a field called removedTopicIds.

Added Topic Payload

{
    "id": "K0UGL3n6S4uPpvtMvItqHA",
    "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
    "customerId": "OOrlNMXeS72gs_WEX2TtMg",
    "timestamp": "2019-07-02T08:12:55.870Z",
    "initiator": {
        "id": "WmeA3Y51Q5ayCAaZ1AotIA",
        "type": "AGENT"
    },
    "content": {
        "type": "TOPIC_CHANGE",
        "addedTopicIds": ["uu4t00vITaKQ3bVjU2UrGQ"]
    }
}

Removed Topic Payload

{
    "id": "K0UGL3n6S4uPpvtMvItqHA",
    "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
    "customerId": "OOrlNMXeS72gs_WEX2TtMg",
    "timestamp": "2019-07-02T08:12:55.870Z",
    "initiator": {
        "id": "WmeA3Y51Q5ayCAaZ1AotIA",
        "type": "AGENT"
    },
    "content": {
        "type": "TOPIC_CHANGE",
        "removedTopicIds": ["uu4t00vITaKQ3bVjU2UrGQ"]
    }
}

Customers

This file contains a list of all customers who were involved in conversations that were closed during this interval.

You will receive a jsonl file with the following schema:

[
    {
        "id" : "OOrlNMXeS72gs_WEX2TtMg",
        "name": "Martha J Williams",
        "address": "563 Rigoberto Station Apt. 197",
        "emailAddresses": ["Martha.Williams@gmail.com"],
        "phoneNumbers": ["+17244895501"],
        "externalCustomerId": "a21c1636-c622-48b7-bf6a-d9032645aa55"
    }
]

When parsing conversation_items.jsonl, use the customerId to match the id in customers.jsonl.

    {
        "id": "ybP4szYCSy6LdV4DNwEd6g",
        "conversationId": "9BcE2O0DQ2ynGHRmk9FeoA",
        "customerId": "OOrlNMXeS72gs_WEX2TtMg",
        "timestamp": "2019-07-01T11:46:45.01Z",
        "initiator": {
            "id": "OOrlNMXeS72gs_WEX2TtMg",
            "type": "CUSTOMER"
        },
        "content": {
            "type": "CHAT_MESSAGE",
            "sessionId": "5k04bYuTRGqyT6uoSQfWVA",
            "content": "Hi! I have a question."
        }
    },

Step 5: Make additional requests

Based on what you are using this data for, you might need some additional information from Gladly. For example, if you needed additional data from the customer profile––maybe a custom attribute, like customerSince––you can request the customer profile using the customerId.

Check out the REST API Documentation for further details.

Step 6: Delete the file from Gladly

As an extra security measure, it's important for you to delete the job and associated files from Gladly once you have downloaded it.

First, make sure you have already successfully downloaded the file(s).

If you received a 404 error when request the file in Step 4, do not delete the file. Make sure you are successfully able to download before doing any deletions.

Next, send a request to Gladly to delete the job and files by specifying the jobId.

DELETE /api/v1/export/jobs/{jobId}

Note that files will be automatically deleted by Gladly 10 days after download or 30 days after generation, whichever comes first.