intercom 3.9.3 → 4.1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +340 -222
- data/Rakefile +1 -1
- data/changes.txt +21 -0
- data/lib/intercom.rb +33 -22
- data/lib/intercom/api_operations/archive.rb +2 -1
- data/lib/intercom/api_operations/delete.rb +16 -0
- data/lib/intercom/api_operations/find.rb +5 -2
- data/lib/intercom/api_operations/find_all.rb +4 -3
- data/lib/intercom/api_operations/list.rb +4 -1
- data/lib/intercom/api_operations/load.rb +4 -2
- data/lib/intercom/api_operations/nested_resource.rb +70 -0
- data/lib/intercom/api_operations/save.rb +6 -4
- data/lib/intercom/api_operations/scroll.rb +4 -5
- data/lib/intercom/api_operations/search.rb +3 -2
- data/lib/intercom/article.rb +7 -0
- data/lib/intercom/base_collection_proxy.rb +72 -0
- data/lib/intercom/client.rb +32 -25
- data/lib/intercom/client_collection_proxy.rb +17 -39
- data/lib/intercom/collection.rb +7 -0
- data/lib/intercom/company.rb +8 -0
- data/lib/intercom/contact.rb +21 -3
- data/lib/intercom/conversation.rb +5 -0
- data/lib/intercom/data_attribute.rb +7 -0
- data/lib/intercom/deprecated_leads_collection_proxy.rb +22 -0
- data/lib/intercom/deprecated_resources.rb +13 -0
- data/lib/intercom/errors.rb +6 -0
- data/lib/intercom/extended_api_operations/segments.rb +3 -1
- data/lib/intercom/extended_api_operations/tags.rb +3 -1
- data/lib/intercom/lead.rb +21 -0
- data/lib/intercom/lib/typed_json_deserializer.rb +42 -37
- data/lib/intercom/note.rb +4 -0
- data/lib/intercom/request.rb +38 -32
- data/lib/intercom/scroll_collection_proxy.rb +33 -38
- data/lib/intercom/search_collection_proxy.rb +30 -65
- data/lib/intercom/section.rb +23 -0
- data/lib/intercom/service/article.rb +20 -0
- data/lib/intercom/service/base_service.rb +7 -0
- data/lib/intercom/service/collection.rb +24 -0
- data/lib/intercom/service/company.rb +0 -12
- data/lib/intercom/service/contact.rb +21 -10
- data/lib/intercom/service/conversation.rb +12 -3
- data/lib/intercom/service/data_attribute.rb +20 -0
- data/lib/intercom/service/lead.rb +41 -0
- data/lib/intercom/service/note.rb +4 -8
- data/lib/intercom/service/section.rb +7 -0
- data/lib/intercom/service/subscription.rb +2 -2
- data/lib/intercom/service/tag.rb +9 -9
- data/lib/intercom/service/visitor.rb +17 -8
- data/lib/intercom/tag.rb +4 -0
- data/lib/intercom/traits/api_resource.rb +44 -18
- data/lib/intercom/traits/dirty_tracking.rb +8 -1
- data/lib/intercom/user.rb +12 -3
- data/lib/intercom/utils.rb +13 -2
- data/lib/intercom/version.rb +1 -1
- data/lib/intercom/visitor.rb +0 -2
- data/spec/spec_helper.rb +843 -520
- data/spec/unit/intercom/admin_spec.rb +2 -2
- data/spec/unit/intercom/article_spec.rb +40 -0
- data/spec/unit/intercom/base_collection_proxy_spec.rb +30 -0
- data/spec/unit/intercom/client_collection_proxy_spec.rb +41 -41
- data/spec/unit/intercom/client_spec.rb +28 -25
- data/spec/unit/intercom/collection_spec.rb +32 -0
- data/spec/unit/intercom/company_spec.rb +13 -15
- data/spec/unit/intercom/contact_spec.rb +344 -33
- data/spec/unit/intercom/conversation_spec.rb +55 -7
- data/spec/unit/intercom/count_spec.rb +4 -4
- data/spec/unit/intercom/data_attribute_spec.rb +40 -0
- data/spec/unit/intercom/deprecated_leads_collection_proxy_spec.rb +17 -0
- data/spec/unit/intercom/event_spec.rb +9 -11
- data/spec/unit/intercom/job_spec.rb +24 -24
- data/spec/unit/intercom/lead_spec.rb +57 -0
- data/spec/unit/intercom/lib/flat_store_spec.rb +22 -20
- data/spec/unit/intercom/message_spec.rb +1 -1
- data/spec/unit/intercom/note_spec.rb +4 -10
- data/spec/unit/intercom/request_spec.rb +10 -1
- data/spec/unit/intercom/scroll_collection_proxy_spec.rb +40 -39
- data/spec/unit/intercom/search_collection_proxy_spec.rb +32 -28
- data/spec/unit/intercom/section_spec.rb +32 -0
- data/spec/unit/intercom/segment_spec.rb +2 -2
- data/spec/unit/intercom/subscription_spec.rb +5 -6
- data/spec/unit/intercom/tag_spec.rb +22 -14
- data/spec/unit/intercom/team_spec.rb +2 -2
- data/spec/unit/intercom/traits/api_resource_spec.rb +107 -52
- data/spec/unit/intercom/user_spec.rb +224 -226
- data/spec/unit/intercom/visitor_spec.rb +49 -0
- data/spec/unit/intercom_spec.rb +5 -3
- metadata +34 -8
- data/lib/intercom/customer.rb +0 -10
- data/lib/intercom/service/customer.rb +0 -14
- data/spec/unit/intercom/visitors_spec.rb +0 -61
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 0243df2d2e2715b541588cb09ed335e70bd1962767f06f475fd9b968ee4dace5
|
4
|
+
data.tar.gz: 9695060c87906c18d77c049eff37e742fadca1bdc21355d4471d4fcbe6447042
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 3ffece71e912927db02751a1d6ee8e84cf535c16491a75e6fd6a2ea1c4564b17eed584d4ea480b215bb93bb215a540b0f683c257211c672151d0c08cc4c9ea3d
|
7
|
+
data.tar.gz: a60b0b793bab1f96d98fae70c75b7ceb3d609bd1b6239d115869c35acd8406119f9ceb8fcf0b7ad374f6d95eb510938098ef9cd9f6c29a46fb28760ede661665
|
data/README.md
CHANGED
@@ -6,13 +6,11 @@ Ruby bindings for the Intercom API (https://developers.intercom.io/reference).
|
|
6
6
|
|
7
7
|
[Gem Documentation](http://rubydoc.info/github/intercom/intercom-ruby/master/frames)
|
8
8
|
|
9
|
-
For generating Intercom
|
9
|
+
For generating Intercom JavaScript script tags for Rails, please see https://github.com/intercom/intercom-rails.
|
10
10
|
|
11
11
|
## Upgrading information
|
12
12
|
|
13
|
-
Version
|
14
|
-
|
15
|
-
Version 3 moves away from a global setup approach to the use of an Intercom Client.
|
13
|
+
Version 4 of intercom-ruby is not backwards compatible with previous versions. Please see our [migration guide](https://github.com/intercom/intercom-ruby/wiki/Migration-guide-for-v4) for full details of breaking changes.
|
16
14
|
|
17
15
|
This version of the gem is compatible with `Ruby 2.1` and above.
|
18
16
|
|
@@ -23,7 +21,7 @@ This version of the gem is compatible with `Ruby 2.1` and above.
|
|
23
21
|
|
24
22
|
Using bundler:
|
25
23
|
|
26
|
-
gem 'intercom', '~>
|
24
|
+
gem 'intercom', '~> 4.0'
|
27
25
|
|
28
26
|
## Basic Usage
|
29
27
|
|
@@ -38,7 +36,7 @@ intercom = Intercom::Client.new(token: 'my_token')
|
|
38
36
|
|
39
37
|
```ruby
|
40
38
|
# With a versioned app:
|
41
|
-
intercom = Intercom::Client.new(token: 'my_token', api_version: '1
|
39
|
+
intercom = Intercom::Client.new(token: 'my_token', api_version: '2.1')
|
42
40
|
```
|
43
41
|
|
44
42
|
If you are building a third party application you can get your access_tokens by [setting-up-oauth](https://developers.intercom.io/page/setting-up-oauth) for Intercom.
|
@@ -48,159 +46,238 @@ You can also use the [omniauth-intercom lib](https://github.com/intercom/omniaut
|
|
48
46
|
|
49
47
|
Resources this API supports:
|
50
48
|
|
51
|
-
https://api.intercom.io/users
|
52
|
-
https://api.intercom.io/teams
|
53
49
|
https://api.intercom.io/contacts
|
50
|
+
https://api.intercom.io/visitors
|
54
51
|
https://api.intercom.io/companies
|
55
|
-
https://api.intercom.io/
|
52
|
+
https://api.intercom.io/data_attributes
|
53
|
+
https://api.intercom.io/events
|
56
54
|
https://api.intercom.io/tags
|
57
55
|
https://api.intercom.io/notes
|
58
56
|
https://api.intercom.io/segments
|
59
|
-
https://api.intercom.io/events
|
60
57
|
https://api.intercom.io/conversations
|
61
58
|
https://api.intercom.io/messages
|
59
|
+
https://api.intercom.io/admins
|
60
|
+
https://api.intercom.io/teams
|
61
|
+
https://api.intercom.io/counts
|
62
62
|
https://api.intercom.io/subscriptions
|
63
63
|
https://api.intercom.io/jobs
|
64
|
+
https://api.intercom.io/articles
|
65
|
+
https://api.intercom.io/help_center/collections
|
66
|
+
https://api.intercom.io/help_center/sections
|
67
|
+
|
64
68
|
|
65
69
|
### Examples
|
66
70
|
|
67
|
-
####
|
71
|
+
#### Contacts
|
72
|
+
Note that this is a new resource compatible only with the new [Contacts API](https://developers.intercom.com/intercom-api-reference/reference#contacts-model) released in API v2.0.
|
68
73
|
|
69
74
|
```ruby
|
70
|
-
#
|
71
|
-
|
72
|
-
# Find user by user_id
|
73
|
-
user = intercom.users.find(user_id: "1")
|
74
|
-
# Find user by id
|
75
|
-
user = intercom.users.find(id: "1")
|
76
|
-
# Create a user
|
77
|
-
user = intercom.users.create(email: "bob@example.com", name: "Bob Smith", signed_up_at: Time.now.to_i)
|
78
|
-
# archive a user
|
79
|
-
user = intercom.users.find(id: "1")
|
80
|
-
archived_user = intercom.users.archive(user)
|
81
|
-
# request a hard delete for a user
|
82
|
-
(https://developers.intercom.com/intercom-api-reference/reference#delete-users)
|
83
|
-
user = intercom.users.find(id: "1")
|
84
|
-
deleted_user = intercom.users.request_hard_delete(user)
|
85
|
-
# Update custom_attributes for a user
|
86
|
-
user.custom_attributes["average_monthly_spend"] = 1234.56
|
87
|
-
intercom.users.save(user)
|
88
|
-
# Perform incrementing
|
89
|
-
user.increment('karma')
|
90
|
-
intercom.users.save(user)
|
91
|
-
# Perform decrementing
|
92
|
-
user.decrement('karma', 5)
|
93
|
-
intercom.users.save(user)
|
94
|
-
# Iterate over all users
|
95
|
-
intercom.users.all.each {|user| puts %Q(#{user.email} - #{user.custom_attributes["average_monthly_spend"]}) }
|
96
|
-
intercom.users.all.map {|user| user.email }
|
97
|
-
# List your users create in the last two days
|
98
|
-
intercom.users.find_all(type: 'users', page: 1, per_page: 10, created_since: 2, order: :asc).to_a.each_with_index {|usr, i| puts "#{i+1}: #{usr.name}"};
|
99
|
-
# Paginate through your list of users choosing how many to return per page (default and max is 50 per page)
|
100
|
-
intercom.users.find_all(type: 'users', page: 1, per_page: 10, order: :asc).to_a.each_with_index {|usr, i| puts "#{i+1}: #{usr.name}"}
|
101
|
-
|
102
|
-
# Duplicate users? If you have duplicate users you can search for them via their email address.
|
103
|
-
# Note this feature is only available from version 1.1 of the API so you will need to switch to that version
|
104
|
-
# This will return multiple users if they have the same email address
|
105
|
-
usrs = intercom.users.find_all(type: 'users', email: 'myemail@example.com', page: 1, per_page: 10, order: :asc)
|
106
|
-
# This returns a user.list so you can access it via
|
107
|
-
usrs.to_a.each_with_index {|usr, i| puts "#{i+1}: #{usr.id}"};
|
108
|
-
|
109
|
-
# If you have over 10,000 users then you will need to use the scroll function to list your users
|
110
|
-
# otherwise you will encounter a page limit with list all your users
|
111
|
-
# You can use the scroll method to list all your users
|
112
|
-
intercom.users.scroll.each { |user| puts user.name}
|
113
|
-
# Alternatively you can use the scroll.next method to get 100 users with each request
|
114
|
-
result = intercom.users.scroll.next
|
115
|
-
# The result object then contains a records attributes that is an array of your user objects and it also contains a scroll_param which
|
116
|
-
# you can then use to request the next 100 users. Note that the scroll parameter will time out after one minute and you will need to
|
117
|
-
# make a new request
|
118
|
-
result.scroll_param
|
119
|
-
=> "0730e341-63ef-44da-ab9c-9113f886326d"
|
120
|
-
result = intercom.users.scroll.next("0730e341-63ef-44da-ab9c-9113f886326d");
|
121
|
-
```
|
75
|
+
# Create a contact with "lead" role
|
76
|
+
contact = intercom.contacts.create(email: "some_contact2@example.com", role: "lead")
|
122
77
|
|
123
|
-
|
124
|
-
|
125
|
-
|
126
|
-
|
127
|
-
|
128
|
-
intercom.
|
129
|
-
|
130
|
-
|
78
|
+
# Get a single contact using their intercom_id
|
79
|
+
intercom.contacts.find(id: contact.id)
|
80
|
+
|
81
|
+
# Update a contact
|
82
|
+
contact.name = "New name"
|
83
|
+
intercom.contacts.save(contact)
|
84
|
+
|
85
|
+
# Update a contact's role from "lead" to "user"
|
86
|
+
contact.role = "user"
|
87
|
+
intercom.contacts.save(contact)
|
88
|
+
|
89
|
+
# Delete a contact permanently
|
90
|
+
intercom.contacts.delete(contact)
|
91
|
+
|
92
|
+
# List all contacts
|
93
|
+
contacts = intercom.contacts.all
|
94
|
+
contacts.each { |contact| p contact.name }
|
95
|
+
|
96
|
+
# Search for contacts by email
|
97
|
+
contacts = intercom.contacts.search(
|
98
|
+
"query": {
|
99
|
+
"field": 'email',
|
100
|
+
"operator": '=',
|
101
|
+
"value": 'some_contact@example.com'
|
102
|
+
}
|
103
|
+
)
|
104
|
+
contacts.each {|c| p c.email}
|
105
|
+
# For full detail on possible queries, please refer to the API documentation:
|
106
|
+
# https://developers.intercom.com/intercom-api-reference/reference
|
107
|
+
|
108
|
+
# Merge a lead into an existing user
|
109
|
+
lead = intercom.contacts.create(email: "some_contact2@example.com", role: "lead")
|
110
|
+
intercom.contacts.merge(lead, intercom.contacts.find(id: "5db2e80ab1b92243d2188cfe"))
|
111
|
+
|
112
|
+
# Add a tag to a contact
|
113
|
+
tag = intercom.tags.find(id: "123")
|
114
|
+
contact.add_tag(id: tag.id)
|
115
|
+
|
116
|
+
# Remove a tag
|
117
|
+
contact.remove_tag(id: tag.id)
|
118
|
+
|
119
|
+
# List tags for a contact
|
120
|
+
contact.tags.each {|t| p t.name}
|
121
|
+
|
122
|
+
# Create a note on a contact
|
123
|
+
contact.create_note(body: "<p>Text for the note</p>")
|
124
|
+
|
125
|
+
# List notes for a contact
|
126
|
+
contact.notes.each {|n| p n.body}
|
127
|
+
|
128
|
+
# Add a contact to a company
|
129
|
+
company = intercom.companies.find(id: "123")
|
130
|
+
contact.add_company(id: company.id)
|
131
|
+
|
132
|
+
# Remove a contact from a company
|
133
|
+
contact.remove_company(id: company.id)
|
134
|
+
|
135
|
+
# List companies for a contact
|
136
|
+
contact.companies.each {|c| p c.name}
|
131
137
|
```
|
132
138
|
|
133
|
-
####
|
139
|
+
#### Visitors
|
134
140
|
```ruby
|
135
|
-
#
|
136
|
-
intercom.
|
137
|
-
|
138
|
-
intercom.
|
141
|
+
# Get and update a visitor
|
142
|
+
visitor = intercom.visitors.find(id: "5dd570e7b1b922452676af23")
|
143
|
+
visitor.name = "New name"
|
144
|
+
intercom.visitors.save(visitor)
|
145
|
+
|
146
|
+
# Convert a visitor into a lead
|
147
|
+
intercom.visitors.convert(visitor)
|
148
|
+
|
149
|
+
# Convert a visitor into a user
|
150
|
+
user = intercom.contacts.find(id: "5db2e7f5b1b92243d2188cb3")
|
151
|
+
intercom.visitors.convert(visitor, user)
|
139
152
|
```
|
140
153
|
|
141
154
|
#### Companies
|
142
155
|
```ruby
|
143
|
-
# Add a user to one or more companies
|
144
|
-
user = intercom.users.find(email: "bob@example.com")
|
145
|
-
user.companies = [{company_id: 6, name: "Intercom"}, {company_id: 9, name: "Test Company"}]
|
146
|
-
intercom.users.save(user)
|
147
|
-
# You can also pass custom attributes within a company as you do this
|
148
|
-
user.companies = [{id: 6, name: "Intercom", custom_attributes: {referral_source: "Google"} } ]
|
149
|
-
intercom.users.save(user)
|
150
156
|
# Find a company by company_id
|
151
157
|
company = intercom.companies.find(company_id: "44")
|
158
|
+
|
152
159
|
# Find a company by name
|
153
160
|
company = intercom.companies.find(name: "Some company")
|
161
|
+
|
154
162
|
# Find a company by id
|
155
163
|
company = intercom.companies.find(id: "41e66f0313708347cb0000d0")
|
164
|
+
|
156
165
|
# Update a company
|
157
166
|
company.name = 'Updated company name'
|
158
167
|
intercom.companies.save(company)
|
168
|
+
|
159
169
|
# Iterate over all companies
|
160
170
|
intercom.companies.all.each {|company| puts %Q(#{company.name} - #{company.custom_attributes["referral_source"]}) }
|
161
171
|
intercom.companies.all.map {|company| company.name }
|
162
|
-
|
163
|
-
intercom.companies.users_by_intercom_company_id(company.id)
|
164
|
-
# Get a list of users in a company by external company_id
|
165
|
-
intercom.companies.users_by_company_id(company.company_id)
|
172
|
+
|
166
173
|
# Get a large list of companies using scroll
|
167
174
|
intercom.companies.scroll.each { |comp| puts comp.name}
|
168
175
|
# Please see users scroll for more details of how to use scroll
|
169
176
|
```
|
170
177
|
|
178
|
+
#### Data Attributes
|
179
|
+
Data Attributes are a type of metadata used to describe your customer and company models. These include standard and custom attributes.
|
180
|
+
```ruby
|
181
|
+
# Create a new custom data attribute
|
182
|
+
intercom.data_attributes.create({ name: "test_attribute", model: "contact", data_type: "string" })
|
183
|
+
|
184
|
+
# List all data attributes
|
185
|
+
attributes = intercom.data_attributes.all
|
186
|
+
attributes.each { |attribute| p attribute.name }
|
187
|
+
|
188
|
+
# Update an attribute
|
189
|
+
attribute = intercom.data_attributes.all.first
|
190
|
+
attribute.label = "New label"
|
191
|
+
intercom.data_attributes.save(attribute)
|
192
|
+
|
193
|
+
# Archive an attribute
|
194
|
+
attribute.archived = true
|
195
|
+
intercom.data_attributes.save(attribute)
|
196
|
+
|
197
|
+
# Find all customer attributes including archived
|
198
|
+
customer_attributes_incl_archived = intercom.data_attributes.find_all({"model": "contact", "include_archived": true})
|
199
|
+
customer_attributes_incl_archived.each { |attr| p attribute.name }
|
200
|
+
```
|
201
|
+
|
202
|
+
#### Events
|
203
|
+
```ruby
|
204
|
+
intercom.events.create(
|
205
|
+
event_name: "invited-friend",
|
206
|
+
created_at: Time.now.to_i,
|
207
|
+
email: user.email,
|
208
|
+
metadata: {
|
209
|
+
"invitee_email" => "pi@example.org",
|
210
|
+
invite_code: "ADDAFRIEND",
|
211
|
+
"found_date" => 12909364407
|
212
|
+
}
|
213
|
+
)
|
214
|
+
|
215
|
+
# Alternatively, use "user_id" in case your app allows multiple accounts having the same email
|
216
|
+
intercom.events.create(
|
217
|
+
event_name: "invited-friend",
|
218
|
+
created_at: Time.now.to_i,
|
219
|
+
user_id: user.uuid,
|
220
|
+
)
|
221
|
+
|
222
|
+
# Retrieve event list for user with id:'123abc'
|
223
|
+
intercom.events.find_all("type" => "user", "intercom_user_id" => "123abc")
|
224
|
+
```
|
225
|
+
|
226
|
+
Metadata Objects support a few simple types that Intercom can present on your behalf
|
227
|
+
|
228
|
+
```ruby
|
229
|
+
intercom.events.create(
|
230
|
+
event_name: "placed-order",
|
231
|
+
email: current_user.email,
|
232
|
+
created_at: 1403001013,
|
233
|
+
metadata: {
|
234
|
+
order_date: Time.now.to_i,
|
235
|
+
stripe_invoice: 'inv_3434343434',
|
236
|
+
order_number: {
|
237
|
+
value: '3434-3434',
|
238
|
+
url: 'https://example.org/orders/3434-3434'
|
239
|
+
},
|
240
|
+
price: {
|
241
|
+
currency: 'usd',
|
242
|
+
amount: 2999
|
243
|
+
}
|
244
|
+
}
|
245
|
+
)
|
246
|
+
```
|
247
|
+
|
248
|
+
The metadata key values in the example are treated as follows-
|
249
|
+
- order_date: a Date (key ends with '_date')
|
250
|
+
- stripe_invoice: The identifier of the Stripe invoice (has a 'stripe_invoice' key)
|
251
|
+
- order_number: a Rich Link (value contains 'url' and 'value' keys)
|
252
|
+
- price: An Amount in US Dollars (value contains 'amount' and 'currency' keys)
|
253
|
+
|
254
|
+
*NB:* This version of the gem reserves the field name `type` in Event data.
|
255
|
+
|
171
256
|
#### Tags
|
172
257
|
```ruby
|
173
|
-
# Tag users
|
174
|
-
tag = intercom.tags.tag(name: 'blue', users: [{email: "test1@example.com"}])
|
175
|
-
# Untag users
|
176
|
-
intercom.tags.untag(name: 'blue', users: [{user_id: "42ea2f1b93891f6a99000427"}])
|
177
258
|
# Iterate over all tags
|
178
259
|
intercom.tags.all.each {|tag| "#{tag.id} - #{tag.name}" }
|
179
260
|
intercom.tags.all.map {|tag| tag.name }
|
261
|
+
|
180
262
|
# Tag companies
|
181
263
|
tag = intercom.tags.tag(name: 'blue', companies: [{company_id: "42ea2f1b93891f6a99000427"}])
|
182
264
|
```
|
183
265
|
|
266
|
+
#### Notes
|
267
|
+
```ruby
|
268
|
+
# Find a note by id
|
269
|
+
note = intercom.notes.find(id: "123")
|
270
|
+
```
|
271
|
+
|
184
272
|
#### Segments
|
185
273
|
```ruby
|
186
274
|
# Find a segment
|
187
275
|
segment = intercom.segments.find(id: segment_id)
|
276
|
+
|
188
277
|
# Iterate over all segments
|
189
278
|
intercom.segments.all.each {|segment| puts "id: #{segment.id} name: #{segment.name}"}
|
190
279
|
```
|
191
280
|
|
192
|
-
#### Notes
|
193
|
-
```ruby
|
194
|
-
# Find a note by id
|
195
|
-
note = intercom.notes.find(id: note)
|
196
|
-
# Create a note for a user
|
197
|
-
note = intercom.notes.create(body: "<p>Text for the note</p>", email: 'joe@example.com')
|
198
|
-
# Iterate over all notes for a user via their email address
|
199
|
-
intercom.notes.find_all(email: 'joe@example.com').each {|note| puts note.body}
|
200
|
-
# Iterate over all notes for a user via their user_id
|
201
|
-
intercom.notes.find_all(user_id: '123').each {|note| puts note.body}
|
202
|
-
```
|
203
|
-
|
204
281
|
#### Conversations
|
205
282
|
```ruby
|
206
283
|
# Iterate over all conversations for your app
|
@@ -234,12 +311,21 @@ conversation = intercom.conversations.find(id: '1')
|
|
234
311
|
|
235
312
|
# INTERACTING WITH THE PARTS OF A CONVERSATION
|
236
313
|
# Getting the subject of a part (only applies to email-based conversations)
|
237
|
-
conversation.
|
314
|
+
conversation.source.subject
|
315
|
+
|
238
316
|
# Get the part_type of the first part
|
239
|
-
conversation.conversation_parts
|
317
|
+
conversation.conversation_parts.first.part_type
|
318
|
+
|
240
319
|
# Get the body of the second part
|
241
320
|
conversation.conversation_parts[1].body
|
242
321
|
|
322
|
+
# Get statistics related to the conversation
|
323
|
+
conversation.statistics.time_to_admin_reply
|
324
|
+
conversation.statistics.last_assignment_at
|
325
|
+
|
326
|
+
# Get information on the sla applied to a conversation
|
327
|
+
conversation.sla_applied.sla_name
|
328
|
+
|
243
329
|
# REPLYING TO CONVERSATIONS
|
244
330
|
# User (identified by email) replies with a comment
|
245
331
|
intercom.conversations.reply(id: conversation.id, type: 'user', email: 'joe@example.com', message_type: 'comment', body: 'foo')
|
@@ -282,13 +368,51 @@ intercom.conversations.reply(id: conversation.id, type: 'admin', assignee_id: as
|
|
282
368
|
|
283
369
|
# MARKING A CONVERSATION AS READ
|
284
370
|
intercom.conversations.mark_read(conversation.id)
|
371
|
+
|
372
|
+
# RUN ASSIGNMENT RULES
|
373
|
+
intercom.conversations.run_assignment_rules(conversation.id)
|
374
|
+
|
375
|
+
# Search for conversations
|
376
|
+
# For full detail on possible queries, please refer to the API documentation:
|
377
|
+
# https://developers.intercom.com/intercom-api-reference/reference
|
378
|
+
|
379
|
+
# Search for open conversations sorted by the created_at date
|
380
|
+
conversations = intercom.conversations.search(
|
381
|
+
query: {
|
382
|
+
field: "open",
|
383
|
+
operator: "=",
|
384
|
+
value: true
|
385
|
+
},
|
386
|
+
sort_field: "created_at",
|
387
|
+
sort_order: "descending"
|
388
|
+
)
|
389
|
+
conversations.each {|c| p c.id}
|
390
|
+
|
391
|
+
# Tagging for conversations
|
392
|
+
tag = intercom.tags.find(id: "2")
|
393
|
+
conversation = intercom.conversations.find(id: "1")
|
394
|
+
|
395
|
+
# An Admin ID is required to add or remove tag on a conversation
|
396
|
+
admin = intercom.admins.find(id: "1")
|
397
|
+
|
398
|
+
# Add a tag to a conversation
|
399
|
+
conversation.add_tag(id: tag.id, admin_id: admin.id)
|
400
|
+
|
401
|
+
# Remove a tag from a conversation
|
402
|
+
conversation.remove_tag(id: tag.id, admin_id: admin.id)
|
403
|
+
|
404
|
+
# Add a contact to a conversation
|
405
|
+
conversation.add_contact(admin_id: admin.id, customer: { intercom_user_id: contact.id })
|
406
|
+
|
407
|
+
# Remove a contact from a conversation
|
408
|
+
conversation.remove_contact(id: contact.id, admin_id: admin.id)
|
285
409
|
```
|
286
410
|
|
287
411
|
#### Full loading of an embedded entity
|
288
412
|
```ruby
|
289
|
-
# Given a conversation with a partial
|
413
|
+
# Given a conversation with a partial contact, load the full contact. This can be
|
290
414
|
# done for any entity
|
291
|
-
intercom.
|
415
|
+
intercom.contacts.load(conversation.contacts.first)
|
292
416
|
```
|
293
417
|
|
294
418
|
#### Sending messages
|
@@ -357,125 +481,22 @@ intercom.messages.create({
|
|
357
481
|
})
|
358
482
|
```
|
359
483
|
|
360
|
-
####
|
361
|
-
```ruby
|
362
|
-
intercom.events.create(
|
363
|
-
event_name: "invited-friend",
|
364
|
-
created_at: Time.now.to_i,
|
365
|
-
email: user.email,
|
366
|
-
metadata: {
|
367
|
-
"invitee_email" => "pi@example.org",
|
368
|
-
invite_code: "ADDAFRIEND",
|
369
|
-
"found_date" => 12909364407
|
370
|
-
}
|
371
|
-
)
|
372
|
-
|
373
|
-
# Alternatively, use "user_id" in case your app allows multiple accounts having the same email
|
374
|
-
intercom.events.create(
|
375
|
-
event_name: "invited-friend",
|
376
|
-
created_at: Time.now.to_i,
|
377
|
-
user_id: user.uuid,
|
378
|
-
)
|
379
|
-
|
380
|
-
# Retrieve event list for user with id:'123abc'
|
381
|
-
intercom.events.find_all("type" => "user", "intercom_user_id" => "123abc")
|
382
|
-
|
383
|
-
```
|
384
|
-
|
385
|
-
Metadata Objects support a few simple types that Intercom can present on your behalf
|
386
|
-
|
387
|
-
```ruby
|
388
|
-
intercom.events.create(
|
389
|
-
event_name: "placed-order",
|
390
|
-
email: current_user.email,
|
391
|
-
created_at: 1403001013,
|
392
|
-
metadata: {
|
393
|
-
order_date: Time.now.to_i,
|
394
|
-
stripe_invoice: 'inv_3434343434',
|
395
|
-
order_number: {
|
396
|
-
value: '3434-3434',
|
397
|
-
url: 'https://example.org/orders/3434-3434'
|
398
|
-
},
|
399
|
-
price: {
|
400
|
-
currency: 'usd',
|
401
|
-
amount: 2999
|
402
|
-
}
|
403
|
-
}
|
404
|
-
)
|
405
|
-
```
|
406
|
-
|
407
|
-
The metadata key values in the example are treated as follows-
|
408
|
-
- order_date: a Date (key ends with '_date')
|
409
|
-
- stripe_invoice: The identifier of the Stripe invoice (has a 'stripe_invoice' key)
|
410
|
-
- order_number: a Rich Link (value contains 'url' and 'value' keys)
|
411
|
-
- price: An Amount in US Dollars (value contains 'amount' and 'currency' keys)
|
412
|
-
|
413
|
-
*NB:* This version of the gem reserves the field name `type` in Event data.
|
414
|
-
|
415
|
-
#### Contacts
|
416
|
-
|
417
|
-
`Contacts` represent logged out users of your application.
|
418
|
-
Note that `contacts` are referred to as `leads` in the [Intercom](https://developers.intercom.com/intercom-api-reference/reference#leads)
|
419
|
-
|
484
|
+
#### Admins
|
420
485
|
```ruby
|
421
|
-
#
|
422
|
-
|
423
|
-
|
424
|
-
|
425
|
-
#
|
426
|
-
|
427
|
-
# See https://developers.intercom.com/intercom-api-reference/reference#update-lead for more detail
|
428
|
-
contact = intercom.contacts.create(email: "some_contact@example.com", id: "3be0398668071a6bc6850413", name:"update_contact")
|
429
|
-
|
430
|
-
# Update a contact (via contact object)
|
431
|
-
contact.custom_attributes['foo'] = 'bar'
|
432
|
-
intercom.contacts.save(contact)
|
433
|
-
|
434
|
-
# Find contacts by email
|
435
|
-
contacts = intercom.contacts.find_all(email: "some_contact@example.com")
|
436
|
-
|
437
|
-
# Using find to search for contacts by email
|
438
|
-
contact_list = intercom.contacts.find(email: "some_contact@example.com")
|
439
|
-
# This returns a Contact object with type contact.list
|
440
|
-
# Note: Multiple contacts can be returned in this list if there are multiple matching contacts found
|
441
|
-
# #<Intercom::Contact:0x00007ff3a80789f8
|
442
|
-
# @changed_fields=#<Set: {}>,
|
443
|
-
# @contacts=
|
444
|
-
# [{"type"=>"contact",
|
445
|
-
# "id"=>"5b7fd9b683681ac52274b9c7",
|
446
|
-
# "user_id"=>"05bc4d17-72cc-433e-88ae-0bf88db5d0e6",
|
447
|
-
# "anonymous"=>true,
|
448
|
-
# "email"=>"some_contact@example.com",
|
449
|
-
# ...}],
|
450
|
-
# @custom_attributes={},
|
451
|
-
# @limited=false,
|
452
|
-
# @pages=#<Intercom::Pages:0x00007ff3a7413c58 @changed_fields=#<Set: {}>, @next=nil, @page=1, @per_page=50, @total_pages=1, @type="pages">,
|
453
|
-
# @total_count=1,
|
454
|
-
# @type="contact.list">
|
455
|
-
# Access the contact's data
|
456
|
-
contact_list.contacts.first
|
457
|
-
|
458
|
-
# Convert a contact into a user
|
459
|
-
contact = intercom.contacts.find(id: "536e564f316c83104c000020")
|
460
|
-
intercom.contacts.convert(contact, Intercom::User.new(email: email))
|
461
|
-
# Using find with email will not work here. See https://github.com/intercom/intercom-ruby/issues/419 for more information
|
462
|
-
|
463
|
-
# archive a contact
|
464
|
-
intercom.contacts.archive(contact)
|
465
|
-
|
466
|
-
# Get a large list of contacts using scroll
|
467
|
-
intercom.contacts.scroll.each { |lead| puts lead.id}
|
468
|
-
# Please see users scroll for more details of how to use scroll
|
486
|
+
# Find access token owner (only with Personal Access Token and OAuth)
|
487
|
+
intercom.admins.me
|
488
|
+
# Find an admin by id
|
489
|
+
intercom.admins.find(id: admin_id)
|
490
|
+
# Iterate over all admins
|
491
|
+
intercom.admins.all.each {|admin| puts admin.email }
|
469
492
|
```
|
470
493
|
|
471
|
-
####
|
472
|
-
|
473
|
-
Our Customer API is a central place for all the information on your customers, whether they're users or leads. More detail in our API documentation on [Customers](https://developers.intercom.com/intercom-api-reference/v0/reference#customers).
|
474
|
-
|
494
|
+
#### Teams
|
475
495
|
```ruby
|
476
|
-
#
|
477
|
-
|
478
|
-
|
496
|
+
# Find a team by id
|
497
|
+
intercom.teams.find(id: team_id)
|
498
|
+
# Iterate over all teams
|
499
|
+
intercom.teams.all.each {|team| puts team.name }
|
479
500
|
```
|
480
501
|
|
481
502
|
#### Counts
|
@@ -507,6 +528,103 @@ intercom.subscriptions.delete(subscription)
|
|
507
528
|
intercom.subscriptions.all
|
508
529
|
```
|
509
530
|
|
531
|
+
#### Articles
|
532
|
+
```ruby
|
533
|
+
# Create an article
|
534
|
+
article = intercom.articles.create(title: "New Article", author_id: "123456")
|
535
|
+
|
536
|
+
# Create an article with translations
|
537
|
+
article = intercom.articles.create(title: "New Article",
|
538
|
+
author_id: "123456",
|
539
|
+
translated_content: {fr: {title: "Nouvel Article"}, es: {title: "Nuevo artículo"}})
|
540
|
+
|
541
|
+
# Fetch an article
|
542
|
+
intercom.articles.find(id: "123456")
|
543
|
+
|
544
|
+
# List all articles
|
545
|
+
articles = intercom.articles.all
|
546
|
+
articles.each { |article| p article.title }
|
547
|
+
|
548
|
+
# Update an article
|
549
|
+
article.title = "Article Updated!"
|
550
|
+
intercom.articles.save(article)
|
551
|
+
|
552
|
+
# Update an article's existing translation
|
553
|
+
article.translated_content.en.title = "English Updated!"
|
554
|
+
intercom.articles.save(article)
|
555
|
+
|
556
|
+
# Update an article by adding a new translation
|
557
|
+
article.translated_content.es = {title: "Artículo en español"}
|
558
|
+
intercom.articles.save(article)
|
559
|
+
|
560
|
+
# Delete an article
|
561
|
+
intercom.articles.delete(article)
|
562
|
+
```
|
563
|
+
|
564
|
+
#### Collections
|
565
|
+
```ruby
|
566
|
+
# Create a collection
|
567
|
+
collection = intercom.collections.create(name: "New Collection")
|
568
|
+
|
569
|
+
# Create a collection with translations
|
570
|
+
collection = intercom.collections.create(name: "New Collection",
|
571
|
+
translated_content: {fr: {name: "Nouvelle collection"}, es: {name: "Nueva colección"}})
|
572
|
+
|
573
|
+
# Fetch a collection
|
574
|
+
intercom.collections.find(id: "123456")
|
575
|
+
|
576
|
+
# List all collections
|
577
|
+
collections = intercom.collections.all
|
578
|
+
collections.each { |collection| p collection.name }
|
579
|
+
|
580
|
+
# Update a collection
|
581
|
+
collection.name = "Collection updated!"
|
582
|
+
intercom.collections.save(collection)
|
583
|
+
|
584
|
+
# Update a collection's existing translation
|
585
|
+
collection.translated_content.en.name = "English Updated!"
|
586
|
+
intercom.collections.save(collection)
|
587
|
+
|
588
|
+
# Update a collection by adding a new translation
|
589
|
+
collection.translated_content.es = {name: "Colección en español", description: "Descripción en español"}
|
590
|
+
intercom.collections.save(collection)
|
591
|
+
|
592
|
+
# Delete an collection
|
593
|
+
intercom.collections.delete(collection)
|
594
|
+
```
|
595
|
+
|
596
|
+
#### Sections
|
597
|
+
```ruby
|
598
|
+
# Create a section
|
599
|
+
section = intercom.sections.create(name: "New Section", parent_id: "123456")
|
600
|
+
|
601
|
+
# Create a section with translations
|
602
|
+
section = intercom.sections.create(name: "New Section",
|
603
|
+
translated_content: {fr: {name: "Nouvelle section"}, es: {name: "Nueva sección"}})
|
604
|
+
|
605
|
+
# Fetch a section
|
606
|
+
intercom.sections.find(id: "123456")
|
607
|
+
|
608
|
+
# List all sections
|
609
|
+
sections = intercom.sections.all
|
610
|
+
sections.each { |section| p section.name }
|
611
|
+
|
612
|
+
# Update a section
|
613
|
+
section.name = "Section updated!"
|
614
|
+
intercom.sections.save(section)
|
615
|
+
|
616
|
+
# Update a section's existing translation
|
617
|
+
section.translated_content.en.name = "English Updated!"
|
618
|
+
intercom.collections.save(section)
|
619
|
+
|
620
|
+
# Update a section by adding a new translation
|
621
|
+
section.translated_content.es = {name: "Sección en español"}
|
622
|
+
intercom.collections.save(section)
|
623
|
+
|
624
|
+
# Delete an section
|
625
|
+
intercom.sections.delete(section)
|
626
|
+
```
|
627
|
+
|
510
628
|
### Errors
|
511
629
|
|
512
630
|
There are different styles for error handling - some people prefer exceptions; some prefer nil and check; some prefer error objects/codes. Balancing these preferences alongside our wish to provide an idiomatic gem has brought us to use the current mechanism of throwing specific exceptions. Our approach in the client is to propagate errors and signal our failure loudly so that erroneous data does not get propagated through our customers' systems - in other words, if you see a `Intercom::ServiceUnavailableError` you know where the problem is.
|