helpscout-mailbox-v2-reports 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/.buildkite/pipeline.yml +6 -0
- data/.gitignore +11 -0
- data/.rspec +3 -0
- data/.ruby-version +1 -0
- data/.travis.yml +6 -0
- data/CODE_OF_CONDUCT.md +74 -0
- data/Dockerfile +8 -0
- data/Gemfile +4 -0
- data/Gemfile.lock +68 -0
- data/LICENSE.txt +21 -0
- data/README.md +1986 -0
- data/Rakefile +6 -0
- data/bin/console +14 -0
- data/bin/setup +8 -0
- data/docker-compose.yml +5 -0
- data/helpscout-mailbox-v2-reports.gemspec +34 -0
- data/lib/helpscout/mailbox/v2/reports.rb +14 -0
- data/lib/helpscout/mailbox/v2/reports/client.rb +214 -0
- data/lib/helpscout/mailbox/v2/reports/validate.rb +65 -0
- data/lib/helpscout/mailbox/v2/reports/version.rb +9 -0
- metadata +149 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 371ed89a96e59f4cecb628556844659b67c90b15fbcbe91b3d21c00d30ba2007
|
|
4
|
+
data.tar.gz: 95d69395f260e85c2ff93c1fc0f5b8ae92d8a8315b9e93059d124ae3e56faba9
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 15d9d9ef278bab67d7e47ee11d1842feea520456352ddce3c28f813206c3bd8faa240a748929ff7ca5d3bd8bdd61e42d113251db9079ba1adecfb6db34c2b649
|
|
7
|
+
data.tar.gz: f00751e2554331ba88e93936816a6dcbfc5788d0b2c001de139d260dd2211be4546b59581a83c22e8f2844295666fffc018217eb10b607f4ce417ad27b26f063
|
data/.gitignore
ADDED
data/.rspec
ADDED
data/.ruby-version
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
2.7.0
|
data/.travis.yml
ADDED
data/CODE_OF_CONDUCT.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Contributor Covenant Code of Conduct
|
|
2
|
+
|
|
3
|
+
## Our Pledge
|
|
4
|
+
|
|
5
|
+
In the interest of fostering an open and welcoming environment, we as
|
|
6
|
+
contributors and maintainers pledge to making participation in our project and
|
|
7
|
+
our community a harassment-free experience for everyone, regardless of age, body
|
|
8
|
+
size, disability, ethnicity, gender identity and expression, level of experience,
|
|
9
|
+
nationality, personal appearance, race, religion, or sexual identity and
|
|
10
|
+
orientation.
|
|
11
|
+
|
|
12
|
+
## Our Standards
|
|
13
|
+
|
|
14
|
+
Examples of behavior that contributes to creating a positive environment
|
|
15
|
+
include:
|
|
16
|
+
|
|
17
|
+
* Using welcoming and inclusive language
|
|
18
|
+
* Being respectful of differing viewpoints and experiences
|
|
19
|
+
* Gracefully accepting constructive criticism
|
|
20
|
+
* Focusing on what is best for the community
|
|
21
|
+
* Showing empathy towards other community members
|
|
22
|
+
|
|
23
|
+
Examples of unacceptable behavior by participants include:
|
|
24
|
+
|
|
25
|
+
* The use of sexualized language or imagery and unwelcome sexual attention or
|
|
26
|
+
advances
|
|
27
|
+
* Trolling, insulting/derogatory comments, and personal or political attacks
|
|
28
|
+
* Public or private harassment
|
|
29
|
+
* Publishing others' private information, such as a physical or electronic
|
|
30
|
+
address, without explicit permission
|
|
31
|
+
* Other conduct which could reasonably be considered inappropriate in a
|
|
32
|
+
professional setting
|
|
33
|
+
|
|
34
|
+
## Our Responsibilities
|
|
35
|
+
|
|
36
|
+
Project maintainers are responsible for clarifying the standards of acceptable
|
|
37
|
+
behavior and are expected to take appropriate and fair corrective action in
|
|
38
|
+
response to any instances of unacceptable behavior.
|
|
39
|
+
|
|
40
|
+
Project maintainers have the right and responsibility to remove, edit, or
|
|
41
|
+
reject comments, commits, code, wiki edits, issues, and other contributions
|
|
42
|
+
that are not aligned to this Code of Conduct, or to ban temporarily or
|
|
43
|
+
permanently any contributor for other behaviors that they deem inappropriate,
|
|
44
|
+
threatening, offensive, or harmful.
|
|
45
|
+
|
|
46
|
+
## Scope
|
|
47
|
+
|
|
48
|
+
This Code of Conduct applies both within project spaces and in public spaces
|
|
49
|
+
when an individual is representing the project or its community. Examples of
|
|
50
|
+
representing a project or community include using an official project e-mail
|
|
51
|
+
address, posting via an official social media account, or acting as an appointed
|
|
52
|
+
representative at an online or offline event. Representation of a project may be
|
|
53
|
+
further defined and clarified by project maintainers.
|
|
54
|
+
|
|
55
|
+
## Enforcement
|
|
56
|
+
|
|
57
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
|
58
|
+
reported by contacting the project team at TODO: Write your email address. All
|
|
59
|
+
complaints will be reviewed and investigated and will result in a response that
|
|
60
|
+
is deemed necessary and appropriate to the circumstances. The project team is
|
|
61
|
+
obligated to maintain confidentiality with regard to the reporter of an incident.
|
|
62
|
+
Further details of specific enforcement policies may be posted separately.
|
|
63
|
+
|
|
64
|
+
Project maintainers who do not follow or enforce the Code of Conduct in good
|
|
65
|
+
faith may face temporary or permanent repercussions as determined by other
|
|
66
|
+
members of the project's leadership.
|
|
67
|
+
|
|
68
|
+
## Attribution
|
|
69
|
+
|
|
70
|
+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
|
|
71
|
+
available at [https://contributor-covenant.org/version/1/4][version]
|
|
72
|
+
|
|
73
|
+
[homepage]: https://contributor-covenant.org
|
|
74
|
+
[version]: https://contributor-covenant.org/version/1/4/
|
data/Dockerfile
ADDED
data/Gemfile
ADDED
data/Gemfile.lock
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
PATH
|
|
2
|
+
remote: .
|
|
3
|
+
specs:
|
|
4
|
+
helpscout-mailbox-v2-reports (0.1.0)
|
|
5
|
+
activesupport (~> 6.0)
|
|
6
|
+
helpscout-mailbox-v2-client (~> 0.1.0)
|
|
7
|
+
|
|
8
|
+
GEM
|
|
9
|
+
remote: https://rubygems.org/
|
|
10
|
+
specs:
|
|
11
|
+
activesupport (6.0.2.1)
|
|
12
|
+
concurrent-ruby (~> 1.0, >= 1.0.2)
|
|
13
|
+
i18n (>= 0.7, < 2)
|
|
14
|
+
minitest (~> 5.1)
|
|
15
|
+
tzinfo (~> 1.1)
|
|
16
|
+
zeitwerk (~> 2.2)
|
|
17
|
+
addressable (2.7.0)
|
|
18
|
+
public_suffix (>= 2.0.2, < 5.0)
|
|
19
|
+
concurrent-ruby (1.1.6)
|
|
20
|
+
crack (0.4.3)
|
|
21
|
+
safe_yaml (~> 1.0.0)
|
|
22
|
+
diff-lcs (1.3)
|
|
23
|
+
hashdiff (1.0.1)
|
|
24
|
+
helpscout-api-auth (0.2.0)
|
|
25
|
+
helpscout-mailbox-paths (1.0.0)
|
|
26
|
+
helpscout-mailbox-v2-client (0.1.0)
|
|
27
|
+
helpscout-api-auth (~> 0.2.0)
|
|
28
|
+
helpscout-mailbox-paths (~> 1.0.0)
|
|
29
|
+
i18n (1.8.2)
|
|
30
|
+
concurrent-ruby (~> 1.0)
|
|
31
|
+
minitest (5.14.0)
|
|
32
|
+
public_suffix (4.0.3)
|
|
33
|
+
rake (12.3.3)
|
|
34
|
+
rspec (3.9.0)
|
|
35
|
+
rspec-core (~> 3.9.0)
|
|
36
|
+
rspec-expectations (~> 3.9.0)
|
|
37
|
+
rspec-mocks (~> 3.9.0)
|
|
38
|
+
rspec-core (3.9.1)
|
|
39
|
+
rspec-support (~> 3.9.1)
|
|
40
|
+
rspec-expectations (3.9.0)
|
|
41
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
42
|
+
rspec-support (~> 3.9.0)
|
|
43
|
+
rspec-mocks (3.9.1)
|
|
44
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
45
|
+
rspec-support (~> 3.9.0)
|
|
46
|
+
rspec-support (3.9.2)
|
|
47
|
+
safe_yaml (1.0.5)
|
|
48
|
+
thread_safe (0.3.6)
|
|
49
|
+
tzinfo (1.2.6)
|
|
50
|
+
thread_safe (~> 0.1)
|
|
51
|
+
webmock (3.8.3)
|
|
52
|
+
addressable (>= 2.3.6)
|
|
53
|
+
crack (>= 0.3.2)
|
|
54
|
+
hashdiff (>= 0.4.0, < 2.0.0)
|
|
55
|
+
zeitwerk (2.3.0)
|
|
56
|
+
|
|
57
|
+
PLATFORMS
|
|
58
|
+
ruby
|
|
59
|
+
|
|
60
|
+
DEPENDENCIES
|
|
61
|
+
bundler (~> 2.0)
|
|
62
|
+
helpscout-mailbox-v2-reports!
|
|
63
|
+
rake (>= 12.3.3)
|
|
64
|
+
rspec (~> 3.0)
|
|
65
|
+
webmock (~> 3.8)
|
|
66
|
+
|
|
67
|
+
BUNDLED WITH
|
|
68
|
+
2.1.2
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2020 Jason Jacob
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,1986 @@
|
|
|
1
|
+
# Helpscout::Mailbox::V2::Reports
|
|
2
|
+
|
|
3
|
+
[](https://buildkite.com/jayco/helpscout-mailbox-v2-reports)
|
|
4
|
+
|
|
5
|
+
Simple to use client for interacting with the [Report Endpoints](https://developer.helpscout.com/mailbox-api/endpoints/reports/company/reports-company-overall) for the HelpScout V2 Mailbox API
|
|
6
|
+
|
|
7
|
+
It uses the following HelpScout gems:
|
|
8
|
+
|
|
9
|
+
- [Helpscout::Api::Auth](https://github.com/jayco/helpscout-api-auth.git)
|
|
10
|
+
- [Helpscout::Mailbox::Paths](https://github.com/jayco/helpscout-mailbox-paths.git)
|
|
11
|
+
- [Helpscout::Mailbox::V2::Client](https://github.com/jayco/helpscout-mailbox-v2-client)
|
|
12
|
+
|
|
13
|
+
## Installation
|
|
14
|
+
|
|
15
|
+
Add this line to your application's Gemfile:
|
|
16
|
+
|
|
17
|
+
```ruby
|
|
18
|
+
gem 'helpscout-mailbox-v2-reports'
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
And then execute:
|
|
22
|
+
|
|
23
|
+
$ bundle install
|
|
24
|
+
|
|
25
|
+
Or install it yourself as:
|
|
26
|
+
|
|
27
|
+
$ gem install helpscout-mailbox-v2-reports
|
|
28
|
+
|
|
29
|
+
## Usage
|
|
30
|
+
|
|
31
|
+
#### Table of Contents
|
|
32
|
+
|
|
33
|
+
[Initialization](#Initialization)
|
|
34
|
+
|
|
35
|
+
[Company Reports](#Company-Reports)
|
|
36
|
+
|
|
37
|
+
- [get_company](#get_company)
|
|
38
|
+
- [get_company_customers_helped](#get_company_customers_helped)
|
|
39
|
+
- [get_company_drilldown](#get_company_drilldown)
|
|
40
|
+
|
|
41
|
+
[Conversation Reports](#Conversation-Reports)
|
|
42
|
+
|
|
43
|
+
- [get_conversations](#get_conversations)
|
|
44
|
+
- [get_conversations_new_conversations](#get_conversations_new_conversations)
|
|
45
|
+
- [get_conversations_channel_volumes](#get_conversations_channel_volumes)
|
|
46
|
+
- [get_conversations_busiest_times](#get_conversations_busiest_times)
|
|
47
|
+
- [get_conversations_drilldown](#get_conversations_drilldown)
|
|
48
|
+
- [get_conversations_drilldown_by_field](#get_conversations_drilldown_by_field)
|
|
49
|
+
- [get_conversations_new_conversations_drilldown](#get_conversations_new_conversations_drilldown)
|
|
50
|
+
- [get_conversations_received_message_stats](#get_conversations_received_message_stats)
|
|
51
|
+
|
|
52
|
+
[Doc Reports](#Doc-Reports)
|
|
53
|
+
|
|
54
|
+
- [get_docs](#get_docs)
|
|
55
|
+
|
|
56
|
+
[Happiness Reports](#Happiness-Reports)
|
|
57
|
+
|
|
58
|
+
- [get_happiness](#get_happiness)
|
|
59
|
+
- [get_happiness_ratings](#get_happiness_ratings)
|
|
60
|
+
|
|
61
|
+
[Productivity Reports](#Productivity-Reports)
|
|
62
|
+
|
|
63
|
+
- [get_productivity](#get_productivity)
|
|
64
|
+
- [get_productivity_first_response_time](#get_productivity_first_response_time)
|
|
65
|
+
- [get_productivity_replies_sent](#get_productivity_replies_sent)
|
|
66
|
+
- [get_productivity_resolution_time](#get_productivity_resolution_time)
|
|
67
|
+
- [get_productivity_resolved](#get_productivity_resolved)
|
|
68
|
+
- [get_productivity_response_time](#get_productivity_response_time)
|
|
69
|
+
|
|
70
|
+
[User Reports](#User-Reports)
|
|
71
|
+
|
|
72
|
+
- [get_user](#get_user)
|
|
73
|
+
- [get_user_conversation_history](#get_user_conversation_history)
|
|
74
|
+
- [get_user_customers_helped](#get_user_customers_helped)
|
|
75
|
+
- [get_user_drilldown](#get_user_drilldown)
|
|
76
|
+
- [get_user_happiness](#get_user_happiness)
|
|
77
|
+
- [get_user_happiness_drilldown](#get_user_happiness_drilldown)
|
|
78
|
+
- [get_user_replies](#get_user_replies)
|
|
79
|
+
- [get_user_resolutions](#get_user_resolutions)
|
|
80
|
+
|
|
81
|
+
[Chat Reports](#Chat-Reports)
|
|
82
|
+
|
|
83
|
+
- [get_chat](#get_chat)
|
|
84
|
+
|
|
85
|
+
[Email Reports](#Email-Reports)
|
|
86
|
+
|
|
87
|
+
- [get_email](#get_email)
|
|
88
|
+
|
|
89
|
+
[Phone Reports](#Phone-Reports)
|
|
90
|
+
|
|
91
|
+
- [get_phone](#get_phone)
|
|
92
|
+
|
|
93
|
+
### Initialization
|
|
94
|
+
|
|
95
|
+
Creates a new Client class and authorises the client with HelpScout
|
|
96
|
+
|
|
97
|
+
| Parameter | Type | Description |
|
|
98
|
+
| :-------------- | :------- | :--------------------------------------------------------------------- |
|
|
99
|
+
| `client_id` | `string` | **Required** HelpScout API client id |
|
|
100
|
+
| `client_secret` | `string` | **Required** HelpScout API client secret |
|
|
101
|
+
| `base_url` | `string` | **Optional** HelpScout API url (defaults to https://api.helpscout.net) |
|
|
102
|
+
|
|
103
|
+
```ruby
|
|
104
|
+
require 'helpscout/mailbox/v2/reports'
|
|
105
|
+
|
|
106
|
+
client = Helpscout::Mailbox::V2::Reports::Client.new(client_id: 'some id', client_secret: 'keep it secret')
|
|
107
|
+
# => 'BMEv1lmcNgDBpOFNHo8TPlODMrF3BG5T'
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### Company Reports
|
|
112
|
+
|
|
113
|
+
#### get_company
|
|
114
|
+
|
|
115
|
+
The company report provides statistics about your company performance over a given time range. You may optionally specify two time ranges to see how performance changed between the two ranges.
|
|
116
|
+
|
|
117
|
+
Maps to [Company Overall Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/company/reports-company-overall)
|
|
118
|
+
|
|
119
|
+
| Parameter | Type | Description | Example |
|
|
120
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
121
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
122
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
123
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
124
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
125
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
126
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
127
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
128
|
+
|
|
129
|
+
```ruby
|
|
130
|
+
response = client.get_company
|
|
131
|
+
# =>
|
|
132
|
+
# {
|
|
133
|
+
# "filterTags" : [ {
|
|
134
|
+
# "id" : 123,
|
|
135
|
+
# "name" : "sample-tag"
|
|
136
|
+
# } ],
|
|
137
|
+
# "current" : {
|
|
138
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
139
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
140
|
+
# "customersHelped" : 28,
|
|
141
|
+
# "closed" : 94,
|
|
142
|
+
# "totalReplies" : 62,
|
|
143
|
+
# "totalUsers" : 5,
|
|
144
|
+
# "totalDays" : 30,
|
|
145
|
+
# "repliesPerDayPerUser" : 0.41333333333333333,
|
|
146
|
+
# "repliesPerDay" : 2.066666666666667,
|
|
147
|
+
# "resolvedPerDay" : 0.03333333333333333
|
|
148
|
+
# },
|
|
149
|
+
# "previous" : {
|
|
150
|
+
# "startDate" : "2014-01-01T00:00:00Z",
|
|
151
|
+
# "endDate" : "2014-01-31T23:59:59Z",
|
|
152
|
+
# "customersHelped" : 27,
|
|
153
|
+
# "closed" : 49,
|
|
154
|
+
# "totalReplies" : 636,
|
|
155
|
+
# "totalUsers" : 4,
|
|
156
|
+
# "totalDays" : 30,
|
|
157
|
+
# "repliesPerDayPerUser" : 5.3,
|
|
158
|
+
# "repliesPerDay" : 21.2,
|
|
159
|
+
# "resolvedPerDay" : 0.4666666666666667
|
|
160
|
+
# },
|
|
161
|
+
# "deltas" : {
|
|
162
|
+
# "customersHelped" : 3.703703703703698,
|
|
163
|
+
# "totalReplies" : -90.25157232704403,
|
|
164
|
+
# "repliesPerDay" : -90.25157232704403,
|
|
165
|
+
# "closed" : 91.83673469387755,
|
|
166
|
+
# "totalUsers" : 25.0,
|
|
167
|
+
# "repliesPerDayPerUser" : -92.20125786163523
|
|
168
|
+
# },
|
|
169
|
+
# "users" : [ {
|
|
170
|
+
# "customersHelped" : 26,
|
|
171
|
+
# "happinessScore" : 66.66666666666666,
|
|
172
|
+
# "previousCustomersHelped" : 16,
|
|
173
|
+
# "replies" : 58,
|
|
174
|
+
# "name" : "John Smith",
|
|
175
|
+
# "previousHappinessScore" : 23.529411764705884,
|
|
176
|
+
# "previousReplies" : 40,
|
|
177
|
+
# "user" : "1",
|
|
178
|
+
# "previousHandleTime" : 0.0,
|
|
179
|
+
# "handleTime" : 78.96
|
|
180
|
+
# } ]
|
|
181
|
+
# }
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
#### get_company_customers_helped
|
|
185
|
+
|
|
186
|
+
The customers helped report provides statistics about how many customers were helped over a given time range. You may optionally specify two time ranges to see how the number of customers helped changed between the two ranges.
|
|
187
|
+
|
|
188
|
+
Maps to [Company Customers Helped](https://developer.helpscout.com/mailbox-api/endpoints/reports/company/reports-company-customers-helped/)
|
|
189
|
+
|
|
190
|
+
| Parameter | Type | Description | Example |
|
|
191
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
192
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
193
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
194
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
195
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
196
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
197
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
198
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
199
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
200
|
+
|
|
201
|
+
```ruby
|
|
202
|
+
response = client.get_company_customers_helped
|
|
203
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"customers\":58}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"customers\":69}]}"
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
#### get_company_drilldown
|
|
207
|
+
|
|
208
|
+
This report is similar to the Company Report, but instead of returning statistics about the company, it drills down and returns the conversation data that makes up the Company Report.
|
|
209
|
+
|
|
210
|
+
Maps to [Company Drilldown](https://developer.helpscout.com/mailbox-api/endpoints/reports/company/reports-company-drilldown/)
|
|
211
|
+
|
|
212
|
+
| Parameter | Type | Description | Example |
|
|
213
|
+
| :----------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
|
214
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
215
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
216
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
217
|
+
| `rows` | `number` | Number of result to return per page; defaults to 25; maximum is 50 | `rows: 30` |
|
|
218
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
219
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
220
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
221
|
+
| `range` | `enumeration` | Range valid values are _replies, firstReplyResolved, resolved responseTime, firstResponseTime, handleTime_ **Defaults responseTime** | `range: replies` |
|
|
222
|
+
| `range_id` | `number` | Range ID details, only valid if range is used | `range_id: 2` |
|
|
223
|
+
|
|
224
|
+
```ruby
|
|
225
|
+
response = client.get_company_drilldown
|
|
226
|
+
# =>
|
|
227
|
+
# {
|
|
228
|
+
# "conversations" : {
|
|
229
|
+
# "pages" : 157,
|
|
230
|
+
# "page" : 1,
|
|
231
|
+
# "count" : 1561,
|
|
232
|
+
# "results" : [ {
|
|
233
|
+
# "id" : 583,
|
|
234
|
+
# "number" : 12345,
|
|
235
|
+
# "type" : "email",
|
|
236
|
+
# "mailboxid" : 2,
|
|
237
|
+
# "attachments" : false,
|
|
238
|
+
# "subject" : "Sample subject",
|
|
239
|
+
# "status" : "active",
|
|
240
|
+
# "threadCount" : 6,
|
|
241
|
+
# "preview" : "This is a preview...",
|
|
242
|
+
# "customerName" : "John Smith",
|
|
243
|
+
# "customerEmail" : "john@example.com",
|
|
244
|
+
# "customerIds" : [ 2 ],
|
|
245
|
+
# "modifiedAt" : "2015-04-24T18:59:49Z",
|
|
246
|
+
# "assignedid" : 4,
|
|
247
|
+
# "tags" : [ {
|
|
248
|
+
# "id" : 123,
|
|
249
|
+
# "name" : "sample-tag",
|
|
250
|
+
# "color" : "none"
|
|
251
|
+
# } ],
|
|
252
|
+
# "assignedName" : "Mary Jones"
|
|
253
|
+
# } ]
|
|
254
|
+
# }
|
|
255
|
+
# }
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Conversation Reports
|
|
259
|
+
|
|
260
|
+
#### get_conversations
|
|
261
|
+
|
|
262
|
+
The conversations report provides statistics about conversation volume over a given time range. You may optionally specify two time ranges to see how conversation volume changed between the two ranges.
|
|
263
|
+
|
|
264
|
+
Maps to [Conversations Overall Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-overall)
|
|
265
|
+
|
|
266
|
+
| Parameter | Type | Description | Example |
|
|
267
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
268
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
269
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
270
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
271
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
272
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
273
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
274
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
275
|
+
|
|
276
|
+
```ruby
|
|
277
|
+
response = client.get_conversations
|
|
278
|
+
|
|
279
|
+
# =>
|
|
280
|
+
# {
|
|
281
|
+
# "filterTags" : [ {
|
|
282
|
+
# "name" : "tag a",
|
|
283
|
+
# "id" : 2
|
|
284
|
+
# }, {
|
|
285
|
+
# "name" : "tag b",
|
|
286
|
+
# "id" : 3
|
|
287
|
+
# } ],
|
|
288
|
+
# "busiestDay" : {
|
|
289
|
+
# "day" : 3,
|
|
290
|
+
# "hour" : 0,
|
|
291
|
+
# "count" : 411
|
|
292
|
+
# },
|
|
293
|
+
# "busyTimeStart" : 11,
|
|
294
|
+
# "busyTimeEnd" : 13,
|
|
295
|
+
# "current" : {
|
|
296
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
297
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
298
|
+
# "totalConversations" : 1816,
|
|
299
|
+
# "conversationsCreated" : 1698,
|
|
300
|
+
# "newConversations" : 1698,
|
|
301
|
+
# "customers" : 1302,
|
|
302
|
+
# "conversationsPerDay" : 60
|
|
303
|
+
# },
|
|
304
|
+
# "previous" : {
|
|
305
|
+
# "startDate" : "2014-01-01T00:00:00Z",
|
|
306
|
+
# "endDate" : "2014-01-01T23:59:59Z",
|
|
307
|
+
# "totalConversations" : 2080,
|
|
308
|
+
# "conversationsCreated" : 1976,
|
|
309
|
+
# "newConversations" : 1976,
|
|
310
|
+
# "customers" : 1479,
|
|
311
|
+
# "conversationsPerDay" : 67
|
|
312
|
+
# },
|
|
313
|
+
# "deltas" : {
|
|
314
|
+
# "newConversations" : -14.068825910931,
|
|
315
|
+
# "totalConversations" : -12.692307692308,
|
|
316
|
+
# "customers" : -11.967545638945,
|
|
317
|
+
# "conversationsCreated" : -14.068825910931,
|
|
318
|
+
# "conversationsPerDay" : -10.44776119403
|
|
319
|
+
# },
|
|
320
|
+
# "tags" : {
|
|
321
|
+
# "count" : 351,
|
|
322
|
+
# "top" : [ {
|
|
323
|
+
# "id" : 1,
|
|
324
|
+
# "count" : 1465,
|
|
325
|
+
# "previousCount" : 1651,
|
|
326
|
+
# "percent" : 80.671806167401,
|
|
327
|
+
# "previousPercent" : 79.375,
|
|
328
|
+
# "deltaPercent" : 1.2968061674009
|
|
329
|
+
# }, {
|
|
330
|
+
# "name" : "tag a",
|
|
331
|
+
# "id" : 2,
|
|
332
|
+
# "count" : 51,
|
|
333
|
+
# "previousCount" : 63,
|
|
334
|
+
# "percent" : 2.8083700440529,
|
|
335
|
+
# "previousPercent" : 3.0288461538462,
|
|
336
|
+
# "deltaPercent" : -0.22047610979329
|
|
337
|
+
# }, {
|
|
338
|
+
# "name" : "tag b",
|
|
339
|
+
# "id" : 406031,
|
|
340
|
+
# "count" : 24,
|
|
341
|
+
# "previousCount" : 20,
|
|
342
|
+
# "percent" : 1.3215859030837,
|
|
343
|
+
# "previousPercent" : 0.96153846153846,
|
|
344
|
+
# "deltaPercent" : 0.36004744154524
|
|
345
|
+
# } ]
|
|
346
|
+
# },
|
|
347
|
+
# "customers" : {
|
|
348
|
+
# "count" : 1816,
|
|
349
|
+
# "top" : [ {
|
|
350
|
+
# "count" : 31,
|
|
351
|
+
# "deltaPercent" : 0.31281768891901,
|
|
352
|
+
# "id" : 1,
|
|
353
|
+
# "name" : "John Smith",
|
|
354
|
+
# "percent" : 1.7070484581498,
|
|
355
|
+
# "previousCount" : 29,
|
|
356
|
+
# "previousPercent" : 1.3942307692308
|
|
357
|
+
# }, {
|
|
358
|
+
# "count" : 12,
|
|
359
|
+
# "deltaPercent" : -0.10843781768892,
|
|
360
|
+
# "id" : 2,
|
|
361
|
+
# "name" : "Mary Jones",
|
|
362
|
+
# "percent" : 0.66079295154185,
|
|
363
|
+
# "previousCount" : 16,
|
|
364
|
+
# "previousPercent" : 0.76923076923077
|
|
365
|
+
# } ]
|
|
366
|
+
# },
|
|
367
|
+
# "replies" : {
|
|
368
|
+
# "count" : 109,
|
|
369
|
+
# "top" : [ {
|
|
370
|
+
# "name" : "Saved Reply 1",
|
|
371
|
+
# "id" : 1,
|
|
372
|
+
# "mailboxId" : 1,
|
|
373
|
+
# "count" : 16,
|
|
374
|
+
# "previousCount" : 9,
|
|
375
|
+
# "percent" : 0.88105726872247,
|
|
376
|
+
# "previousPercent" : 0.43269230769231,
|
|
377
|
+
# "deltaPercent" : 0.44836496103016
|
|
378
|
+
# }, {
|
|
379
|
+
# "name" : "Saved Reply 2",
|
|
380
|
+
# "id" : 2,
|
|
381
|
+
# "mailboxId" : 1,
|
|
382
|
+
# "count" : 13,
|
|
383
|
+
# "previousCount" : 12,
|
|
384
|
+
# "percent" : 0.715859030837,
|
|
385
|
+
# "previousPercent" : 0.57692307692308,
|
|
386
|
+
# "deltaPercent" : 0.13893595391393
|
|
387
|
+
# } ]
|
|
388
|
+
# },
|
|
389
|
+
# "workflows" : {
|
|
390
|
+
# "count" : 240,
|
|
391
|
+
# "top" : [ {
|
|
392
|
+
# "name" : "Workflow 1",
|
|
393
|
+
# "id" : 1,
|
|
394
|
+
# "count" : 90,
|
|
395
|
+
# "previousCount" : 82,
|
|
396
|
+
# "percent" : 4.9559471365639,
|
|
397
|
+
# "previousPercent" : 3.9423076923077,
|
|
398
|
+
# "deltaPercent" : 1.0136394442562
|
|
399
|
+
# }, {
|
|
400
|
+
# "name" : "Workflow 2",
|
|
401
|
+
# "id" : 2,
|
|
402
|
+
# "count" : 75,
|
|
403
|
+
# "previousCount" : 91,
|
|
404
|
+
# "percent" : 4.1299559471366,
|
|
405
|
+
# "previousPercent" : 4.375,
|
|
406
|
+
# "deltaPercent" : -0.24504405286344
|
|
407
|
+
# } ]
|
|
408
|
+
# },
|
|
409
|
+
# "customFields" : {
|
|
410
|
+
# "count" : 1,
|
|
411
|
+
# "fields" : [ {
|
|
412
|
+
# "id" : 8,
|
|
413
|
+
# "name" : "Account Type",
|
|
414
|
+
# "mailboxId" : 1234,
|
|
415
|
+
# "values" : [ {
|
|
416
|
+
# "name" : "Paying Customer",
|
|
417
|
+
# "id" : 7,
|
|
418
|
+
# "count" : 1442,
|
|
419
|
+
# "percent" : 55.12232415902141
|
|
420
|
+
# }, {
|
|
421
|
+
# "name" : "Trial Customer",
|
|
422
|
+
# "id" : 11,
|
|
423
|
+
# "count" : 273,
|
|
424
|
+
# "percent" : 10.435779816513762
|
|
425
|
+
# } ],
|
|
426
|
+
# "summary" : {
|
|
427
|
+
# "total" : 2616,
|
|
428
|
+
# "totalAnswered" : 2241,
|
|
429
|
+
# "previousTotal" : null,
|
|
430
|
+
# "previousTotalAnswered" : null,
|
|
431
|
+
# "unansweredDelta" : 14.3348623853211,
|
|
432
|
+
# "unansweredPreviousPercent" : 0,
|
|
433
|
+
# "unansweredPercent" : 14.3348623853211
|
|
434
|
+
# }
|
|
435
|
+
# } ]
|
|
436
|
+
# }
|
|
437
|
+
# }
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
#### get_conversations_new_conversations
|
|
441
|
+
|
|
442
|
+
The new conversations report provides a summary of new conversation volume over a given time range.
|
|
443
|
+
|
|
444
|
+
Maps to [Conversations - New Conversations](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-new)
|
|
445
|
+
|
|
446
|
+
| Parameter | Type | Description | Example |
|
|
447
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
448
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
449
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
450
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
451
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
452
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
453
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
454
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
455
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
456
|
+
|
|
457
|
+
```ruby
|
|
458
|
+
response = client.get_conversations_new_conversations
|
|
459
|
+
# => "{\"current\":[{\"start\":\"2020-03-09T13:30:00Z\",\"count\":62}],\"previous\":[{\"start\":\"2020-02-24T13:30:00Z\",\"count\":69}]}"
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
#### get_conversations_channel_volumes
|
|
463
|
+
|
|
464
|
+
This report shows conversation volumes split by chat, phone and email channels.
|
|
465
|
+
|
|
466
|
+
Maps to [All Channels - Volumes by Channel](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-volume-by-channel/)
|
|
467
|
+
|
|
468
|
+
| Parameter | Type | Description | Example |
|
|
469
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
470
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
471
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
472
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
473
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
474
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
475
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
476
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
477
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
478
|
+
|
|
479
|
+
```ruby
|
|
480
|
+
response = client.get_conversations_channel_volumes
|
|
481
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"chat\":0,\"email\":62,\"phone\":0}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"chat\":0,\"email\":69,\"phone\":0}]}"
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
#### get_conversations_busiest_times
|
|
485
|
+
|
|
486
|
+
The busiest time of day report provides a summary of which days and times had the highest coversation volume. Days/hours are reported using the company’s time zone.
|
|
487
|
+
|
|
488
|
+
Maps to [Conversations - Busiest Time of Day](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-busy-times/)
|
|
489
|
+
|
|
490
|
+
| Parameter | Type | Description | Example |
|
|
491
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
492
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
493
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
494
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
495
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
496
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
497
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
498
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
499
|
+
|
|
500
|
+
```ruby
|
|
501
|
+
response = client.get_conversations_busiest_times
|
|
502
|
+
# =>
|
|
503
|
+
# [ {
|
|
504
|
+
# "day" : 1,
|
|
505
|
+
# "hour" : 0,
|
|
506
|
+
# "count" : 3
|
|
507
|
+
# }, {
|
|
508
|
+
# "day" : 1,
|
|
509
|
+
# "hour" : 1,
|
|
510
|
+
# "count" : 2
|
|
511
|
+
# }, {
|
|
512
|
+
# "day" : 7,
|
|
513
|
+
# "hour" : 22,
|
|
514
|
+
# "count" : 12
|
|
515
|
+
# }, {
|
|
516
|
+
# "day" : 7,
|
|
517
|
+
# "hour" : 23,
|
|
518
|
+
# "count" : 4
|
|
519
|
+
# } ]
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
#### get_conversations_drilldown
|
|
523
|
+
|
|
524
|
+
This report is similar to the Conversations Report, but instead of returning statistics about conversation volume, it drills down and returns the conversation data that makes up the Conversations Report.
|
|
525
|
+
|
|
526
|
+
Maps to [Conversations - Drilldown](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-drilldown/)
|
|
527
|
+
|
|
528
|
+
| Parameter | Type | Description | Example |
|
|
529
|
+
| :----------- | :------------ | :----------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
|
530
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
531
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
532
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
533
|
+
| `rows` | `number` | Number of result to return per page; defaults to 25; maximum is 50 | `rows: 30` |
|
|
534
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
535
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
536
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
537
|
+
|
|
538
|
+
```ruby
|
|
539
|
+
response = client.get_conversations_drilldown
|
|
540
|
+
# =>
|
|
541
|
+
# {
|
|
542
|
+
# "conversations" : {
|
|
543
|
+
# "pages" : 157,
|
|
544
|
+
# "page" : 1,
|
|
545
|
+
# "count" : 1561,
|
|
546
|
+
# "results" : [ {
|
|
547
|
+
# "id" : 583,
|
|
548
|
+
# "number" : 12345,
|
|
549
|
+
# "type" : "email",
|
|
550
|
+
# "mailboxid" : 2,
|
|
551
|
+
# "attachments" : false,
|
|
552
|
+
# "subject" : "Sample subject",
|
|
553
|
+
# "status" : "active",
|
|
554
|
+
# "threadCount" : 6,
|
|
555
|
+
# "preview" : "This is a preview...",
|
|
556
|
+
# "customerName" : "John Smith",
|
|
557
|
+
# "customerEmail" : "john@example.com",
|
|
558
|
+
# "customerIds" : [ 2 ],
|
|
559
|
+
# "modifiedAt" : "2015-04-24T18:59:49Z",
|
|
560
|
+
# "assignedid" : 4,
|
|
561
|
+
# "tags" : [ {
|
|
562
|
+
# "id" : 123,
|
|
563
|
+
# "name" : "sample-tag",
|
|
564
|
+
# "color" : "none"
|
|
565
|
+
# } ],
|
|
566
|
+
# "assignedName" : "Mary Jones"
|
|
567
|
+
# } ]
|
|
568
|
+
# }
|
|
569
|
+
# }
|
|
570
|
+
```
|
|
571
|
+
|
|
572
|
+
#### get_conversations_drilldown_by_field
|
|
573
|
+
|
|
574
|
+
This report is similar to the Conversations Report, but instead of returning statistics about conversation volume, it drills down and returns the conversation data (by conversation field) that makes up the Conversations Report.
|
|
575
|
+
|
|
576
|
+
Maps to [Conversations - Drilldown by Field](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-field-drilldown/)
|
|
577
|
+
|
|
578
|
+
| Parameter | Type | Description | Example |
|
|
579
|
+
| :----------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
|
580
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
581
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
582
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
583
|
+
| `rows` | `number` | Number of result to return per page; defaults to 25; maximum is 50 | `rows: 30` |
|
|
584
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
585
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
586
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
587
|
+
| `field` | `enumeration` | Field to drill down; valid values: _tagid (for tags), replyid (for saved replies), workflowid (for workflows), customerid (for most active customers)_ **Defaults to customerid** | `field: customerid` |
|
|
588
|
+
| `field_id` | `number` | The identifier on which to drill down; can be an identifier representing a tag, saved reply, workflow, or customer | `field_id: 2` |
|
|
589
|
+
|
|
590
|
+
```ruby
|
|
591
|
+
response = client.get_conversations_drilldown_by_field
|
|
592
|
+
# =>
|
|
593
|
+
# {
|
|
594
|
+
# "conversations" : {
|
|
595
|
+
# "pages" : 157,
|
|
596
|
+
# "page" : 1,
|
|
597
|
+
# "count" : 1561,
|
|
598
|
+
# "results" : [ {
|
|
599
|
+
# "id" : 583,
|
|
600
|
+
# "number" : 12345,
|
|
601
|
+
# "type" : "email",
|
|
602
|
+
# "mailboxid" : 2,
|
|
603
|
+
# "attachments" : false,
|
|
604
|
+
# "subject" : "Sample subject",
|
|
605
|
+
# "status" : "active",
|
|
606
|
+
# "threadCount" : 6,
|
|
607
|
+
# "preview" : "This is a preview...",
|
|
608
|
+
# "customerName" : "John Smith",
|
|
609
|
+
# "customerEmail" : "john@example.com",
|
|
610
|
+
# "customerIds" : [ 2 ],
|
|
611
|
+
# "modifiedAt" : "2015-04-24T18:59:49Z",
|
|
612
|
+
# "assignedid" : 4,
|
|
613
|
+
# "tags" : [ {
|
|
614
|
+
# "id" : 123,
|
|
615
|
+
# "name" : "sample-tag",
|
|
616
|
+
# "color" : "none"
|
|
617
|
+
# } ],
|
|
618
|
+
# "assignedName" : "Mary Jones"
|
|
619
|
+
# } ]
|
|
620
|
+
# }
|
|
621
|
+
# }
|
|
622
|
+
```
|
|
623
|
+
|
|
624
|
+
#### get_conversations_new_conversations_drilldown
|
|
625
|
+
|
|
626
|
+
This report is similar to the New Conversations Report, but instead of returning statistics about new conversation volume, it drills down and returns the actual new conversations that makes up the New Conversations Report.
|
|
627
|
+
|
|
628
|
+
Maps to [Conversations - New Conversations Drilldown](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-new-drilldown/)
|
|
629
|
+
|
|
630
|
+
| Parameter | Type | Description | Example |
|
|
631
|
+
| :----------- | :------------ | :----------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
|
632
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
633
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
634
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
635
|
+
| `rows` | `number` | Number of result to return per page; defaults to 25; maximum is 50 | `rows: 30` |
|
|
636
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
637
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
638
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
639
|
+
|
|
640
|
+
```ruby
|
|
641
|
+
response = client.get_conversations_new_conversations_drilldown
|
|
642
|
+
# =>
|
|
643
|
+
# {
|
|
644
|
+
# "conversations" : {
|
|
645
|
+
# "pages" : 157,
|
|
646
|
+
# "page" : 1,
|
|
647
|
+
# "count" : 1561,
|
|
648
|
+
# "results" : [ {
|
|
649
|
+
# "id" : 583,
|
|
650
|
+
# "number" : 12345,
|
|
651
|
+
# "type" : "email",
|
|
652
|
+
# "mailboxid" : 2,
|
|
653
|
+
# "attachments" : false,
|
|
654
|
+
# "subject" : "Sample subject",
|
|
655
|
+
# "status" : "active",
|
|
656
|
+
# "threadCount" : 6,
|
|
657
|
+
# "preview" : "This is a preview...",
|
|
658
|
+
# "customerName" : "John Smith",
|
|
659
|
+
# "customerEmail" : "john@example.com",
|
|
660
|
+
# "customerIds" : [ 2 ],
|
|
661
|
+
# "modifiedAt" : "2015-04-24T18:59:49Z",
|
|
662
|
+
# "assignedid" : 4,
|
|
663
|
+
# "tags" : [ {
|
|
664
|
+
# "id" : 123,
|
|
665
|
+
# "name" : "sample-tag",
|
|
666
|
+
# "color" : "none"
|
|
667
|
+
# } ],
|
|
668
|
+
# "assignedName" : "Mary Jones"
|
|
669
|
+
# } ]
|
|
670
|
+
# }
|
|
671
|
+
# }
|
|
672
|
+
```
|
|
673
|
+
|
|
674
|
+
#### get_conversations_received_message_stats
|
|
675
|
+
|
|
676
|
+
The received messages report provides a summary of the volume of received messages over a given time range. Only messages from customers are counted.
|
|
677
|
+
|
|
678
|
+
Maps to [Conversations - Received Messages Statistics](https://developer.helpscout.com/mailbox-api/endpoints/reports/conversations/reports-conversations-received-messages/)
|
|
679
|
+
|
|
680
|
+
| Parameter | Type | Description | Example |
|
|
681
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
682
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
683
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
684
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
685
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
686
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
687
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
688
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
689
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
690
|
+
|
|
691
|
+
```ruby
|
|
692
|
+
response = client.get_conversations_received_message_stats
|
|
693
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"messages\":126}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"messages\":146}]}"
|
|
694
|
+
```
|
|
695
|
+
|
|
696
|
+
### Doc Reports
|
|
697
|
+
|
|
698
|
+
#### get_docs
|
|
699
|
+
|
|
700
|
+
The Docs report provides statistics about Docs usage (searches, top articles, etc.) over a given time range. You may optionally specify two time ranges to see how usage changed between the two ranges.
|
|
701
|
+
|
|
702
|
+
Maps to [Docs Overall Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/docs/reports-docs-overall/)
|
|
703
|
+
|
|
704
|
+
| Parameter | Type | Description | Example |
|
|
705
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
|
|
706
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
707
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
708
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
709
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
710
|
+
| `sites` | `string` | List of comma separated docs site IDs | `sites: 5215163545667acd25394b5c or sites:5215163545667acd25394b5c,5214c77c45667acd25394b51` |
|
|
711
|
+
|
|
712
|
+
```ruby
|
|
713
|
+
response = client.get_docs
|
|
714
|
+
# =>
|
|
715
|
+
# {
|
|
716
|
+
# "current" : {
|
|
717
|
+
# "visitors" : 10723,
|
|
718
|
+
# "browseAction" : 88.94575230296827,
|
|
719
|
+
# "sentAnEmailResult" : 0.3450526904784109,
|
|
720
|
+
# "foundAnAnswerResult" : 72.93667816842301,
|
|
721
|
+
# "searchAction" : 11.05424769703173,
|
|
722
|
+
# "failedResult" : 26.71826914109857,
|
|
723
|
+
# "docsViewedPerVisit" : 0.9329443525211182
|
|
724
|
+
# },
|
|
725
|
+
# "popularSearches" : [ {
|
|
726
|
+
# "count" : 22,
|
|
727
|
+
# "id" : "pricing",
|
|
728
|
+
# "results" : 4
|
|
729
|
+
# }, {
|
|
730
|
+
# "count" : 21,
|
|
731
|
+
# "id" : "beacon",
|
|
732
|
+
# "results" : 9
|
|
733
|
+
# } ],
|
|
734
|
+
# "failedSearches" : [ {
|
|
735
|
+
# "count" : 2,
|
|
736
|
+
# "id" : "knowlege"
|
|
737
|
+
# }, {
|
|
738
|
+
# "count" : 1,
|
|
739
|
+
# "id" : "auto-advance"
|
|
740
|
+
# } ],
|
|
741
|
+
# "topArticles" : [ {
|
|
742
|
+
# "count" : 2295,
|
|
743
|
+
# "name" : "Email commands ",
|
|
744
|
+
# "siteId" : "52244cc53e3e9bd67a3dc68c",
|
|
745
|
+
# "id" : "524db929e400c2199a391f39",
|
|
746
|
+
# "collectionId" : "524491b4e4b0145597daf4e4"
|
|
747
|
+
# } ],
|
|
748
|
+
# "topCategories" : [ {
|
|
749
|
+
# "count" : 1153,
|
|
750
|
+
# "name" : "Productivity",
|
|
751
|
+
# "siteId" : "52444cc53e3e9bd67a3dc28c",
|
|
752
|
+
# "id" : "52b5a3b6e4b0a3b4e5ec64d3",
|
|
753
|
+
# "articles" : 20
|
|
754
|
+
# }, {
|
|
755
|
+
# "count" : 790,
|
|
756
|
+
# "name" : "Copying Email to Help Scout",
|
|
757
|
+
# "siteId" : "52444cc53e3e9bd67b3dc68c",
|
|
758
|
+
# "id" : "52548414e4b0772073dac6d0",
|
|
759
|
+
# "articles" : 17
|
|
760
|
+
# } ],
|
|
761
|
+
# "deltas" : {
|
|
762
|
+
# "failedResult" : 2.4021178109331593,
|
|
763
|
+
# "docsViewedPerVisit" : 2.561943903720043,
|
|
764
|
+
# "foundAnAnswerResult" : -2.7056392137487535,
|
|
765
|
+
# "visitors" : -14.622392395035643,
|
|
766
|
+
# "browseAction" : -2.154856275773497,
|
|
767
|
+
# "searchAction" : 2.1548562757735183,
|
|
768
|
+
# "sentAnEmailResult" : 0.30352140281560414
|
|
769
|
+
# }
|
|
770
|
+
# }
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
### Happiness Reports
|
|
774
|
+
|
|
775
|
+
#### get_happiness
|
|
776
|
+
|
|
777
|
+
The happiness report provides information about how many Great, Okay, and Not Good ratings your company received for each period in a specified time range. You may optionally specify two time ranges to see how happiness ratings changed between the two time ranges.
|
|
778
|
+
|
|
779
|
+
Maps to [Happiness Overall Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/happiness/reports-happiness-overall/)
|
|
780
|
+
|
|
781
|
+
| Parameter | Type | Description | Example |
|
|
782
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
783
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
784
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
785
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
786
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
787
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
788
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
789
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
790
|
+
|
|
791
|
+
```ruby
|
|
792
|
+
response = client.get_happiness
|
|
793
|
+
# =>
|
|
794
|
+
# {
|
|
795
|
+
# "current" : {
|
|
796
|
+
# "ratingsPercent" : 35.77981651376147,
|
|
797
|
+
# "okay" : 30.909090909090907,
|
|
798
|
+
# "great" : 37.27272727272727,
|
|
799
|
+
# "happinessScore" : 5.454545454545457,
|
|
800
|
+
# "okayCount" : 34,
|
|
801
|
+
# "totalCustomersWithRatings" : 39,
|
|
802
|
+
# "notGoodCount" : 35,
|
|
803
|
+
# "ratingsCount" : 110,
|
|
804
|
+
# "notGood" : 31.818181818181817,
|
|
805
|
+
# "greatCount" : 41,
|
|
806
|
+
# "totalCustomers" : 109
|
|
807
|
+
# },
|
|
808
|
+
# "previous" : {
|
|
809
|
+
# "ratingsPercent" : 32.03047366677708,
|
|
810
|
+
# "great" : 31.65735567970205,
|
|
811
|
+
# "okay" : 36.49906890130354,
|
|
812
|
+
# "happinessScore" : -0.1862197392923619,
|
|
813
|
+
# "okayCount" : 392,
|
|
814
|
+
# "totalCustomersWithRatings" : 967,
|
|
815
|
+
# "notGoodCount" : 342,
|
|
816
|
+
# "ratingsCount" : 1074,
|
|
817
|
+
# "notGood" : 31.843575418994412,
|
|
818
|
+
# "greatCount" : 340,
|
|
819
|
+
# "totalCustomers" : 3019
|
|
820
|
+
# },
|
|
821
|
+
# "deltas" : {
|
|
822
|
+
# "okay" : -5.589977992212631,
|
|
823
|
+
# "great" : 5.615371593025223,
|
|
824
|
+
# "okayCount" : -91.3265306122449,
|
|
825
|
+
# "happinessScore" : 5.640765193837819,
|
|
826
|
+
# "notGoodCount" : -89.76608187134502,
|
|
827
|
+
# "notGood" : -0.02539360081259545,
|
|
828
|
+
# "greatCount" : -87.94117647058823
|
|
829
|
+
# }
|
|
830
|
+
# }
|
|
831
|
+
```
|
|
832
|
+
|
|
833
|
+
#### get_happiness_ratings
|
|
834
|
+
|
|
835
|
+
The happiness ratings report provides a company’s ratings for over a specified time range.
|
|
836
|
+
|
|
837
|
+
Maps to [Happiness Ratings Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/happiness/reports-happiness-ratings/)
|
|
838
|
+
|
|
839
|
+
| Parameter | Type | Description | Example |
|
|
840
|
+
| :----------- | :------------ | :----------------------------------------------------------------------------------------------- | :--------------------------------------- |
|
|
841
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
842
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
843
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
844
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
845
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
846
|
+
| `sort_field` | `enumeration` | Must be one of _number, modifiedAt, rating_ **Defaults to rating** | `sort_field: rating` |
|
|
847
|
+
| `sort_order` | `enumeration` | Must be one of _ASC or DESC_ **Defaults to ASC** | `sort_order: ASC` |
|
|
848
|
+
| `rating` | `enumeration` | Rating to filter on, valid values are: _great, ok, all, not-good_ | `rating: great` |
|
|
849
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
850
|
+
|
|
851
|
+
```ruby
|
|
852
|
+
response = client.get_happiness_ratings
|
|
853
|
+
# =>
|
|
854
|
+
# {
|
|
855
|
+
# "results" : [ {
|
|
856
|
+
# "number" : 222043,
|
|
857
|
+
# "threadid" : 1169815634,
|
|
858
|
+
# "threadCreatedAt" : "2017-09-15T11:57:14Z",
|
|
859
|
+
# "id" : 432207336,
|
|
860
|
+
# "type" : "email",
|
|
861
|
+
# "ratingId" : 1,
|
|
862
|
+
# "ratingCustomerId" : 121198824,
|
|
863
|
+
# "ratingComments" : "Thanks for the clear reply, Amanda!",
|
|
864
|
+
# "ratingCreatedAt" : "2017-09-15T12:26:53Z",
|
|
865
|
+
# "ratingCustomerName" : "Alexander the Great",
|
|
866
|
+
# "ratingUserId" : 69013,
|
|
867
|
+
# "ratingUserName" : "Amanda Herrington"
|
|
868
|
+
# }, {
|
|
869
|
+
# "number" : 226983,
|
|
870
|
+
# "threadid" : 1169298612,
|
|
871
|
+
# "threadCreatedAt" : "2017-09-15T03:52:30Z",
|
|
872
|
+
# "id" : 432031326,
|
|
873
|
+
# "type" : "email",
|
|
874
|
+
# "ratingId" : 1,
|
|
875
|
+
# "ratingCustomerId" : 121972376,
|
|
876
|
+
# "ratingComments" : "Super helpful!",
|
|
877
|
+
# "ratingCreatedAt" : "2017-09-15T14:54:27Z",
|
|
878
|
+
# "ratingCustomerName" : "Mikey Mikelson",
|
|
879
|
+
# "ratingUserId" : 76859,
|
|
880
|
+
# "ratingUserName" : "Shawna Herring"
|
|
881
|
+
# } ],
|
|
882
|
+
# "page" : 1,
|
|
883
|
+
# "count" : 100,
|
|
884
|
+
# "pages" : 2
|
|
885
|
+
# }
|
|
886
|
+
```
|
|
887
|
+
|
|
888
|
+
### Productivity Reports
|
|
889
|
+
|
|
890
|
+
#### get_productivity
|
|
891
|
+
|
|
892
|
+
The productivity report provides a snapshot of productivity over a given time range. You may optionally specify two time ranges to see how productivity changed between the two ranges.
|
|
893
|
+
|
|
894
|
+
If you would like to see the conversation data that make up this report, please use the Company Drilldown endpoint
|
|
895
|
+
|
|
896
|
+
Maps to [Productivity Overall Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-overall/)
|
|
897
|
+
|
|
898
|
+
| Parameter | Type | Description | Example |
|
|
899
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
900
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
901
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
902
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
903
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
904
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
905
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
906
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
907
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
908
|
+
|
|
909
|
+
```ruby
|
|
910
|
+
response = client.get_productivity
|
|
911
|
+
# =>
|
|
912
|
+
# {
|
|
913
|
+
# "filterTags" : [ {
|
|
914
|
+
# "id" : 123,
|
|
915
|
+
# "name" : "sample-tag"
|
|
916
|
+
# } ],
|
|
917
|
+
# "current" : {
|
|
918
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
919
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
920
|
+
# "totalConversations" : 1,
|
|
921
|
+
# "resolutionTime" : 2278004.0,
|
|
922
|
+
# "repliesToResolve" : 2.0,
|
|
923
|
+
# "responseTime" : 2278004,
|
|
924
|
+
# "firstResponseTime" : 2278004,
|
|
925
|
+
# "resolved" : 1,
|
|
926
|
+
# "resolvedOnFirstReply" : 0,
|
|
927
|
+
# "closed" : 94,
|
|
928
|
+
# "repliesSent" : 62,
|
|
929
|
+
# "handleTime" : 6,
|
|
930
|
+
# "percentResolvedOnFirstReply" : 0.0
|
|
931
|
+
# },
|
|
932
|
+
# "previous" : {
|
|
933
|
+
# "startDate" : "2014-01-01T00:00:00Z",
|
|
934
|
+
# "endDate" : "2014-01-31T23:59:59Z",
|
|
935
|
+
# "totalConversations" : 14,
|
|
936
|
+
# "resolutionTime" : 6531211.714285715,
|
|
937
|
+
# "repliesToResolve" : 2.2142857142857144,
|
|
938
|
+
# "responseTime" : 4850412,
|
|
939
|
+
# "firstResponseTime" : 5138913,
|
|
940
|
+
# "resolved" : 14,
|
|
941
|
+
# "resolvedOnFirstReply" : 5,
|
|
942
|
+
# "closed" : 49,
|
|
943
|
+
# "repliesSent" : 636,
|
|
944
|
+
# "handleTime" : 0,
|
|
945
|
+
# "percentResolvedOnFirstReply" : 0.35714285714285715
|
|
946
|
+
# },
|
|
947
|
+
# "deltas" : {
|
|
948
|
+
# "totalConversations" : -92.85714285714286,
|
|
949
|
+
# "repliesSent" : -90.25157232704403,
|
|
950
|
+
# "firstResponseTime" : -55.67148149813006,
|
|
951
|
+
# "resolved" : -92.85714285714286,
|
|
952
|
+
# "repliesToResolve" : -9.677419354838712,
|
|
953
|
+
# "closed" : 91.83673469387755,
|
|
954
|
+
# "resolvedOnFirstReply" : -100.0,
|
|
955
|
+
# "responseTime" : -53.03483497896673,
|
|
956
|
+
# "handleTime" : 0.0,
|
|
957
|
+
# "resolutionTime" : -65.12126539984419
|
|
958
|
+
# },
|
|
959
|
+
# "responseTime" : {
|
|
960
|
+
# "count" : 1,
|
|
961
|
+
# "previousCount" : 14,
|
|
962
|
+
# "ranges" : [ {
|
|
963
|
+
# "id" : 10,
|
|
964
|
+
# "count" : 1,
|
|
965
|
+
# "previousCount" : 12,
|
|
966
|
+
# "percent" : 100.0,
|
|
967
|
+
# "previousPercent" : 85.71428571428571
|
|
968
|
+
# } ]
|
|
969
|
+
# },
|
|
970
|
+
# "handleTime" : {
|
|
971
|
+
# "count" : 1,
|
|
972
|
+
# "previousCount" : 14,
|
|
973
|
+
# "ranges" : [ {
|
|
974
|
+
# "id" : 1,
|
|
975
|
+
# "count" : 1,
|
|
976
|
+
# "previousCount" : 14,
|
|
977
|
+
# "percent" : 100.0,
|
|
978
|
+
# "previousPercent" : 100.0
|
|
979
|
+
# } ]
|
|
980
|
+
# },
|
|
981
|
+
# "firstResponseTime" : {
|
|
982
|
+
# "count" : 1,
|
|
983
|
+
# "previousCount" : 14,
|
|
984
|
+
# "ranges" : [ {
|
|
985
|
+
# "id" : 10,
|
|
986
|
+
# "count" : 1,
|
|
987
|
+
# "previousCount" : 12,
|
|
988
|
+
# "percent" : 100.0,
|
|
989
|
+
# "previousPercent" : 85.71428571428571
|
|
990
|
+
# } ]
|
|
991
|
+
# },
|
|
992
|
+
# "repliesToResolve" : {
|
|
993
|
+
# "count" : 1,
|
|
994
|
+
# "previousCount" : 14,
|
|
995
|
+
# "ranges" : [ {
|
|
996
|
+
# "id" : 2,
|
|
997
|
+
# "count" : 1,
|
|
998
|
+
# "previousCount" : 4,
|
|
999
|
+
# "percent" : 100.0,
|
|
1000
|
+
# "previousPercent" : 28.57142857142857,
|
|
1001
|
+
# "resolutionTime" : 2278004
|
|
1002
|
+
# } ]
|
|
1003
|
+
# }
|
|
1004
|
+
# }
|
|
1005
|
+
```
|
|
1006
|
+
|
|
1007
|
+
#### get_productivity_first_response_time
|
|
1008
|
+
|
|
1009
|
+
This report provides average first response times for each period in a specified time range. You may optionally specify two time ranges to see how first response time changed between the two ranges.
|
|
1010
|
+
|
|
1011
|
+
Maps to [Productivity - First Response Time](https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-first-response-time/)
|
|
1012
|
+
|
|
1013
|
+
| Parameter | Type | Description | Example |
|
|
1014
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1015
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1016
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1017
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1018
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1019
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1020
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1021
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1022
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1023
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1024
|
+
|
|
1025
|
+
```ruby
|
|
1026
|
+
response = client.get_productivity_first_response_time
|
|
1027
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"time\":77134}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"time\":160951}]}"
|
|
1028
|
+
```
|
|
1029
|
+
|
|
1030
|
+
#### get_productivity_replies_sent
|
|
1031
|
+
|
|
1032
|
+
This report provides the number of replies sent for each period in a specified time range. You may optionally specify two time ranges to see how the number of replies sent changed between the two ranges.
|
|
1033
|
+
|
|
1034
|
+
Maps to [Productivity - Replies Sent](https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-replies-sent/)
|
|
1035
|
+
|
|
1036
|
+
| Parameter | Type | Description | Example |
|
|
1037
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1038
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1039
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1040
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1041
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1042
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1043
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1044
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1045
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1046
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1047
|
+
|
|
1048
|
+
```ruby
|
|
1049
|
+
response = client.get_productivity_replies_sent
|
|
1050
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"replies\":86}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"replies\":109}]}"
|
|
1051
|
+
```
|
|
1052
|
+
|
|
1053
|
+
#### get_productivity_resolution_time
|
|
1054
|
+
|
|
1055
|
+
This report provides average resolution times for each period in a specified time range. You may optionally specify two time ranges to see how average resolution time changed between the two ranges.
|
|
1056
|
+
|
|
1057
|
+
Maps to [Productivity - Resolution Time](https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-resolution-time/)
|
|
1058
|
+
|
|
1059
|
+
| Parameter | Type | Description | Example |
|
|
1060
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1061
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1062
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1063
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1064
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1065
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1066
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1067
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1068
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1069
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1070
|
+
|
|
1071
|
+
```ruby
|
|
1072
|
+
response = client.get_productivity_resolution_time
|
|
1073
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"time\":423588}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"time\":642356}]}"
|
|
1074
|
+
```
|
|
1075
|
+
|
|
1076
|
+
#### get_productivity_resolved
|
|
1077
|
+
|
|
1078
|
+
This report provides the number of resolved conversations for each period in a specified time range. You may optionally specify two time ranges to see how the number of resolved conversations changed between the two ranges.
|
|
1079
|
+
|
|
1080
|
+
Maps to [Productivity - Resolved](https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-resolved/)
|
|
1081
|
+
|
|
1082
|
+
| Parameter | Type | Description | Example |
|
|
1083
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1084
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1085
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1086
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1087
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1088
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1089
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1090
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1091
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1092
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1093
|
+
|
|
1094
|
+
```ruby
|
|
1095
|
+
response = client.get_productivity_resolved
|
|
1096
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"resolved\":49}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"resolved\":47}]}"
|
|
1097
|
+
```
|
|
1098
|
+
|
|
1099
|
+
#### get_productivity_response_time
|
|
1100
|
+
|
|
1101
|
+
This report provides average response times for each period in a specified time range. You may optionally specify two time ranges to see how response time changed between the two ranges.
|
|
1102
|
+
|
|
1103
|
+
Maps to [Productivity - Response Time](https://developer.helpscout.com/mailbox-api/endpoints/reports/productivity/reports-productivity-respose-time/)
|
|
1104
|
+
|
|
1105
|
+
| Parameter | Type | Description | Example |
|
|
1106
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1107
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1108
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1109
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1110
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1111
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1112
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1113
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1114
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1115
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1116
|
+
|
|
1117
|
+
```ruby
|
|
1118
|
+
response = client.get_productivity_response_time
|
|
1119
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"time\":82731}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"time\":115673}]}"
|
|
1120
|
+
```
|
|
1121
|
+
|
|
1122
|
+
### User Report
|
|
1123
|
+
|
|
1124
|
+
#### get_user
|
|
1125
|
+
|
|
1126
|
+
Please note that if a team ID is used instead of an user ID, the report calculates summary data for all team members.
|
|
1127
|
+
|
|
1128
|
+
The report provides a snapshot of a user or team activity over a specified time range. You may optionally specify two time ranges to see how activity changed between the two ranges.
|
|
1129
|
+
|
|
1130
|
+
Maps to [User/Team Overall Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user/)
|
|
1131
|
+
|
|
1132
|
+
| Parameter | Type | Description | Example |
|
|
1133
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1134
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1135
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1136
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1137
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1138
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1139
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1140
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1141
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1142
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1143
|
+
|
|
1144
|
+
```ruby
|
|
1145
|
+
response = client.get_user
|
|
1146
|
+
# =>
|
|
1147
|
+
# {
|
|
1148
|
+
# "filterTags" : [ {
|
|
1149
|
+
# "id" : 123,
|
|
1150
|
+
# "name" : "sample-tag"
|
|
1151
|
+
# } ],
|
|
1152
|
+
# "user" : {
|
|
1153
|
+
# "id" : 4,
|
|
1154
|
+
# "hasPhoto" : true,
|
|
1155
|
+
# "createdAt" : "2010-09-03T15:55:48Z",
|
|
1156
|
+
# "name" : "John Smith",
|
|
1157
|
+
# "totalCustomersHelped" : 6580,
|
|
1158
|
+
# "photoUrl" : "http://example.com/pic.jpg"
|
|
1159
|
+
# },
|
|
1160
|
+
# "current" : {
|
|
1161
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
1162
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
1163
|
+
# "totalDays" : 30,
|
|
1164
|
+
# "resolved" : 1,
|
|
1165
|
+
# "conversationsCreated" : 15,
|
|
1166
|
+
# "closed" : 3,
|
|
1167
|
+
# "totalReplies" : 58,
|
|
1168
|
+
# "resolvedOnFirstReply" : 0,
|
|
1169
|
+
# "percentResolvedOnFirstReply" : 0.0,
|
|
1170
|
+
# "repliesToResolve" : 2.0,
|
|
1171
|
+
# "handleTime" : 78.96,
|
|
1172
|
+
# "happinessScore" : 66.66666666666666,
|
|
1173
|
+
# "responseTime" : 2278004,
|
|
1174
|
+
# "resolutionTime" : 2278004.0,
|
|
1175
|
+
# "repliesPerDay" : 1.9333333333333333,
|
|
1176
|
+
# "customersHelped" : 26,
|
|
1177
|
+
# "totalConversations" : 19,
|
|
1178
|
+
# "conversationsPerDay" : 0.6333333333333333,
|
|
1179
|
+
# "busiestDay" : 5
|
|
1180
|
+
# },
|
|
1181
|
+
# "previous" : {
|
|
1182
|
+
# "startDate" : "2014-01-01T00:00:00Z",
|
|
1183
|
+
# "endDate" : "2014-01-31T23:59:59Z",
|
|
1184
|
+
# "totalDays" : 30,
|
|
1185
|
+
# "resolved" : 12,
|
|
1186
|
+
# "conversationsCreated" : 2,
|
|
1187
|
+
# "closed" : 33,
|
|
1188
|
+
# "totalReplies" : 40,
|
|
1189
|
+
# "resolvedOnFirstReply" : 4,
|
|
1190
|
+
# "percentResolvedOnFirstReply" : 0.3333333333333333,
|
|
1191
|
+
# "repliesToResolve" : 2.1666666666666665,
|
|
1192
|
+
# "handleTime" : 0.0,
|
|
1193
|
+
# "happinessScore" : 23.529411764705884,
|
|
1194
|
+
# "responseTime" : 2357169,
|
|
1195
|
+
# "resolutionTime" : 4318101.5,
|
|
1196
|
+
# "repliesPerDay" : 1.3333333333333333,
|
|
1197
|
+
# "customersHelped" : 16,
|
|
1198
|
+
# "totalConversations" : 42,
|
|
1199
|
+
# "conversationsPerDay" : 0.4
|
|
1200
|
+
# },
|
|
1201
|
+
# "deltas" : {
|
|
1202
|
+
# "totalConversations" : -54.761904761904766,
|
|
1203
|
+
# "customersHelped" : 62.5,
|
|
1204
|
+
# "happinessScore" : 43.13725490196077,
|
|
1205
|
+
# "repliesPerDay" : 45.000000000000014,
|
|
1206
|
+
# "resolvedOnFirstReply" : -100.0,
|
|
1207
|
+
# "handleTime" : 0.0,
|
|
1208
|
+
# "conversationsPerDay" : 58.33333333333333,
|
|
1209
|
+
# "resolved" : -91.66666666666666,
|
|
1210
|
+
# "repliesToResolve" : -7.692307692307687,
|
|
1211
|
+
# "activeConversations" : -54.761904761904766,
|
|
1212
|
+
# "totalReplies" : 44.99999999999999,
|
|
1213
|
+
# "closed" : -90.9090909090909,
|
|
1214
|
+
# "responseTime" : -3.3584779029420475,
|
|
1215
|
+
# "resolutionTime" : -47.245241919394445,
|
|
1216
|
+
# "conversationsCreated" : 650.0
|
|
1217
|
+
# }
|
|
1218
|
+
# }
|
|
1219
|
+
```
|
|
1220
|
+
|
|
1221
|
+
#### get_user_conversation_history
|
|
1222
|
+
|
|
1223
|
+
The conversation history report provides details about a user’s conversations for over a specified time range.
|
|
1224
|
+
|
|
1225
|
+
Maps to [User Conversation History](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-conversation-history/)
|
|
1226
|
+
|
|
1227
|
+
| Parameter | Type | Description | Example |
|
|
1228
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1229
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1230
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1231
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1232
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1233
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1234
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1235
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1236
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1237
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1238
|
+
| `status` | `enumeration` | Conversation status, one of _active, pending, closed_ | `user: 1` |
|
|
1239
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
1240
|
+
| `sort_field` | `enumeration` | Must be one of _number, modifiedAt, rating_ **Defaults to number** | `sort_field: rating` |
|
|
1241
|
+
| `sort_order` | `enumeration` | Must be one of _ASC or DESC_ **Defaults to ASC** | `sort_order: ASC` |
|
|
1242
|
+
|
|
1243
|
+
```ruby
|
|
1244
|
+
response = client.get_user_conversation_history
|
|
1245
|
+
# =>
|
|
1246
|
+
# {
|
|
1247
|
+
# "results" : [ {
|
|
1248
|
+
# "id" : 416351186,
|
|
1249
|
+
# "number" : 222002,
|
|
1250
|
+
# "customers" : [ {
|
|
1251
|
+
# "id" : 138946703,
|
|
1252
|
+
# "name" : "Peter Peters"
|
|
1253
|
+
# } ],
|
|
1254
|
+
# "avgHandleTime" : 279,
|
|
1255
|
+
# "firstResponseTime" : 1878,
|
|
1256
|
+
# "repliesSent" : 1,
|
|
1257
|
+
# "responseTime" : 1878,
|
|
1258
|
+
# "resolveTime" : 1878
|
|
1259
|
+
# }, {
|
|
1260
|
+
# "id" : 4845671933,
|
|
1261
|
+
# "number" : 221955,
|
|
1262
|
+
# "customers" : [ {
|
|
1263
|
+
# "id" : 137966680,
|
|
1264
|
+
# "name" : "Alex Ballena"
|
|
1265
|
+
# } ],
|
|
1266
|
+
# "avgHandleTime" : 154,
|
|
1267
|
+
# "firstResponseTime" : 8307,
|
|
1268
|
+
# "repliesSent" : 1,
|
|
1269
|
+
# "responseTime" : 8307,
|
|
1270
|
+
# "resolveTime" : 8307
|
|
1271
|
+
# } ],
|
|
1272
|
+
# "page" : 1,
|
|
1273
|
+
# "count" : 2303,
|
|
1274
|
+
# "pages" : 20
|
|
1275
|
+
# }
|
|
1276
|
+
```
|
|
1277
|
+
|
|
1278
|
+
#### get_user_customers_helped
|
|
1279
|
+
|
|
1280
|
+
This reports provides the number of customers a user helped for each period in a specified time range. You may optionally specify two time ranges to see how the number of customers helped changed between the two time ranges.
|
|
1281
|
+
|
|
1282
|
+
Maps to [User Customers Helped](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-customer-helped/)
|
|
1283
|
+
|
|
1284
|
+
| Parameter | Type | Description | Example |
|
|
1285
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1286
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1287
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1288
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1289
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1290
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1291
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1292
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1293
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1294
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1295
|
+
|
|
1296
|
+
```ruby
|
|
1297
|
+
response = client.get_user_customers_helped
|
|
1298
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"customers\":17}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"customers\":16}]}"
|
|
1299
|
+
```
|
|
1300
|
+
|
|
1301
|
+
#### get_user_drilldown
|
|
1302
|
+
|
|
1303
|
+
This report is similar to the User Report, but instead of returning statistics about users, it drills down and returns the conversation data that makes up the User Report.
|
|
1304
|
+
|
|
1305
|
+
Maps to [User Drill-down](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-drilldown/)
|
|
1306
|
+
|
|
1307
|
+
| Parameter | Type | Description | Example |
|
|
1308
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1309
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1310
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1311
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1312
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1313
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1314
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1315
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1316
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1317
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
1318
|
+
| `rows` | `number` | Number of result to return per page; defaults to 25; maximum is 50 | `rows: 30` |
|
|
1319
|
+
|
|
1320
|
+
```ruby
|
|
1321
|
+
response = client.get_user_drilldown
|
|
1322
|
+
# =>
|
|
1323
|
+
# {
|
|
1324
|
+
# "conversations" : {
|
|
1325
|
+
# "results" : [ {
|
|
1326
|
+
# "id" : 430221821,
|
|
1327
|
+
# "number" : 226358,
|
|
1328
|
+
# "type" : "email",
|
|
1329
|
+
# "mailboxid" : 85,
|
|
1330
|
+
# "attachments" : false,
|
|
1331
|
+
# "subject" : "Folder Not Appearing",
|
|
1332
|
+
# "status" : "active",
|
|
1333
|
+
# "threadCount" : 3,
|
|
1334
|
+
# "preview" : "Hi Reginald, We actually need this workflow to run on the following condition",
|
|
1335
|
+
# "customerName" : "Owen Freheim",
|
|
1336
|
+
# "modifiedAt" : "2017-09-12T11:22:11Z",
|
|
1337
|
+
# "assignedid" : 0,
|
|
1338
|
+
# "waitingSince" : "2017-09-12T11:22:11Z",
|
|
1339
|
+
# "waitingSinceType" : 2,
|
|
1340
|
+
# "tags" : [ {
|
|
1341
|
+
# "id" : 1277761,
|
|
1342
|
+
# "name" : "folder-refresh",
|
|
1343
|
+
# "color" : "none"
|
|
1344
|
+
# } ]
|
|
1345
|
+
# }, {
|
|
1346
|
+
# "id" : 430120638,
|
|
1347
|
+
# "number" : 226333,
|
|
1348
|
+
# "type" : "email",
|
|
1349
|
+
# "mailboxid" : 85,
|
|
1350
|
+
# "attachments" : true,
|
|
1351
|
+
# "subject" : "Troubles with water level",
|
|
1352
|
+
# "status" : "active",
|
|
1353
|
+
# "threadCount" : 4,
|
|
1354
|
+
# "preview" : "Hey there seems to be an issue with the following levels...",
|
|
1355
|
+
# "customerName" : "Water service",
|
|
1356
|
+
# "modifiedAt" : "2017-09-12T11:23:06Z",
|
|
1357
|
+
# "assignedid" : 0,
|
|
1358
|
+
# "waitingSince" : "2017-09-12T11:21:50Z",
|
|
1359
|
+
# "waitingSinceType" : 2,
|
|
1360
|
+
# "tags" : [ ]
|
|
1361
|
+
# } ],
|
|
1362
|
+
# "page" : 1,
|
|
1363
|
+
# "count" : 101,
|
|
1364
|
+
# "pages" : 2
|
|
1365
|
+
# }
|
|
1366
|
+
# }
|
|
1367
|
+
```
|
|
1368
|
+
|
|
1369
|
+
#### get_user_happiness
|
|
1370
|
+
|
|
1371
|
+
The happiness report provides information about how many Great, Okay, and Not Good ratings a user received for each period in a specified time range. You may optionally specify two time ranges to see how happiness ratings changed between the two time ranges.
|
|
1372
|
+
|
|
1373
|
+
Maps to [User Happiness](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-happiness/)
|
|
1374
|
+
|
|
1375
|
+
| Parameter | Type | Description | Example |
|
|
1376
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1377
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1378
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1379
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1380
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1381
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1382
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1383
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1384
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1385
|
+
|
|
1386
|
+
```ruby
|
|
1387
|
+
response = client.get_user_happiness
|
|
1388
|
+
# =>
|
|
1389
|
+
# {
|
|
1390
|
+
# "filterTags" : [ {
|
|
1391
|
+
# "id" : 123,
|
|
1392
|
+
# "name" : "sample-tag"
|
|
1393
|
+
# } ],
|
|
1394
|
+
# "current" : {
|
|
1395
|
+
# "ratingsPercent" : 35.77981651376147,
|
|
1396
|
+
# "okay" : 30.909090909090907,
|
|
1397
|
+
# "great" : 37.27272727272727,
|
|
1398
|
+
# "happinessScore" : 5.454545454545457,
|
|
1399
|
+
# "okayCount" : 34,
|
|
1400
|
+
# "totalCustomersWithRatings" : 39,
|
|
1401
|
+
# "notGoodCount" : 35,
|
|
1402
|
+
# "ratingsCount" : 110,
|
|
1403
|
+
# "notGood" : 31.818181818181817,
|
|
1404
|
+
# "greatCount" : 41,
|
|
1405
|
+
# "totalCustomers" : 109
|
|
1406
|
+
# },
|
|
1407
|
+
# "previous" : {
|
|
1408
|
+
# "ratingsPercent" : 32.03047366677708,
|
|
1409
|
+
# "great" : 31.65735567970205,
|
|
1410
|
+
# "okay" : 36.49906890130354,
|
|
1411
|
+
# "happinessScore" : -0.1862197392923619,
|
|
1412
|
+
# "okayCount" : 392,
|
|
1413
|
+
# "totalCustomersWithRatings" : 967,
|
|
1414
|
+
# "notGoodCount" : 342,
|
|
1415
|
+
# "ratingsCount" : 1074,
|
|
1416
|
+
# "notGood" : 31.843575418994412,
|
|
1417
|
+
# "greatCount" : 340,
|
|
1418
|
+
# "totalCustomers" : 3019
|
|
1419
|
+
# },
|
|
1420
|
+
# "deltas" : {
|
|
1421
|
+
# "okay" : -5.589977992212631,
|
|
1422
|
+
# "great" : 5.615371593025223,
|
|
1423
|
+
# "okayCount" : -91.3265306122449,
|
|
1424
|
+
# "happinessScore" : 5.640765193837819,
|
|
1425
|
+
# "notGoodCount" : -89.76608187134502,
|
|
1426
|
+
# "notGood" : -0.02539360081259545,
|
|
1427
|
+
# "greatCount" : -87.94117647058823
|
|
1428
|
+
# }
|
|
1429
|
+
# }
|
|
1430
|
+
```
|
|
1431
|
+
|
|
1432
|
+
#### get_user_happiness_drilldown
|
|
1433
|
+
|
|
1434
|
+
The user ratings report provides a user’s ratings for over a specified time range.
|
|
1435
|
+
|
|
1436
|
+
Maps to [User Happiness drilldown](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-happiness-drilldown/)
|
|
1437
|
+
|
|
1438
|
+
| Parameter | Type | Description | Example |
|
|
1439
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1440
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1441
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1442
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1443
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1444
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1445
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1446
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1447
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1448
|
+
| `rating` | `enumeration` | Rating to filter on, valid values are: _great, ok, all, not-good_ | `rating: great` |
|
|
1449
|
+
| `page` | `number` | The page number | `page: 2` |
|
|
1450
|
+
| `sort_field` | `enumeration` | Must be one of _number, modifiedAt, rating_ **Defaults to number** | `sort_field: rating` |
|
|
1451
|
+
| `sort_order` | `enumeration` | Must be one of _ASC or DESC_ **Defaults to ASC** | `sort_order: ASC` |
|
|
1452
|
+
|
|
1453
|
+
```ruby
|
|
1454
|
+
response = client.get_user_happiness_drilldown
|
|
1455
|
+
# =>
|
|
1456
|
+
# {
|
|
1457
|
+
# "results" : [ {
|
|
1458
|
+
# "number" : 214705,
|
|
1459
|
+
# "threadid" : 1149512066,
|
|
1460
|
+
# "threadCreatedAt" : "2017-09-02T11:21:42Z",
|
|
1461
|
+
# "id" : 424890237,
|
|
1462
|
+
# "type" : "email",
|
|
1463
|
+
# "ratingId" : 1,
|
|
1464
|
+
# "ratingCustomerId" : 141147564,
|
|
1465
|
+
# "ratingComments" : "Nice work!",
|
|
1466
|
+
# "ratingCreatedAt" : "2017-09-02T11:23:43Z",
|
|
1467
|
+
# "ratingCustomerName" : "david@loans.net",
|
|
1468
|
+
# "ratingUserId" : 19,
|
|
1469
|
+
# "ratingUserName" : "Denny Matthews"
|
|
1470
|
+
# }, {
|
|
1471
|
+
# "number" : 224713,
|
|
1472
|
+
# "threadid" : 1149511394,
|
|
1473
|
+
# "threadCreatedAt" : "2017-09-02T11:20:31Z",
|
|
1474
|
+
# "id" : 424910211,
|
|
1475
|
+
# "type" : "email",
|
|
1476
|
+
# "ratingId" : 1,
|
|
1477
|
+
# "ratingCustomerId" : 79911899,
|
|
1478
|
+
# "ratingComments" : "Great job",
|
|
1479
|
+
# "ratingCreatedAt" : "2017-09-02T11:28:47Z",
|
|
1480
|
+
# "ratingCustomerName" : "Robert Johnson",
|
|
1481
|
+
# "ratingUserId" : 4,
|
|
1482
|
+
# "ratingUserName" : "Robert Swindle"
|
|
1483
|
+
# } ],
|
|
1484
|
+
# "page" : 1,
|
|
1485
|
+
# "count" : 165,
|
|
1486
|
+
# "pages" : 17
|
|
1487
|
+
# }
|
|
1488
|
+
```
|
|
1489
|
+
|
|
1490
|
+
#### get_user_replies
|
|
1491
|
+
|
|
1492
|
+
This reports provides the number of replies a user sent for each period in a specified time range. You may optionally specify two time ranges to see how the number replies changed between the two time ranges.
|
|
1493
|
+
|
|
1494
|
+
Maps to [User Replies](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-replies/)
|
|
1495
|
+
|
|
1496
|
+
| Parameter | Type | Description | Example |
|
|
1497
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1498
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1499
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1500
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1501
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1502
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1503
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1504
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1505
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1506
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1507
|
+
|
|
1508
|
+
```ruby
|
|
1509
|
+
response = client.get_user_replies
|
|
1510
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"replies\":24}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"replies\":18}]}"
|
|
1511
|
+
```
|
|
1512
|
+
|
|
1513
|
+
#### get_user_resolutions
|
|
1514
|
+
|
|
1515
|
+
This reports provides the number of conversations a user helped resolve for each period in a specified time range. You may optionally specify two time ranges to see how the number of resolved conversations changed between the two time ranges.
|
|
1516
|
+
|
|
1517
|
+
Maps to [User Resolutions](https://developer.helpscout.com/mailbox-api/endpoints/reports/user/reports-user-resolutions/)
|
|
1518
|
+
|
|
1519
|
+
| Parameter | Type | Description | Example |
|
|
1520
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1521
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1522
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1523
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1524
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1525
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1526
|
+
| `types` | `enumeration` | List of comma separated conversation types to filter on, valid values are _email, chat or phone_ | `types: email or types:chat,email,phone` |
|
|
1527
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1528
|
+
| `user` | `number` | User for whom the report is generated **Defaults 1** | `user: 1` |
|
|
1529
|
+
| `view_by` | `enumeration` | Represents the resolution at which data is returned; valid values are: _day, week or month_ | `view_by: day` |
|
|
1530
|
+
|
|
1531
|
+
```ruby
|
|
1532
|
+
response = client.get_user_resolutions
|
|
1533
|
+
# => "{\"current\":[{\"date\":\"2020-03-09T13:30:00Z\",\"resolved\":26}],\"previous\":[{\"date\":\"2020-02-24T13:30:00Z\",\"resolved\":17}]}"
|
|
1534
|
+
```
|
|
1535
|
+
|
|
1536
|
+
### Chat Reports
|
|
1537
|
+
|
|
1538
|
+
#### get_chat
|
|
1539
|
+
|
|
1540
|
+
The Chat report is all about seeing volume, efficiency, and team productivity when using Beacon with live chat over time. If you don’t see the chat report, it means you aren’t using Beacon. Set up a chat-enabled Beacon and give it a spin! Check out Reporting Definitions and Scenarios for the scoop on how these metrics are calculated.
|
|
1541
|
+
|
|
1542
|
+
Third party chat integrations will show a count in the All Channels - Volumes by Channel report as chats, but will not be included in the Chat report. These metrics are available only for chats via Beacon.
|
|
1543
|
+
|
|
1544
|
+
Maps to [Chat Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/chat/)
|
|
1545
|
+
|
|
1546
|
+
| Parameter | Type | Description | Example |
|
|
1547
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1548
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1549
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1550
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1551
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1552
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1553
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1554
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1555
|
+
|
|
1556
|
+
```ruby
|
|
1557
|
+
response = client.get_chat
|
|
1558
|
+
# =>
|
|
1559
|
+
# {
|
|
1560
|
+
# "current" : {
|
|
1561
|
+
# "startDate" : "2019-03-01T12:00:00Z",
|
|
1562
|
+
# "endDate" : "2019-04-01T12:00:00Z",
|
|
1563
|
+
# "volume" : {
|
|
1564
|
+
# "chatConversations" : 255,
|
|
1565
|
+
# "completedChats" : 243,
|
|
1566
|
+
# "missedChats" : 12,
|
|
1567
|
+
# "chatsPerDay" : 8.225806
|
|
1568
|
+
# },
|
|
1569
|
+
# "responses" : {
|
|
1570
|
+
# "waitTime" : 37,
|
|
1571
|
+
# "responseTime" : 0
|
|
1572
|
+
# },
|
|
1573
|
+
# "resolutions" : {
|
|
1574
|
+
# "messagesPerChat" : 16.84252,
|
|
1575
|
+
# "duration" : 927
|
|
1576
|
+
# }
|
|
1577
|
+
# },
|
|
1578
|
+
# "previous" : {
|
|
1579
|
+
# "startDate" : "2019-02-01T12:00:00Z",
|
|
1580
|
+
# "endDate" : "2019-03-01T12:00:00Z",
|
|
1581
|
+
# "volume" : {
|
|
1582
|
+
# "chatConversations" : 212,
|
|
1583
|
+
# "completedChats" : 206,
|
|
1584
|
+
# "missedChats" : 5,
|
|
1585
|
+
# "chatsPerDay" : 7.571429
|
|
1586
|
+
# },
|
|
1587
|
+
# "responses" : {
|
|
1588
|
+
# "waitTime" : 37,
|
|
1589
|
+
# "responseTime" : 66
|
|
1590
|
+
# },
|
|
1591
|
+
# "resolutions" : {
|
|
1592
|
+
# "messagesPerChat" : 15.898551,
|
|
1593
|
+
# "duration" : 935
|
|
1594
|
+
# }
|
|
1595
|
+
# },
|
|
1596
|
+
# "deltas" : {
|
|
1597
|
+
# "volume" : {
|
|
1598
|
+
# "chatConversations" : 20.283018,
|
|
1599
|
+
# "completedChats" : 17.961164,
|
|
1600
|
+
# "missedChats" : 140.0,
|
|
1601
|
+
# "chatsPerDay" : 8.642727
|
|
1602
|
+
# },
|
|
1603
|
+
# "responses" : {
|
|
1604
|
+
# "waitTime" : 0.0,
|
|
1605
|
+
# "responseTime" : -6.060606
|
|
1606
|
+
# },
|
|
1607
|
+
# "resolutions" : {
|
|
1608
|
+
# "messagesPerChat" : 5.937453,
|
|
1609
|
+
# "duration" : -0.85561496
|
|
1610
|
+
# }
|
|
1611
|
+
# },
|
|
1612
|
+
# "waitTime" : {
|
|
1613
|
+
# "count" : 238,
|
|
1614
|
+
# "previousCount" : 196,
|
|
1615
|
+
# "ranges" : [ {
|
|
1616
|
+
# "id" : 1,
|
|
1617
|
+
# "count" : 199,
|
|
1618
|
+
# "percent" : 83.61345,
|
|
1619
|
+
# "previousCount" : 160,
|
|
1620
|
+
# "previousPercent" : 81
|
|
1621
|
+
# }, {
|
|
1622
|
+
# "id" : 2,
|
|
1623
|
+
# "count" : 30,
|
|
1624
|
+
# "percent" : 12.605042,
|
|
1625
|
+
# "previousCount" : 33,
|
|
1626
|
+
# "previousPercent" : 16
|
|
1627
|
+
# }, {
|
|
1628
|
+
# "id" : 3,
|
|
1629
|
+
# "count" : 9,
|
|
1630
|
+
# "percent" : 3.7815125,
|
|
1631
|
+
# "previousCount" : 3,
|
|
1632
|
+
# "previousPercent" : 1
|
|
1633
|
+
# }, {
|
|
1634
|
+
# "id" : 4,
|
|
1635
|
+
# "count" : 0,
|
|
1636
|
+
# "percent" : 0.0,
|
|
1637
|
+
# "previousCount" : 0,
|
|
1638
|
+
# "previousPercent" : 0
|
|
1639
|
+
# }, {
|
|
1640
|
+
# "id" : 5,
|
|
1641
|
+
# "count" : 0,
|
|
1642
|
+
# "percent" : 0.0,
|
|
1643
|
+
# "previousCount" : 0,
|
|
1644
|
+
# "previousPercent" : 0
|
|
1645
|
+
# } ]
|
|
1646
|
+
# },
|
|
1647
|
+
# "responseTime" : {
|
|
1648
|
+
# "count" : 237,
|
|
1649
|
+
# "previousCount" : 183,
|
|
1650
|
+
# "ranges" : [ {
|
|
1651
|
+
# "id" : 1,
|
|
1652
|
+
# "count" : 150,
|
|
1653
|
+
# "percent" : 63.291138,
|
|
1654
|
+
# "previousCount" : 103,
|
|
1655
|
+
# "previousPercent" : 56
|
|
1656
|
+
# }, {
|
|
1657
|
+
# "id" : 2,
|
|
1658
|
+
# "count" : 62,
|
|
1659
|
+
# "percent" : 26.160337,
|
|
1660
|
+
# "previousCount" : 61,
|
|
1661
|
+
# "previousPercent" : 33
|
|
1662
|
+
# }, {
|
|
1663
|
+
# "id" : 3,
|
|
1664
|
+
# "count" : 25,
|
|
1665
|
+
# "percent" : 10.548523,
|
|
1666
|
+
# "previousCount" : 18,
|
|
1667
|
+
# "previousPercent" : 9
|
|
1668
|
+
# }, {
|
|
1669
|
+
# "id" : 4,
|
|
1670
|
+
# "count" : 0,
|
|
1671
|
+
# "percent" : 0.0,
|
|
1672
|
+
# "previousCount" : 1,
|
|
1673
|
+
# "previousPercent" : 0
|
|
1674
|
+
# }, {
|
|
1675
|
+
# "id" : 5,
|
|
1676
|
+
# "count" : 0,
|
|
1677
|
+
# "percent" : 0.0,
|
|
1678
|
+
# "previousCount" : 0,
|
|
1679
|
+
# "previousPercent" : 0
|
|
1680
|
+
# } ]
|
|
1681
|
+
# },
|
|
1682
|
+
# "messagesPerChat" : {
|
|
1683
|
+
# "count" : 254,
|
|
1684
|
+
# "previousCount" : 207,
|
|
1685
|
+
# "ranges" : [ {
|
|
1686
|
+
# "id" : 3,
|
|
1687
|
+
# "count" : 87,
|
|
1688
|
+
# "percent" : 34.25197,
|
|
1689
|
+
# "previousCount" : 61,
|
|
1690
|
+
# "previousPercent" : 29
|
|
1691
|
+
# }, {
|
|
1692
|
+
# "id" : 2,
|
|
1693
|
+
# "count" : 60,
|
|
1694
|
+
# "percent" : 23.622047,
|
|
1695
|
+
# "previousCount" : 40,
|
|
1696
|
+
# "previousPercent" : 19
|
|
1697
|
+
# }, {
|
|
1698
|
+
# "id" : 4,
|
|
1699
|
+
# "count" : 44,
|
|
1700
|
+
# "percent" : 17.322834,
|
|
1701
|
+
# "previousCount" : 37,
|
|
1702
|
+
# "previousPercent" : 17
|
|
1703
|
+
# }, {
|
|
1704
|
+
# "id" : 5,
|
|
1705
|
+
# "count" : 35,
|
|
1706
|
+
# "percent" : 13.779528,
|
|
1707
|
+
# "previousCount" : 23,
|
|
1708
|
+
# "previousPercent" : 11
|
|
1709
|
+
# }, {
|
|
1710
|
+
# "id" : 1,
|
|
1711
|
+
# "count" : 28,
|
|
1712
|
+
# "percent" : 11.0236225,
|
|
1713
|
+
# "previousCount" : 46,
|
|
1714
|
+
# "previousPercent" : 22
|
|
1715
|
+
# } ]
|
|
1716
|
+
# },
|
|
1717
|
+
# "duration" : {
|
|
1718
|
+
# "count" : 238,
|
|
1719
|
+
# "previousCount" : 196,
|
|
1720
|
+
# "ranges" : [ {
|
|
1721
|
+
# "id" : 3,
|
|
1722
|
+
# "count" : 73,
|
|
1723
|
+
# "percent" : 30.67227,
|
|
1724
|
+
# "previousCount" : 49,
|
|
1725
|
+
# "previousPercent" : 25
|
|
1726
|
+
# }, {
|
|
1727
|
+
# "id" : 2,
|
|
1728
|
+
# "count" : 54,
|
|
1729
|
+
# "percent" : 22.689075,
|
|
1730
|
+
# "previousCount" : 49,
|
|
1731
|
+
# "previousPercent" : 25
|
|
1732
|
+
# }, {
|
|
1733
|
+
# "id" : 1,
|
|
1734
|
+
# "count" : 43,
|
|
1735
|
+
# "percent" : 18.067226,
|
|
1736
|
+
# "previousCount" : 40,
|
|
1737
|
+
# "previousPercent" : 20
|
|
1738
|
+
# }, {
|
|
1739
|
+
# "id" : 4,
|
|
1740
|
+
# "count" : 35,
|
|
1741
|
+
# "percent" : 14.705882,
|
|
1742
|
+
# "previousCount" : 28,
|
|
1743
|
+
# "previousPercent" : 14
|
|
1744
|
+
# }, {
|
|
1745
|
+
# "id" : 5,
|
|
1746
|
+
# "count" : 33,
|
|
1747
|
+
# "percent" : 13.865546,
|
|
1748
|
+
# "previousCount" : 30,
|
|
1749
|
+
# "previousPercent" : 15
|
|
1750
|
+
# } ]
|
|
1751
|
+
# }
|
|
1752
|
+
# }
|
|
1753
|
+
```
|
|
1754
|
+
|
|
1755
|
+
### Email Reports
|
|
1756
|
+
|
|
1757
|
+
#### get_email
|
|
1758
|
+
|
|
1759
|
+
The Email report measures efficiency working with email conversations. You’ll be able to keep track of how your team is performing in terms of time spent addressing and responding to conversations. Check out Reporting Definitions and Scenarios for the scoop on how these metrics are calculated.
|
|
1760
|
+
|
|
1761
|
+
Maps to [Email Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/email/)
|
|
1762
|
+
|
|
1763
|
+
| Parameter | Type | Description | Example |
|
|
1764
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1765
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1766
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1767
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1768
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1769
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1770
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1771
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1772
|
+
|
|
1773
|
+
```ruby
|
|
1774
|
+
response = client.get_email
|
|
1775
|
+
# =>
|
|
1776
|
+
# {
|
|
1777
|
+
# "filterTags" : [ {
|
|
1778
|
+
# "id" : 100,
|
|
1779
|
+
# "name" : "vip"
|
|
1780
|
+
# } ],
|
|
1781
|
+
# "current" : {
|
|
1782
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
1783
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
1784
|
+
# "volume" : {
|
|
1785
|
+
# "emailConversations" : 8,
|
|
1786
|
+
# "emailsCreated" : 5,
|
|
1787
|
+
# "repliesSent" : 24,
|
|
1788
|
+
# "messagesReceived" : 40
|
|
1789
|
+
# },
|
|
1790
|
+
# "resolutions" : {
|
|
1791
|
+
# "resolved" : 10,
|
|
1792
|
+
# "resolvedOnFirstReply" : 1,
|
|
1793
|
+
# "percentResolvedOnFirstReply" : 0.1,
|
|
1794
|
+
# "resolutionTime" : 20.5,
|
|
1795
|
+
# "repliesToResolve" : 17.0,
|
|
1796
|
+
# "handleTime" : 129,
|
|
1797
|
+
# "closed" : 20
|
|
1798
|
+
# },
|
|
1799
|
+
# "responses" : {
|
|
1800
|
+
# "responseTime" : 1023,
|
|
1801
|
+
# "firstResponseTime" : 500
|
|
1802
|
+
# }
|
|
1803
|
+
# },
|
|
1804
|
+
# "previous" : {
|
|
1805
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
1806
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
1807
|
+
# "volume" : {
|
|
1808
|
+
# "emailConversations" : 7,
|
|
1809
|
+
# "emailsCreated" : 4,
|
|
1810
|
+
# "repliesSent" : 14,
|
|
1811
|
+
# "messagesReceived" : 20
|
|
1812
|
+
# },
|
|
1813
|
+
# "resolutions" : {
|
|
1814
|
+
# "resolved" : 11,
|
|
1815
|
+
# "resolvedOnFirstReply" : 140,
|
|
1816
|
+
# "percentResolvedOnFirstReply" : 0.2,
|
|
1817
|
+
# "resolutionTime" : 20.4,
|
|
1818
|
+
# "repliesToResolve" : 7.0,
|
|
1819
|
+
# "handleTime" : 110,
|
|
1820
|
+
# "closed" : 19
|
|
1821
|
+
# },
|
|
1822
|
+
# "responses" : {
|
|
1823
|
+
# "responseTime" : 1021,
|
|
1824
|
+
# "firstResponseTime" : 300
|
|
1825
|
+
# }
|
|
1826
|
+
# },
|
|
1827
|
+
# "deltas" : {
|
|
1828
|
+
# "volume" : {
|
|
1829
|
+
# "emailConversations" : 639.2,
|
|
1830
|
+
# "emailsCreated" : 865.0602,
|
|
1831
|
+
# "repliesSent" : 402.4922,
|
|
1832
|
+
# "messagesReceived" : 245.098
|
|
1833
|
+
# },
|
|
1834
|
+
# "resolutions" : {
|
|
1835
|
+
# "resolved" : -15.0,
|
|
1836
|
+
# "resolvedOnFirstReply" : 3.8235,
|
|
1837
|
+
# "resolutionTime" : -99.3841,
|
|
1838
|
+
# "repliesToResolve" : 45.6583,
|
|
1839
|
+
# "handleTime" : -45.5696,
|
|
1840
|
+
# "closed" : -40.678
|
|
1841
|
+
# },
|
|
1842
|
+
# "responses" : {
|
|
1843
|
+
# "responseTime" : -99.0912,
|
|
1844
|
+
# "firstResponseTime" : -99.085
|
|
1845
|
+
# }
|
|
1846
|
+
# },
|
|
1847
|
+
# "responseTime" : {
|
|
1848
|
+
# "count" : 1,
|
|
1849
|
+
# "previousCount" : 14,
|
|
1850
|
+
# "ranges" : [ {
|
|
1851
|
+
# "id" : 10,
|
|
1852
|
+
# "count" : 1,
|
|
1853
|
+
# "percent" : 100.0,
|
|
1854
|
+
# "previousCount" : 12,
|
|
1855
|
+
# "previousPercent" : 85
|
|
1856
|
+
# } ]
|
|
1857
|
+
# },
|
|
1858
|
+
# "handleTime" : {
|
|
1859
|
+
# "count" : 1,
|
|
1860
|
+
# "previousCount" : 14,
|
|
1861
|
+
# "ranges" : [ {
|
|
1862
|
+
# "id" : 1,
|
|
1863
|
+
# "count" : 1,
|
|
1864
|
+
# "percent" : 100.0,
|
|
1865
|
+
# "previousCount" : 14,
|
|
1866
|
+
# "previousPercent" : 100
|
|
1867
|
+
# } ]
|
|
1868
|
+
# },
|
|
1869
|
+
# "firstResponseTime" : {
|
|
1870
|
+
# "count" : 1,
|
|
1871
|
+
# "previousCount" : 14,
|
|
1872
|
+
# "ranges" : [ {
|
|
1873
|
+
# "id" : 10,
|
|
1874
|
+
# "count" : 1,
|
|
1875
|
+
# "percent" : 100.0,
|
|
1876
|
+
# "previousCount" : 12,
|
|
1877
|
+
# "previousPercent" : 85
|
|
1878
|
+
# } ]
|
|
1879
|
+
# },
|
|
1880
|
+
# "resolutionTime" : {
|
|
1881
|
+
# "count" : 17,
|
|
1882
|
+
# "previousCount" : 20,
|
|
1883
|
+
# "ranges" : [ {
|
|
1884
|
+
# "id" : 1,
|
|
1885
|
+
# "count" : 12,
|
|
1886
|
+
# "percent" : 70.588234,
|
|
1887
|
+
# "previousCount" : 5,
|
|
1888
|
+
# "previousPercent" : 25
|
|
1889
|
+
# }, {
|
|
1890
|
+
# "id" : 3,
|
|
1891
|
+
# "count" : 2,
|
|
1892
|
+
# "percent" : 11.764706,
|
|
1893
|
+
# "previousCount" : 1,
|
|
1894
|
+
# "previousPercent" : 5
|
|
1895
|
+
# } ]
|
|
1896
|
+
# },
|
|
1897
|
+
# "repliesToResolve" : {
|
|
1898
|
+
# "count" : 1,
|
|
1899
|
+
# "previousCount" : 14,
|
|
1900
|
+
# "ranges" : [ {
|
|
1901
|
+
# "id" : 2,
|
|
1902
|
+
# "count" : 1,
|
|
1903
|
+
# "percent" : 100.0,
|
|
1904
|
+
# "previousCount" : 4,
|
|
1905
|
+
# "previousPercent" : 28,
|
|
1906
|
+
# "resolutionTime" : 2278004
|
|
1907
|
+
# } ]
|
|
1908
|
+
# }
|
|
1909
|
+
# }
|
|
1910
|
+
```
|
|
1911
|
+
|
|
1912
|
+
### Phone Reports
|
|
1913
|
+
|
|
1914
|
+
#### get_phone
|
|
1915
|
+
|
|
1916
|
+
The Phone report is a very simple and straightforward measure of the volume of phone calls logged in Help Scout. Check out Reporting Definitions and Scenarios for the scoop on how these metrics are calculated.
|
|
1917
|
+
|
|
1918
|
+
Maps to [Phone Report](https://developer.helpscout.com/mailbox-api/endpoints/reports/phone/)
|
|
1919
|
+
|
|
1920
|
+
| Parameter | Type | Description | Example |
|
|
1921
|
+
| :-------------------- | :------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------ |
|
|
1922
|
+
| `start_date` | `utc.iso8601` | Start of the interval **Defaults 1.week.ago.beginning_of_day.utc.iso8601** | `start_date: 2020-03-09T13:30:00Z` |
|
|
1923
|
+
| `end_date` | `utc.iso8601` | End of the interval **DateTime.now.beginning_of_day.utc.iso8601** | `end_date: 2020-03-16T13:30:00Z` |
|
|
1924
|
+
| `previous_start_date` | `utc.iso8601` | Start of the previous interval **Defaults 3.weeks.ago.beginning_of_day.utc.iso8601** | `previous_start_date: 2020-02-24T13:30:00Z` |
|
|
1925
|
+
| `previous_end_date` | `utc.iso8601` | End of the previous interval **Defaults 2.weeks.ago.beginning_of_day.utc.iso8601** | `previous_end_date: 2020-03-02T13:30:00Z` |
|
|
1926
|
+
| `tags` | `number` | List of comma separated ids to filter on tags | `tags:99787 or tags:5666 99787` |
|
|
1927
|
+
| `folders` | `number` | List of comma separated folder ids to filter on folders | `folders: 991 or folders: 991,99` |
|
|
1928
|
+
| `office_hours` | `boolean` | 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 | `office_hours: true` |
|
|
1929
|
+
|
|
1930
|
+
```ruby
|
|
1931
|
+
response = client.get_phone
|
|
1932
|
+
# =>
|
|
1933
|
+
# {
|
|
1934
|
+
# "current" : {
|
|
1935
|
+
# "startDate" : "2015-01-01T00:00:00Z",
|
|
1936
|
+
# "endDate" : "2015-01-31T23:59:59Z",
|
|
1937
|
+
# "phoneConversations" : 11,
|
|
1938
|
+
# "phoneCallsCreated" : 11,
|
|
1939
|
+
# "customers" : 10
|
|
1940
|
+
# },
|
|
1941
|
+
# "previous" : {
|
|
1942
|
+
# "startDate" : "2019-02-01T12:00:00Z",
|
|
1943
|
+
# "endDate" : "2019-03-01T12:00:00Z",
|
|
1944
|
+
# "phoneConversations" : 11,
|
|
1945
|
+
# "phoneCallsCreated" : 6,
|
|
1946
|
+
# "customers" : 8
|
|
1947
|
+
# },
|
|
1948
|
+
# "deltas" : {
|
|
1949
|
+
# "newConversations" : 0.0,
|
|
1950
|
+
# "phoneCallsCreated" : 83.333336,
|
|
1951
|
+
# "customers" : 25.0
|
|
1952
|
+
# },
|
|
1953
|
+
# "users" : [ {
|
|
1954
|
+
# "name" : "Vernon Bear",
|
|
1955
|
+
# "id" : 100,
|
|
1956
|
+
# "current" : {
|
|
1957
|
+
# "phoneConversations" : 2,
|
|
1958
|
+
# "phoneCallsCreated" : 0,
|
|
1959
|
+
# "customers" : 2
|
|
1960
|
+
# },
|
|
1961
|
+
# "previous" : {
|
|
1962
|
+
# "phoneConversations" : 1,
|
|
1963
|
+
# "phoneCallsCreated" : 0,
|
|
1964
|
+
# "customers" : 1
|
|
1965
|
+
# }
|
|
1966
|
+
# } ]
|
|
1967
|
+
# }
|
|
1968
|
+
```
|
|
1969
|
+
|
|
1970
|
+
## Development
|
|
1971
|
+
|
|
1972
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
|
1973
|
+
|
|
1974
|
+
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
|
|
1975
|
+
|
|
1976
|
+
## Contributing
|
|
1977
|
+
|
|
1978
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/helpscout-mailbox-v2-reports. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/helpscout-mailbox-v2-reports/blob/master/CODE_OF_CONDUCT.md).
|
|
1979
|
+
|
|
1980
|
+
## License
|
|
1981
|
+
|
|
1982
|
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
|
1983
|
+
|
|
1984
|
+
## Code of Conduct
|
|
1985
|
+
|
|
1986
|
+
Everyone interacting in the Helpscout::Mailbox::V2::Reports project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/helpscout-mailbox-v2-reports/blob/master/CODE_OF_CONDUCT.md).
|