Legacy Mailbox API 1.0 is deprecated

Legacy Mailbox API 1.0 was deprecated on November 20, 2019. Please use Mailbox API 2.0 going forward. If you have any questions or need help with the new API, please reach out.

User Conversation History

  • REST Method: GET
  • URLs: https://api.helpscout.net/v1/reports/user/conversation-history.json

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

URL Parameters

A variety of filters are available as query parameters. Including any of these will result in only conversations that match the filters being included in the report.

Parameter Type Required Notes Example
start Date/Time Yes ISO 8601, in UTC 2015-01-01T00:00:00Z
end Date/Time Yes ISO 8601, in UTC 2015-01-31T23:59:59Z
mailboxes list of mailbox identifiers No   1,2,3
tags list of tag identifiers No   1,2,3
types list of conversation types No Valid values are:
  • email
  • chat
  • phone
 email,chat
folders list of folder identifiers No   1,2,3
officeHours Boolean (0/1) No Whether to take office hours into consideration in the report (defaults to 0); office hours must be enabled if 1 is passed, otherwise the default of 0 will be used 1
user Int Yes user identifier for this report 1
page Int No The page number 1
sortField String No Field which to sort results by; valid values are:
  • number
  • repliesSent
  • responseTime
  • resolveTime
 repliesSent
sortOrder String No Valid values are:
  • ASC
  • DESC
 ASC

Response

Response Name Type Notes
Header Status Int 200
Body pages Int The total number of pages
  page Int The current page
  count Int Total number of conversations
  results Collection 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[index].number Int The conversation number
  results[index].responseTime Int Average amount of time (in seconds) the customer waited for a response from this user
  results[index].firstResponseTime Int The user's first response time for the conversation (in seconds)
  results[index].resolveTime Int Resolution time for the conversation, in seconds
  results[index].repliesSent Int Total number of replies sent for the conversation, including those of other users
  results[index].id Int The unique conversation identifier
  results[index].status String Status of the conversation; possible values include:
  • active
  • pending
  • closed
  • spam
  results[index].customers Collection List of customers associated with this conversation
  results[index].avgHandleTime Double 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

Example Response

{
  "pages": 3,
  "page": 1,
  "count": 58,
  "results": [
    {
      "number": 59691,
      "responseTime": 14434,
      "firstResponseTime": 14434,
      "resolveTime": 14434,
      "repliesSent": 4,
      "id": 1545204,
      "status": "closed",
      "customers": [
        {
          "id": 2,
          "name": "Mary Jones"
        }
      ],
      "avgHandleTime": 65.0
    },
    ...
  ]
}
↑Back to top
© Help Scout 2024