intercom 3.9.5 → 4.1.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +355 -222
- data/Rakefile +1 -1
- data/changes.txt +25 -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 +36 -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 +22 -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 +3 -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 +37 -33
- data/lib/intercom/scroll_collection_proxy.rb +38 -42
- data/lib/intercom/search_collection_proxy.rb +30 -65
- data/lib/intercom/section.rb +23 -0
- data/lib/intercom/segment.rb +4 -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 +2 -12
- data/lib/intercom/service/contact.rb +31 -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 +25 -26
- data/spec/unit/intercom/collection_spec.rb +32 -0
- data/spec/unit/intercom/company_spec.rb +18 -14
- data/spec/unit/intercom/contact_spec.rb +363 -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 +1 -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 +37 -11
- 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: ebb883bd25fc8d132306baac3a22c43650701dbe42d42b95ada3819bc52cc2d6
|
4
|
+
data.tar.gz: 8d1158c4d79cf19916c6cc1d413c329588d1ff36b5741517e029415e0f992360
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 0a0ea848ac117043da9707f2f9689504abda06f34e218a077c0591216aa654c3e9ca73f9874f2255e7300cd3329c95ba6440232c30d58364877e7d358bf950d0
|
7
|
+
data.tar.gz: 95b5ffdd05e7332fcbd53061c08c380d8632bd9f11d09e3673da65ca25b4624377b409116292b41f626a0fc6b4ad3d1c5183e5315533d3b4f94fe285c74041a6
|
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.1'
|
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,253 @@ 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
|
+
# Archive a contact
|
90
|
+
intercom.contacts.archive(contact)
|
91
|
+
|
92
|
+
# Unarchive a contact
|
93
|
+
intercom.contacts.unarchive(contact)
|
94
|
+
|
95
|
+
# Delete a contact permanently
|
96
|
+
intercom.contacts.delete(contact)
|
97
|
+
|
98
|
+
# List all contacts
|
99
|
+
contacts = intercom.contacts.all
|
100
|
+
contacts.each { |contact| p contact.name }
|
101
|
+
|
102
|
+
# Search for contacts by email
|
103
|
+
contacts = intercom.contacts.search(
|
104
|
+
"query": {
|
105
|
+
"field": 'email',
|
106
|
+
"operator": '=',
|
107
|
+
"value": 'some_contact@example.com'
|
108
|
+
}
|
109
|
+
)
|
110
|
+
contacts.each {|c| p c.email}
|
111
|
+
# For full detail on possible queries, please refer to the API documentation:
|
112
|
+
# https://developers.intercom.com/intercom-api-reference/reference
|
113
|
+
|
114
|
+
# Merge a lead into an existing user
|
115
|
+
lead = intercom.contacts.create(email: "some_contact2@example.com", role: "lead")
|
116
|
+
intercom.contacts.merge(lead, intercom.contacts.find(id: "5db2e80ab1b92243d2188cfe"))
|
117
|
+
|
118
|
+
# Add a tag to a contact
|
119
|
+
tag = intercom.tags.find(id: "123")
|
120
|
+
contact.add_tag(id: tag.id)
|
121
|
+
|
122
|
+
# Remove a tag
|
123
|
+
contact.remove_tag(id: tag.id)
|
124
|
+
|
125
|
+
# List tags for a contact
|
126
|
+
contact.tags.each {|t| p t.name}
|
127
|
+
|
128
|
+
# Create a note on a contact
|
129
|
+
contact.create_note(body: "<p>Text for the note</p>")
|
130
|
+
|
131
|
+
# List notes for a contact
|
132
|
+
contact.notes.each {|n| p n.body}
|
133
|
+
|
134
|
+
# List segments for a contact
|
135
|
+
contact.segments.each {|segment| p segment.name}
|
136
|
+
|
137
|
+
# Add a contact to a company
|
138
|
+
company = intercom.companies.find(id: "123")
|
139
|
+
contact.add_company(id: company.id)
|
140
|
+
|
141
|
+
# Remove a contact from a company
|
142
|
+
contact.remove_company(id: company.id)
|
143
|
+
|
144
|
+
# List companies for a contact
|
145
|
+
contact.companies.each {|c| p c.name}
|
131
146
|
```
|
132
147
|
|
133
|
-
####
|
148
|
+
#### Visitors
|
134
149
|
```ruby
|
135
|
-
#
|
136
|
-
intercom.
|
137
|
-
|
138
|
-
intercom.
|
150
|
+
# Get and update a visitor
|
151
|
+
visitor = intercom.visitors.find(id: "5dd570e7b1b922452676af23")
|
152
|
+
visitor.name = "New name"
|
153
|
+
intercom.visitors.save(visitor)
|
154
|
+
|
155
|
+
# Convert a visitor into a lead
|
156
|
+
intercom.visitors.convert(visitor)
|
157
|
+
|
158
|
+
# Convert a visitor into a user
|
159
|
+
user = intercom.contacts.find(id: "5db2e7f5b1b92243d2188cb3")
|
160
|
+
intercom.visitors.convert(visitor, user)
|
139
161
|
```
|
140
162
|
|
141
163
|
#### Companies
|
142
164
|
```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
165
|
# Find a company by company_id
|
151
166
|
company = intercom.companies.find(company_id: "44")
|
167
|
+
|
152
168
|
# Find a company by name
|
153
169
|
company = intercom.companies.find(name: "Some company")
|
170
|
+
|
154
171
|
# Find a company by id
|
155
172
|
company = intercom.companies.find(id: "41e66f0313708347cb0000d0")
|
173
|
+
|
156
174
|
# Update a company
|
157
175
|
company.name = 'Updated company name'
|
158
176
|
intercom.companies.save(company)
|
177
|
+
|
178
|
+
# Delete a company
|
179
|
+
intercom.companies.delete(company)
|
180
|
+
|
159
181
|
# Iterate over all companies
|
160
182
|
intercom.companies.all.each {|company| puts %Q(#{company.name} - #{company.custom_attributes["referral_source"]}) }
|
161
183
|
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)
|
184
|
+
|
166
185
|
# Get a large list of companies using scroll
|
167
186
|
intercom.companies.scroll.each { |comp| puts comp.name}
|
168
187
|
# Please see users scroll for more details of how to use scroll
|
169
188
|
```
|
170
189
|
|
190
|
+
#### Data Attributes
|
191
|
+
Data Attributes are a type of metadata used to describe your customer and company models. These include standard and custom attributes.
|
192
|
+
```ruby
|
193
|
+
# Create a new custom data attribute
|
194
|
+
intercom.data_attributes.create({ name: "test_attribute", model: "contact", data_type: "string" })
|
195
|
+
|
196
|
+
# List all data attributes
|
197
|
+
attributes = intercom.data_attributes.all
|
198
|
+
attributes.each { |attribute| p attribute.name }
|
199
|
+
|
200
|
+
# Update an attribute
|
201
|
+
attribute = intercom.data_attributes.all.first
|
202
|
+
attribute.label = "New label"
|
203
|
+
intercom.data_attributes.save(attribute)
|
204
|
+
|
205
|
+
# Archive an attribute
|
206
|
+
attribute.archived = true
|
207
|
+
intercom.data_attributes.save(attribute)
|
208
|
+
|
209
|
+
# Find all customer attributes including archived
|
210
|
+
customer_attributes_incl_archived = intercom.data_attributes.find_all({"model": "contact", "include_archived": true})
|
211
|
+
customer_attributes_incl_archived.each { |attr| p attribute.name }
|
212
|
+
```
|
213
|
+
|
214
|
+
#### Events
|
215
|
+
```ruby
|
216
|
+
intercom.events.create(
|
217
|
+
event_name: "invited-friend",
|
218
|
+
created_at: Time.now.to_i,
|
219
|
+
email: user.email,
|
220
|
+
metadata: {
|
221
|
+
"invitee_email" => "pi@example.org",
|
222
|
+
invite_code: "ADDAFRIEND",
|
223
|
+
"found_date" => 12909364407
|
224
|
+
}
|
225
|
+
)
|
226
|
+
|
227
|
+
# Alternatively, use "user_id" in case your app allows multiple accounts having the same email
|
228
|
+
intercom.events.create(
|
229
|
+
event_name: "invited-friend",
|
230
|
+
created_at: Time.now.to_i,
|
231
|
+
user_id: user.uuid,
|
232
|
+
)
|
233
|
+
|
234
|
+
# Retrieve event list for user with id:'123abc'
|
235
|
+
intercom.events.find_all("type" => "user", "intercom_user_id" => "123abc")
|
236
|
+
```
|
237
|
+
|
238
|
+
Metadata Objects support a few simple types that Intercom can present on your behalf
|
239
|
+
|
240
|
+
```ruby
|
241
|
+
intercom.events.create(
|
242
|
+
event_name: "placed-order",
|
243
|
+
email: current_user.email,
|
244
|
+
created_at: 1403001013,
|
245
|
+
metadata: {
|
246
|
+
order_date: Time.now.to_i,
|
247
|
+
stripe_invoice: 'inv_3434343434',
|
248
|
+
order_number: {
|
249
|
+
value: '3434-3434',
|
250
|
+
url: 'https://example.org/orders/3434-3434'
|
251
|
+
},
|
252
|
+
price: {
|
253
|
+
currency: 'usd',
|
254
|
+
amount: 2999
|
255
|
+
}
|
256
|
+
}
|
257
|
+
)
|
258
|
+
```
|
259
|
+
|
260
|
+
The metadata key values in the example are treated as follows-
|
261
|
+
- order_date: a Date (key ends with '_date')
|
262
|
+
- stripe_invoice: The identifier of the Stripe invoice (has a 'stripe_invoice' key)
|
263
|
+
- order_number: a Rich Link (value contains 'url' and 'value' keys)
|
264
|
+
- price: An Amount in US Dollars (value contains 'amount' and 'currency' keys)
|
265
|
+
|
266
|
+
*NB:* This version of the gem reserves the field name `type` in Event data.
|
267
|
+
|
171
268
|
#### Tags
|
172
269
|
```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
270
|
# Iterate over all tags
|
178
271
|
intercom.tags.all.each {|tag| "#{tag.id} - #{tag.name}" }
|
179
272
|
intercom.tags.all.map {|tag| tag.name }
|
273
|
+
|
180
274
|
# Tag companies
|
181
275
|
tag = intercom.tags.tag(name: 'blue', companies: [{company_id: "42ea2f1b93891f6a99000427"}])
|
276
|
+
|
277
|
+
# Untag Companies
|
278
|
+
tag = intercom.tags.untag(name: 'blue', companies: [{ company_id: "42ea2f1b93891f6a99000427" }])
|
279
|
+
```
|
280
|
+
|
281
|
+
#### Notes
|
282
|
+
```ruby
|
283
|
+
# Find a note by id
|
284
|
+
note = intercom.notes.find(id: "123")
|
182
285
|
```
|
183
286
|
|
184
287
|
#### Segments
|
185
288
|
```ruby
|
186
289
|
# Find a segment
|
187
290
|
segment = intercom.segments.find(id: segment_id)
|
291
|
+
|
188
292
|
# Iterate over all segments
|
189
293
|
intercom.segments.all.each {|segment| puts "id: #{segment.id} name: #{segment.name}"}
|
190
294
|
```
|
191
295
|
|
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
296
|
#### Conversations
|
205
297
|
```ruby
|
206
298
|
# Iterate over all conversations for your app
|
@@ -234,12 +326,21 @@ conversation = intercom.conversations.find(id: '1')
|
|
234
326
|
|
235
327
|
# INTERACTING WITH THE PARTS OF A CONVERSATION
|
236
328
|
# Getting the subject of a part (only applies to email-based conversations)
|
237
|
-
conversation.
|
329
|
+
conversation.source.subject
|
330
|
+
|
238
331
|
# Get the part_type of the first part
|
239
|
-
conversation.conversation_parts
|
332
|
+
conversation.conversation_parts.first.part_type
|
333
|
+
|
240
334
|
# Get the body of the second part
|
241
335
|
conversation.conversation_parts[1].body
|
242
336
|
|
337
|
+
# Get statistics related to the conversation
|
338
|
+
conversation.statistics.time_to_admin_reply
|
339
|
+
conversation.statistics.last_assignment_at
|
340
|
+
|
341
|
+
# Get information on the sla applied to a conversation
|
342
|
+
conversation.sla_applied.sla_name
|
343
|
+
|
243
344
|
# REPLYING TO CONVERSATIONS
|
244
345
|
# User (identified by email) replies with a comment
|
245
346
|
intercom.conversations.reply(id: conversation.id, type: 'user', email: 'joe@example.com', message_type: 'comment', body: 'foo')
|
@@ -282,13 +383,51 @@ intercom.conversations.reply(id: conversation.id, type: 'admin', assignee_id: as
|
|
282
383
|
|
283
384
|
# MARKING A CONVERSATION AS READ
|
284
385
|
intercom.conversations.mark_read(conversation.id)
|
386
|
+
|
387
|
+
# RUN ASSIGNMENT RULES
|
388
|
+
intercom.conversations.run_assignment_rules(conversation.id)
|
389
|
+
|
390
|
+
# Search for conversations
|
391
|
+
# For full detail on possible queries, please refer to the API documentation:
|
392
|
+
# https://developers.intercom.com/intercom-api-reference/reference
|
393
|
+
|
394
|
+
# Search for open conversations sorted by the created_at date
|
395
|
+
conversations = intercom.conversations.search(
|
396
|
+
query: {
|
397
|
+
field: "open",
|
398
|
+
operator: "=",
|
399
|
+
value: true
|
400
|
+
},
|
401
|
+
sort_field: "created_at",
|
402
|
+
sort_order: "descending"
|
403
|
+
)
|
404
|
+
conversations.each {|c| p c.id}
|
405
|
+
|
406
|
+
# Tagging for conversations
|
407
|
+
tag = intercom.tags.find(id: "2")
|
408
|
+
conversation = intercom.conversations.find(id: "1")
|
409
|
+
|
410
|
+
# An Admin ID is required to add or remove tag on a conversation
|
411
|
+
admin = intercom.admins.find(id: "1")
|
412
|
+
|
413
|
+
# Add a tag to a conversation
|
414
|
+
conversation.add_tag(id: tag.id, admin_id: admin.id)
|
415
|
+
|
416
|
+
# Remove a tag from a conversation
|
417
|
+
conversation.remove_tag(id: tag.id, admin_id: admin.id)
|
418
|
+
|
419
|
+
# Add a contact to a conversation
|
420
|
+
conversation.add_contact(admin_id: admin.id, customer: { intercom_user_id: contact.id })
|
421
|
+
|
422
|
+
# Remove a contact from a conversation
|
423
|
+
conversation.remove_contact(id: contact.id, admin_id: admin.id)
|
285
424
|
```
|
286
425
|
|
287
426
|
#### Full loading of an embedded entity
|
288
427
|
```ruby
|
289
|
-
# Given a conversation with a partial
|
428
|
+
# Given a conversation with a partial contact, load the full contact. This can be
|
290
429
|
# done for any entity
|
291
|
-
intercom.
|
430
|
+
intercom.contacts.load(conversation.contacts.first)
|
292
431
|
```
|
293
432
|
|
294
433
|
#### Sending messages
|
@@ -357,125 +496,22 @@ intercom.messages.create({
|
|
357
496
|
})
|
358
497
|
```
|
359
498
|
|
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
|
-
|
499
|
+
#### Admins
|
420
500
|
```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
|
501
|
+
# Find access token owner (only with Personal Access Token and OAuth)
|
502
|
+
intercom.admins.me
|
503
|
+
# Find an admin by id
|
504
|
+
intercom.admins.find(id: admin_id)
|
505
|
+
# Iterate over all admins
|
506
|
+
intercom.admins.all.each {|admin| puts admin.email }
|
469
507
|
```
|
470
508
|
|
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
|
-
|
509
|
+
#### Teams
|
475
510
|
```ruby
|
476
|
-
#
|
477
|
-
|
478
|
-
|
511
|
+
# Find a team by id
|
512
|
+
intercom.teams.find(id: team_id)
|
513
|
+
# Iterate over all teams
|
514
|
+
intercom.teams.all.each {|team| puts team.name }
|
479
515
|
```
|
480
516
|
|
481
517
|
#### Counts
|
@@ -507,6 +543,103 @@ intercom.subscriptions.delete(subscription)
|
|
507
543
|
intercom.subscriptions.all
|
508
544
|
```
|
509
545
|
|
546
|
+
#### Articles
|
547
|
+
```ruby
|
548
|
+
# Create an article
|
549
|
+
article = intercom.articles.create(title: "New Article", author_id: "123456")
|
550
|
+
|
551
|
+
# Create an article with translations
|
552
|
+
article = intercom.articles.create(title: "New Article",
|
553
|
+
author_id: "123456",
|
554
|
+
translated_content: {fr: {title: "Nouvel Article"}, es: {title: "Nuevo artículo"}})
|
555
|
+
|
556
|
+
# Fetch an article
|
557
|
+
intercom.articles.find(id: "123456")
|
558
|
+
|
559
|
+
# List all articles
|
560
|
+
articles = intercom.articles.all
|
561
|
+
articles.each { |article| p article.title }
|
562
|
+
|
563
|
+
# Update an article
|
564
|
+
article.title = "Article Updated!"
|
565
|
+
intercom.articles.save(article)
|
566
|
+
|
567
|
+
# Update an article's existing translation
|
568
|
+
article.translated_content.en.title = "English Updated!"
|
569
|
+
intercom.articles.save(article)
|
570
|
+
|
571
|
+
# Update an article by adding a new translation
|
572
|
+
article.translated_content.es = {title: "Artículo en español"}
|
573
|
+
intercom.articles.save(article)
|
574
|
+
|
575
|
+
# Delete an article
|
576
|
+
intercom.articles.delete(article)
|
577
|
+
```
|
578
|
+
|
579
|
+
#### Collections
|
580
|
+
```ruby
|
581
|
+
# Create a collection
|
582
|
+
collection = intercom.collections.create(name: "New Collection")
|
583
|
+
|
584
|
+
# Create a collection with translations
|
585
|
+
collection = intercom.collections.create(name: "New Collection",
|
586
|
+
translated_content: {fr: {name: "Nouvelle collection"}, es: {name: "Nueva colección"}})
|
587
|
+
|
588
|
+
# Fetch a collection
|
589
|
+
intercom.collections.find(id: "123456")
|
590
|
+
|
591
|
+
# List all collections
|
592
|
+
collections = intercom.collections.all
|
593
|
+
collections.each { |collection| p collection.name }
|
594
|
+
|
595
|
+
# Update a collection
|
596
|
+
collection.name = "Collection updated!"
|
597
|
+
intercom.collections.save(collection)
|
598
|
+
|
599
|
+
# Update a collection's existing translation
|
600
|
+
collection.translated_content.en.name = "English Updated!"
|
601
|
+
intercom.collections.save(collection)
|
602
|
+
|
603
|
+
# Update a collection by adding a new translation
|
604
|
+
collection.translated_content.es = {name: "Colección en español", description: "Descripción en español"}
|
605
|
+
intercom.collections.save(collection)
|
606
|
+
|
607
|
+
# Delete an collection
|
608
|
+
intercom.collections.delete(collection)
|
609
|
+
```
|
610
|
+
|
611
|
+
#### Sections
|
612
|
+
```ruby
|
613
|
+
# Create a section
|
614
|
+
section = intercom.sections.create(name: "New Section", parent_id: "123456")
|
615
|
+
|
616
|
+
# Create a section with translations
|
617
|
+
section = intercom.sections.create(name: "New Section",
|
618
|
+
translated_content: {fr: {name: "Nouvelle section"}, es: {name: "Nueva sección"}})
|
619
|
+
|
620
|
+
# Fetch a section
|
621
|
+
intercom.sections.find(id: "123456")
|
622
|
+
|
623
|
+
# List all sections
|
624
|
+
sections = intercom.sections.all
|
625
|
+
sections.each { |section| p section.name }
|
626
|
+
|
627
|
+
# Update a section
|
628
|
+
section.name = "Section updated!"
|
629
|
+
intercom.sections.save(section)
|
630
|
+
|
631
|
+
# Update a section's existing translation
|
632
|
+
section.translated_content.en.name = "English Updated!"
|
633
|
+
intercom.collections.save(section)
|
634
|
+
|
635
|
+
# Update a section by adding a new translation
|
636
|
+
section.translated_content.es = {name: "Sección en español"}
|
637
|
+
intercom.collections.save(section)
|
638
|
+
|
639
|
+
# Delete an section
|
640
|
+
intercom.sections.delete(section)
|
641
|
+
```
|
642
|
+
|
510
643
|
### Errors
|
511
644
|
|
512
645
|
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.
|