User Conversation History

The conversation history report provides details about a user’s conversations for over a specified time range.


GET /v2/reports/user/conversation-history HTTP/1.1
Authorization: Bearer oauth_token

URL Parameters

Parameter Description
user User for whom the report is generated
start Start of the interval
end End of the interval
previousStart Start of the previous interval
previousEnd End of the previous interval
status Conversation status, one of active, pending, closed
mailboxes List of comma separated ids to filter on mailboxes
tags List of comma separated ids to filter on tags
types List of comma separated conversation types to filter on, valid values are email, chat, phone
folders List of comma separated folder ids to filter on folders
officeHours Whether to take office hours into consideration in the report (defaults to false); office hours must be enabled if true is passed, otherwise the default of false will be used
page The page number
sortField Must be one of number, repliesSent, responseTime, resolveTime
sortOrder Must be one of ASC or DESC


HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

  "results" : [ {
    "id" : 416351186,
    "number" : 222002,
    "customers" : [ {
      "id" : 138946703,
      "name" : "Peter Peters"
    } ],
    "avgHandleTime" : 279,
    "firstResponseTime" : 1878,
    "repliesSent" : 1,
    "responseTime" : 1878,
    "resolveTime" : 1878
  }, {
    "id" : 4845671933,
    "number" : 221955,
    "customers" : [ {
      "id" : 137966680,
      "name" : "Alex Ballena"
    } ],
    "avgHandleTime" : 154,
    "firstResponseTime" : 8307,
    "repliesSent" : 1,
    "responseTime" : 8307,
    "resolveTime" : 8307
  } ],
  "page" : 1,
  "count" : 2303,
  "pages" : 20

Response fields

Path Type Description
page Number The current page
pages Number The total number of pages
count Number Total number of conversations
results Array Collection of details about each conversation thread for a given user. Note: Each element represents one reply the user sent, so it’s possible to have duplicate entries in the list if the user replied more than one time to the same conversation. You may wish to collapse duplicate threads.
results[].number Number The conversation number
results[].responseTime Number Average amount of time (in seconds) the customer waited for a response from this user
results[].firstResponseTime Number The user’s first response time for the conversation (in seconds)
results[].resolveTime Number Resolution time for the conversation, in seconds
results[].repliesSent Number Total number of replies sent for the conversation, including those of other users
results[].id Number The unique conversation identifier
results[].status String Status of the conversation, possible values include: active
results[].avgHandleTime Number Average amount of time (in seconds) between the user pressing the Reply and Send buttons for this conversation; if the user saved a draft and came back to visit it several times, only the final visit before sending is captured as the handle time
results[].customers Array List of customers associated with this conversation