User Conversation History

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

Note: The reporting endpoints are only available to Plus and Pro plans.

Request

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

URL Parameters

Parameter Type Examples Description
user number user=447723
 User for whom the report is generated
start date start=2019-05-02T12:00:00Z
 Start of the interval
end date end=2019-06-02T12:00:00Z
 End of the interval
previousStart date previousStart=2019-04-02T12:00:00Z
 Start of the previous interval
previousEnd date previousEnd=2019-05-02T12:00:00Z
 End of the previous interval
status enumeration status=closed
 Conversation status, one of active, pending, closed
mailboxes number mailboxes=123
mailboxes=123,567
 List of comma separated ids to filter on inboxes
tags number tags=99787
tags=5666,99787
 List of comma separated ids to filter on tags
types enumeration types=email
 List of comma separated conversation types to filter on, valid values are email, chat, phone
folders number folders=991
folders=991,992
 List of comma separated folder ids to filter on folders
officeHours boolean officeHours=true
 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 number page=2
 The page number
sortField enumeration sortField=number
 Must be one of number, repliesSent, responseTviewByDescriptionime, resolveTime
sortOrder enumeration sortOrder=ASC
 Must be one of ASC or DESC

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "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, Accepted values are: active
pending
closed
spam
results[].avgHandleTime Number Average amount of time (in seconds) between the user loading the conversation and pressing the Send button; 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
↑Back to top
© Help Scout 2024