intercom 3.5.10 → 4.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0f98bf7f9725ad035949ca88859ba807a6323a83
-  data.tar.gz: 97e46a4507500d311495e11114fb80d0715cb0a0
+SHA256:
+  metadata.gz: ebb883bd25fc8d132306baac3a22c43650701dbe42d42b95ada3819bc52cc2d6
+  data.tar.gz: 8d1158c4d79cf19916c6cc1d413c329588d1ff36b5741517e029415e0f992360
 SHA512:
-  metadata.gz: 8c83c5d9c5ad9d4844b5b8f7c3602e6bf76cbbb9e9836b264acbdcfdb5e3567310c1441e23c7cd0b2dac30f0200bbea46175fe9eea5c130aa49d16e9ca5cd2d4
-  data.tar.gz: b480c171fd98135e719c37be86b0d13f7288f65130583d863afad3dd32acdc42de3e66be8941620047ba57db9fc54548b10307cbed55bd5278563825e6728de0
+  metadata.gz: 0a0ea848ac117043da9707f2f9689504abda06f34e218a077c0591216aa654c3e9ca73f9874f2255e7300cd3329c95ba6440232c30d58364877e7d358bf950d0
+  data.tar.gz: 95b5ffdd05e7332fcbd53061c08c380d8632bd9f11d09e3673da65ca25b4624377b409116292b41f626a0fc6b4ad3d1c5183e5315533d3b4f94fe285c74041a6

data/.circleci/config.yml

@@ -0,0 +1,35 @@
+version: 2
+jobs:
+  "Test against Ruby 2.4":
+    docker:
+      - image: circleci/ruby:2.4.9
+    working_directory: ~/intercom-ruby
+    steps:
+      - checkout
+      - run: bundle install
+      - run: bundle exec rake
+  "Test against Ruby 2.5":
+    docker:
+      - image: circleci/ruby:2.5.7
+    working_directory: ~/intercom-ruby
+    steps:
+      - checkout
+      - run: bundle install
+      - run: bundle exec rake
+  "Test against Ruby 2.6":
+    docker:
+      - image: circleci/ruby:2.6.5
+    working_directory: ~/intercom-ruby
+    steps:
+      - checkout
+      - run: bundle install
+      - run: bundle exec rake
+
+workflows:
+  version: 2
+  build_and_test:
+    jobs:
+      - "Test against Ruby 2.4"
+      - "Test against Ruby 2.5"
+      - "Test against Ruby 2.6"
+

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+#### Why?
+Why are you making this change?
+
+#### How?
+Technical details on your change

data/Gemfile

@@ -1,13 +1,10 @@
 source "http://rubygems.org"
 
+gem 'webmock'
 gemspec
 
 group :development, :test do
   platforms :jruby do
-    gem 'json-jruby'
     gem 'jruby-openssl'
   end
-  platforms :ruby_18 do
-    gem 'json_pure'
-  end
 end

data/README.md

@@ -6,35 +6,39 @@ Ruby bindings for the Intercom API (https://developers.intercom.io/reference).
 
 [Gem Documentation](http://rubydoc.info/github/intercom/intercom-ruby/master/frames)
 
-For generating Intercom javascript script tags for Rails, please see https://github.com/intercom/intercom-rails.
+For generating Intercom JavaScript script tags for Rails, please see https://github.com/intercom/intercom-rails.
 
 ## Upgrading information
 
-Version 3 of intercom-ruby is not backwards compatible with previous versions.
-
-Version 3 moves away from a global setup approach to the use of an Intercom Client.
+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.
 
 This version of the gem is compatible with `Ruby 2.1` and above.
 
 ## Installation
 
+
     gem install intercom
 
 Using bundler:
 
-    gem 'intercom', '~> 3.5.9'
+    gem 'intercom', '~> 4.1'
 
 ## Basic Usage
 
 ### Configure your client
 
-> If you already have a personal access token you can find it [here](https://app.intercom.io/a/apps/_/settings/personal-access-token). If you want to create or learn more about personal access tokens then you can find more info [here](https://developers.intercom.io/docs/personal-access-tokens).
+> If you already have a personal access token you can find it [here](https://app.intercom.io/a/apps/_/developer-hub/). If you want to create or learn more about personal access tokens then you can find more info [here](https://developers.intercom.io/docs/personal-access-tokens).
 
 ```ruby
 # With an OAuth or Personal Access token:
 intercom = Intercom::Client.new(token: 'my_token')
 ```
 
+```ruby
+# With a versioned app:
+intercom = Intercom::Client.new(token: 'my_token', api_version: '2.1')
+```
+
 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.
 You can also use the [omniauth-intercom lib](https://github.com/intercom/omniauth-intercom) which is a middleware helping you to handle the authentication process with Intercom.
 
@@ -42,146 +46,258 @@ You can also use the [omniauth-intercom lib](https://github.com/intercom/omniaut
 
 Resources this API supports:
 
-    https://api.intercom.io/users
     https://api.intercom.io/contacts
+    https://api.intercom.io/visitors
     https://api.intercom.io/companies
-    https://api.intercom.io/counts
+    https://api.intercom.io/data_attributes
+    https://api.intercom.io/events
     https://api.intercom.io/tags
     https://api.intercom.io/notes
     https://api.intercom.io/segments
-    https://api.intercom.io/events
     https://api.intercom.io/conversations
     https://api.intercom.io/messages
+    https://api.intercom.io/admins
+    https://api.intercom.io/teams
+    https://api.intercom.io/counts
     https://api.intercom.io/subscriptions
     https://api.intercom.io/jobs
-    https://api.intercom.io/bulk
+    https://api.intercom.io/articles
+    https://api.intercom.io/help_center/collections
+    https://api.intercom.io/help_center/sections
+
 
 ### Examples
 
-#### Users
+#### Contacts
+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.
 
 ```ruby
-# Find user by email
-user = intercom.users.find(email: "bob@example.com")
-# Find user by user_id
-user = intercom.users.find(user_id: "1")
-# Find user by id
-user = intercom.users.find(id: "1")
-# Create a user
-user = intercom.users.create(email: "bob@example.com", name: "Bob Smith", signed_up_at: Time.now.to_i)
-# Delete a user
-user = intercom.users.find(id: "1")
-deleted_user = intercom.users.delete(user)
-# Update custom_attributes for a user
-user.custom_attributes["average_monthly_spend"] = 1234.56
-intercom.users.save(user)
-# Perform incrementing
-user.increment('karma')
-intercom.users.save(user)
-# Perform decrementing
-user.decrement('karma', 5)
-intercom.users.save(user)
-# Iterate over all users
-intercom.users.all.each {|user| puts %Q(#{user.email} - #{user.custom_attributes["average_monthly_spend"]}) }
-intercom.users.all.map {|user| user.email }
-# List your users create in the last two days
-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}"};
-# Paginate through your list of users choosing how many to return per page (default and max is 50 per page)
-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}"}
-# If you have over 10,000 users then you will need to use the scroll function to list your users
-# otherwise you will encounter a page limit with list all your users
-# You can use the scroll method to list all your users
-intercom.users.scroll.each { |user| puts user.name}
-# Alternatively you can use the scroll.next method to get 100 users with each request
-result = intercom.users.scroll.next
-# The result object then contains a records attributes that is an array of your user objects and it also contains a scroll_param which
-# 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
-# make a new request
-result.scroll_param
-=> "0730e341-63ef-44da-ab9c-9113f886326d"
-result = intercom.users.scroll.next("0730e341-63ef-44da-ab9c-9113f886326d");
-
-#Bulk operations.
-# Submit bulk job to create users. If any of the items in create_items match an existing user that user will be updated
-intercom.users.submit_bulk_job(create_items: [{user_id: "25", email: "alice@example.com"}, {user_id: "25", email: "bob@example.com"}])
-# Submit bulk job to create users with companies. Companies must be sent as an array of objects nested within each applicable user object
-intercom.users.submit_bulk_job(create_items: [{user_id: "25", email: "alice@example.com", companies: [{company_id: 9, name: "Test Company"}]}])
-# Submit bulk job, to delete users
-intercom.users.submit_bulk_job(delete_items: [{user_id: "25", email: "alice@example.com"}, {user_id: "25", email: "bob@example.com"}])
-# Submit bulk job, to add items to existing job
-intercom.users.submit_bulk_job(create_items: [{user_id: "25", email: "alice@example.com"}], delete_items: [{user_id: "25", email: "bob@example.com"}], job_id:'job_abcd1234')
+# Create a contact with "lead" role
+contact = intercom.contacts.create(email: "some_contact2@example.com", role: "lead")
+
+# Get a single contact using their intercom_id
+intercom.contacts.find(id: contact.id)
+
+# Update a contact
+contact.name = "New name"
+intercom.contacts.save(contact)
+
+# Update a contact's role from "lead" to "user"
+contact.role = "user"
+intercom.contacts.save(contact)
+
+# Archive a contact
+intercom.contacts.archive(contact)
+
+# Unarchive a contact
+intercom.contacts.unarchive(contact)
+
+# Delete a contact permanently
+intercom.contacts.delete(contact)
+
+# List all contacts
+contacts = intercom.contacts.all
+contacts.each { |contact| p contact.name }
+
+# Search for contacts by email
+contacts = intercom.contacts.search(
+  "query": {
+    "field": 'email',
+    "operator": '=',
+    "value": 'some_contact@example.com'
+  }
+)
+contacts.each {|c| p c.email}
+# For full detail on possible queries, please refer to the API documentation:
+# https://developers.intercom.com/intercom-api-reference/reference
+
+# Merge a lead into an existing user
+lead = intercom.contacts.create(email: "some_contact2@example.com", role: "lead")
+intercom.contacts.merge(lead, intercom.contacts.find(id: "5db2e80ab1b92243d2188cfe"))
+
+# Add a tag to a contact
+tag = intercom.tags.find(id: "123")
+contact.add_tag(id: tag.id)
+
+# Remove a tag
+contact.remove_tag(id: tag.id)
+
+# List tags for a contact
+contact.tags.each {|t| p t.name}
+
+# Create a note on a contact
+contact.create_note(body: "<p>Text for the note</p>")
+
+# List notes for a contact
+contact.notes.each {|n| p n.body}
+
+# List segments for a contact
+contact.segments.each {|segment| p segment.name}
+
+# Add a contact to a company
+company = intercom.companies.find(id: "123")
+contact.add_company(id: company.id)
+
+# Remove a contact from a company
+contact.remove_company(id: company.id)
+
+# List companies for a contact
+contact.companies.each {|c| p c.name}
 ```
 
-#### Admins
+#### Visitors
 ```ruby
-# Find access token owner (only with Personal Access Token and OAuth)
-intercom.admins.me
-# Find an admin by id
-intercom.admins.find(id: admin_id)
-# Iterate over all admins
-intercom.admins.all.each {|admin| puts admin.email }
+# Get and update a visitor
+visitor = intercom.visitors.find(id: "5dd570e7b1b922452676af23")
+visitor.name = "New name"
+intercom.visitors.save(visitor)
+
+# Convert a visitor into a lead
+intercom.visitors.convert(visitor)
+
+# Convert a visitor into a user
+user = intercom.contacts.find(id: "5db2e7f5b1b92243d2188cb3")
+intercom.visitors.convert(visitor, user)
 ```
 
 #### Companies
 ```ruby
-# Add a user to one or more companies
-user = intercom.users.find(email: "bob@example.com")
-user.companies = [{company_id: 6, name: "Intercom"}, {company_id: 9, name: "Test Company"}]
-intercom.users.save(user)
-# You can also pass custom attributes within a company as you do this
-user.companies = [{id: 6, name: "Intercom", custom_attributes: {referral_source: "Google"} } ]
-intercom.users.save(user)
 # Find a company by company_id
 company = intercom.companies.find(company_id: "44")
+
 # Find a company by name
 company = intercom.companies.find(name: "Some company")
+
 # Find a company by id
 company = intercom.companies.find(id: "41e66f0313708347cb0000d0")
+
 # Update a company
 company.name = 'Updated company name'
 intercom.companies.save(company)
+
+# Delete a company
+intercom.companies.delete(company)
+
 # Iterate over all companies
 intercom.companies.all.each {|company| puts %Q(#{company.name} - #{company.custom_attributes["referral_source"]}) }
 intercom.companies.all.map {|company| company.name }
-# Get a list of users in a company
-intercom.companies.users(company.id)
+
+# Get a large list of companies using scroll
+intercom.companies.scroll.each { |comp| puts comp.name}
+# Please see users scroll for more details of how to use scroll
+```
+
+#### Data Attributes
+Data Attributes are a type of metadata used to describe your customer and company models. These include standard and custom attributes.
+```ruby
+# Create a new custom data attribute
+intercom.data_attributes.create({ name: "test_attribute", model: "contact", data_type: "string" })
+
+# List all data attributes
+attributes = intercom.data_attributes.all
+attributes.each { |attribute| p attribute.name }
+
+# Update an attribute
+attribute = intercom.data_attributes.all.first
+attribute.label = "New label"
+intercom.data_attributes.save(attribute)
+
+# Archive an attribute
+attribute.archived = true
+intercom.data_attributes.save(attribute)
+
+# Find all customer attributes including archived
+customer_attributes_incl_archived = intercom.data_attributes.find_all({"model": "contact", "include_archived": true})
+customer_attributes_incl_archived.each { |attr| p attribute.name }
 ```
 
+#### Events
+```ruby
+intercom.events.create(
+  event_name: "invited-friend",
+  created_at: Time.now.to_i,
+  email: user.email,
+  metadata: {
+    "invitee_email" => "pi@example.org",
+    invite_code: "ADDAFRIEND",
+    "found_date" => 12909364407
+  }
+)
+
+# Alternatively, use "user_id" in case your app allows multiple accounts having the same email
+intercom.events.create(
+  event_name: "invited-friend",
+  created_at: Time.now.to_i,
+  user_id: user.uuid,
+)
+
+# Retrieve event list for user with id:'123abc'
+ intercom.events.find_all("type" => "user", "intercom_user_id" => "123abc")
+```
+
+Metadata Objects support a few simple types that Intercom can present on your behalf
+
+```ruby
+intercom.events.create(
+  event_name: "placed-order",
+  email: current_user.email,
+  created_at: 1403001013,
+  metadata: {
+    order_date: Time.now.to_i,
+    stripe_invoice: 'inv_3434343434',
+    order_number: {
+      value: '3434-3434',
+      url: 'https://example.org/orders/3434-3434'
+    },
+    price: {
+      currency: 'usd',
+      amount: 2999
+    }
+  }
+)
+```
+
+The metadata key values in the example are treated as follows-
+- order_date: a Date (key ends with '_date')
+- stripe_invoice: The identifier of the Stripe invoice (has a 'stripe_invoice' key)
+- order_number: a Rich Link (value contains 'url' and 'value' keys)
+- price: An Amount in US Dollars (value contains 'amount' and 'currency' keys)
+
+*NB:* This version of the gem reserves the field name `type` in Event data.
+
 #### Tags
 ```ruby
-# Tag users
-tag = intercom.tags.tag(name: 'blue', users: [{email: "test1@example.com"}])
-# Untag users
-intercom.tags.untag(name: 'blue',  users: [{user_id: "42ea2f1b93891f6a99000427"}])
 # Iterate over all tags
 intercom.tags.all.each {|tag| "#{tag.id} - #{tag.name}" }
 intercom.tags.all.map {|tag| tag.name }
+
 # Tag companies
-tag = intercom.tags.tag(name: 'blue', companies: [{id: "42ea2f1b93891f6a99000427"}])
+tag = intercom.tags.tag(name: 'blue', companies: [{company_id: "42ea2f1b93891f6a99000427"}])
+
+# Untag Companies
+tag = intercom.tags.untag(name: 'blue', companies: [{ company_id: "42ea2f1b93891f6a99000427" }])
+```
+
+#### Notes
+```ruby
+# Find a note by id
+note = intercom.notes.find(id: "123")
 ```
 
 #### Segments
 ```ruby
 # Find a segment
 segment = intercom.segments.find(id: segment_id)
+
 # Iterate over all segments
 intercom.segments.all.each {|segment| puts "id: #{segment.id} name: #{segment.name}"}
 ```
 
-#### Notes
-```ruby
-# Find a note by id
-note = intercom.notes.find(id: note)
-# Create a note for a user
-note = intercom.notes.create(body: "<p>Text for the note</p>", email: 'joe@example.com')
-# Iterate over all notes for a user via their email address
-intercom.notes.find_all(email: 'joe@example.com').each {|note| puts note.body}
-# Iterate over all notes for a user via their user_id
-intercom.notes.find_all(user_id: '123').each {|note| puts note.body}
-```
-
 #### Conversations
 ```ruby
+# Iterate over all conversations for your app
+intercom.conversations.all.each { |convo| ... }
+
 # FINDING CONVERSATIONS FOR AN ADMIN
 # Iterate over all conversations (open and closed) assigned to an admin
 intercom.conversations.find_all(type: 'admin', id: '7').each {|convo| ... }
@@ -189,7 +305,7 @@ intercom.conversations.find_all(type: 'admin', id: '7').each {|convo| ... }
 intercom.conversations.find_all(type: 'admin', id: 7, open: true).each {|convo| ... }
 # Iterate over closed conversations assigned to an admin
 intercom.conversations.find_all(type: 'admin', id: 7, open: false).each {|convo| ... }
-# Iterate over closed conversations for assigned an admin, before a certain moment in time
+# Iterate over closed conversations which are assigned to an admin, and where updated_at is before a certain moment in time
 intercom.conversations.find_all(type: 'admin', id: 7, open: false, before: 1374844930).each {|convo| ... }
 
 # FINDING CONVERSATIONS FOR A USER
@@ -199,18 +315,32 @@ intercom.conversations.find_all(email: 'joe@example.com', type: 'user').each {|c
 intercom.conversations.find_all(email: 'joe@example.com', type: 'user', unread: false).each {|convo| ... }
 # Iterate over all unread conversations with a user based on the users email
 intercom.conversations.find_all(email: 'joe@example.com', type: 'user', unread: true).each {|convo| ... }
+# Iterate over all conversations for a user with their Intercom user ID
+intercom.conversations.find_all(intercom_user_id: '536e564f316c83104c000020', type: 'user').each {|convo| ... }
+# Iterate over all conversations for a lead
+# NOTE: to iterate over a lead's conversations you MUST use their Intercom User ID and type User
+intercom.conversations.find_all(intercom_user_id: lead.id, type: 'user').each {|convo| ... }
 
 # FINDING A SINGLE CONVERSATION
 conversation = intercom.conversations.find(id: '1')
 
 # INTERACTING WITH THE PARTS OF A CONVERSATION
 # Getting the subject of a part (only applies to email-based conversations)
-conversation.rendered_message.subject
+conversation.source.subject
+
 # Get the part_type of the first part
-conversation.conversation_parts[0].part_type
+conversation.conversation_parts.first.part_type
+
 # Get the body of the second part
 conversation.conversation_parts[1].body
 
+# Get statistics related to the conversation
+conversation.statistics.time_to_admin_reply
+conversation.statistics.last_assignment_at
+
+# Get information on the sla applied to a conversation
+conversation.sla_applied.sla_name
+
 # REPLYING TO CONVERSATIONS
 # User (identified by email) replies with a comment
 intercom.conversations.reply(id: conversation.id, type: 'user', email: 'joe@example.com', message_type: 'comment', body: 'foo')
@@ -219,6 +349,9 @@ intercom.conversations.reply(id: conversation.id, type: 'admin', admin_id: '123'
 # User (identified by email) replies with a comment and attachment
 intercom.conversations.reply(id: conversation.id, type: 'user', email: 'joe@example.com', message_type: 'comment', body: 'foo', attachment_urls: ['http://www.example.com/attachment.jpg'])
 
+#reply to a user's last conversation
+intercom.conversations.reply_to_last(type: 'user', body: 'Thanks again', message_type: 'comment', user_id: '12345', admin_id: '123')
+
 # Open
 intercom.conversations.open(id: conversation.id, admin_id: '123')
 
@@ -226,26 +359,75 @@ intercom.conversations.open(id: conversation.id, admin_id: '123')
 intercom.conversations.close(id: conversation.id, admin_id: '123')
 
 # Assign
+# Note: Conversations can be assigned to teams. However, the entity that performs the operation of assigning the conversation has to be an existing teammate.
+#       You can use `intercom.admins.all.each {|a| puts a.inspect if a.type == 'admin' }` to list all of your teammates.
 intercom.conversations.assign(id: conversation.id, admin_id: '123', assignee_id: '124')
 
+# Snooze
+intercom.conversations.snooze(id: conversation.id, admin_id: '123', snoozed_until: 9999999999)
+
 # Reply and Open
 intercom.conversations.reply(id: conversation.id, type: 'admin', admin_id: '123', message_type: 'open', body: 'bar')
 
 # Reply and Close
 intercom.conversations.reply(id: conversation.id, type: 'admin', admin_id: '123', message_type: 'close', body: 'bar')
 
+# Admin reply to last conversation
+intercom.conversations.reply_to_last(intercom_user_id: '5678', type: 'admin', admin_id: '123', message_type: 'comment', body: 'bar')
+
+# User reply to last conversation
+intercom.conversations.reply_to_last(intercom_user_id: '5678', type: 'user', message_type: 'comment', body: 'bar')
+
 # ASSIGNING CONVERSATIONS TO ADMINS
 intercom.conversations.reply(id: conversation.id, type: 'admin', assignee_id: assignee_admin.id, admin_id: admin.id, message_type: 'assignment')
 
 # MARKING A CONVERSATION AS READ
 intercom.conversations.mark_read(conversation.id)
+
+# RUN ASSIGNMENT RULES
+intercom.conversations.run_assignment_rules(conversation.id)
+
+# Search for conversations
+# For full detail on possible queries, please refer to the API documentation:
+# https://developers.intercom.com/intercom-api-reference/reference
+
+# Search for open conversations sorted by the created_at date
+conversations = intercom.conversations.search(
+  query: {
+    field: "open",
+    operator: "=",
+    value: true
+  },
+  sort_field: "created_at",
+  sort_order: "descending"
+)
+conversations.each {|c| p c.id}
+
+# Tagging for conversations
+tag = intercom.tags.find(id: "2")
+conversation = intercom.conversations.find(id: "1")
+
+# An Admin ID is required to add or remove tag on a conversation
+admin = intercom.admins.find(id: "1")
+
+# Add a tag to a conversation
+conversation.add_tag(id: tag.id, admin_id: admin.id)
+
+# Remove a tag from a conversation
+conversation.remove_tag(id: tag.id, admin_id: admin.id)
+
+# Add a contact to a conversation
+conversation.add_contact(admin_id: admin.id, customer: { intercom_user_id: contact.id })
+
+# Remove a contact from a conversation
+conversation.remove_contact(id: contact.id, admin_id: admin.id)
 ```
 
 #### Full loading of an embedded entity
 ```ruby
-# Given a conversation with a partial user, load the full user. This can be
+# Given a conversation with a partial contact, load the full contact. This can be
 # done for any entity
-intercom.users.load(conversation.user)
+intercom.contacts.load(conversation.contacts.first)
 ```
 
 #### Sending messages
@@ -314,156 +496,148 @@ intercom.messages.create({
 })
 ```
 
-#### Events
+#### Admins
 ```ruby
-intercom.events.create(
-  event_name: "invited-friend",
-  created_at: Time.now.to_i,
-  email: user.email,
-  metadata: {
-    "invitee_email" => "pi@example.org",
-    invite_code: "ADDAFRIEND",
-    "found_date" => 12909364407
-  }
-)
-
-# Retrieve event list for user with id:'123abc'
- intercom.events.find_all("type" => "user", "intercom_user_id" => "123abc")
+# Find access token owner (only with Personal Access Token and OAuth)
+intercom.admins.me
+# Find an admin by id
+intercom.admins.find(id: admin_id)
+# Iterate over all admins
+intercom.admins.all.each {|admin| puts admin.email }
+```
 
+#### Teams
+```ruby
+# Find a team by id
+intercom.teams.find(id: team_id)
+# Iterate over all teams
+intercom.teams.all.each {|team| puts team.name }
 ```
 
-Metadata Objects support a few simple types that Intercom can present on your behalf
+#### Counts
 
 ```ruby
-intercom.events.create(
-  event_name: "placed-order",
-  email: current_user.email,
-  created_at: 1403001013,
-  metadata: {
-    order_date: Time.now.to_i,
-    stripe_invoice: 'inv_3434343434',
-    order_number: {
-      value: '3434-3434',
-      url: 'https://example.org/orders/3434-3434'
-    },
-    price: {
-      currency: 'usd',
-      amount: 2999
-    }
-  }
-)
+# App-wide counts
+intercom.counts.for_app
+
+# Users in segment counts
+intercom.counts.for_type(type: 'user', count: 'segment')
 ```
 
-The metadata key values in the example are treated as follows-
-- order_date: a Date (key ends with '_date')
-- stripe_invoice: The identifier of the Stripe invoice (has a 'stripe_invoice' key)
-- order_number: a Rich Link (value contains 'url' and 'value' keys)
-- price: An Amount in US Dollars (value contains 'amount' and 'currency' keys)
+#### Subscriptions
 
-*NB:* This version of the gem reserves the field name `type` in Event data.
+Subscribe to events in Intercom to receive webhooks.
 
-Bulk operations.
 ```ruby
-# Submit bulk job, to create events
-intercom.events.submit_bulk_job(create_items: [
-  {
-    event_name: "ordered-item",
-    created_at: 1438944980,
-    user_id: "314159",
-    metadata: {
-      order_date: 1438944980,
-      stripe_invoice: "inv_3434343434"
-    }
-  },
-  {
-    event_name: "invited-friend",
-    created_at: 1438944979,
-    user_id: "314159",
-    metadata: {
-      invitee_email: "pi@example.org",
-      invite_code: "ADDAFRIEND"
-    }
-  }
-])
-
-
-# Submit bulk job, to add items to existing job
-intercom.events.submit_bulk_job(create_items: [
-  {
-    event_name: "ordered-item",
-    created_at: 1438944980,
-    user_id: "314159",
-    metadata: {
-      order_date: 1438944980,
-      stripe_invoice: "inv_3434343434"
-    }
-  },
-  {
-    event_name: "invited-friend",
-    created_at: 1438944979,
-    user_id: "314159",
-    metadata: {
-      invitee_email: "pi@example.org",
-      invite_code: "ADDAFRIEND"
-    }
-  }
-], job_id:'job_abcd1234')
-```
+# create a subscription
+intercom.subscriptions.create(url: "http://example.com", topics: ["user.created"])
+
+# fetch a subscription
+intercom.subscriptions.find(id: "nsub_123456789")
 
-### Contacts
+# delete a subscription
+subscription = intercom.subscriptions.find(id: "nsub_123456789")
+intercom.subscriptions.delete(subscription)
 
-`Contacts` represent logged out users of your application.
+# list subscriptions
+intercom.subscriptions.all
+```
 
+#### Articles
 ```ruby
-# Create a contact
-contact = intercom.contacts.create(email: "some_contact@example.com")
+# Create an article
+article = intercom.articles.create(title: "New Article", author_id: "123456")
 
-# Update a contact
-contact.custom_attributes['foo'] = 'bar'
-intercom.contacts.save(contact)
+# Create an article with translations
+article = intercom.articles.create(title: "New Article",
+                                   author_id: "123456",
+                                   translated_content: {fr: {title: "Nouvel Article"}, es: {title: "Nuevo artículo"}})
 
-# Find contacts by email
-contacts = intercom.contacts.find_all(email: "some_contact@example.com")
+# Fetch an article
+intercom.articles.find(id: "123456")
 
-# Convert a contact into a user
-intercom.contacts.convert(contact, user)
+# List all articles
+articles = intercom.articles.all
+articles.each { |article| p article.title }
 
-# Delete a contact
-intercom.contacts.delete(contact)
-```
+# Update an article
+article.title = "Article Updated!"
+intercom.articles.save(article)
 
-### Counts
+# Update an article's existing translation
+article.translated_content.en.title = "English Updated!"
+intercom.articles.save(article)
 
-```ruby
-# App-wide counts
-intercom.counts.for_app
+# Update an article by adding a new translation
+article.translated_content.es = {title: "Artículo en español"}
+intercom.articles.save(article)
 
-# Users in segment counts
-intercom.counts.for_type(type: 'user', count: 'segment')
+# Delete an article
+intercom.articles.delete(article)
 ```
 
-### Subscriptions
+#### Collections
+```ruby
+# Create a collection
+collection = intercom.collections.create(name: "New Collection")
 
-Subscribe to events in Intercom to receive webhooks.
+# Create a collection with translations
+collection = intercom.collections.create(name: "New Collection",
+                                         translated_content: {fr: {name: "Nouvelle collection"}, es: {name: "Nueva colección"}})
 
-```ruby
-# create a subscription
-intercom.subscriptions.create(url: "http://example.com", topics: ["user.created"])
+# Fetch a collection
+intercom.collections.find(id: "123456")
 
-# fetch a subscription
-intercom.subscriptions.find(id: "nsub_123456789")
+# List all collections
+collections = intercom.collections.all
+collections.each { |collection| p collection.name }
 
-# list subscriptions
-intercom.subscriptions.all
+# Update a collection
+collection.name = "Collection updated!"
+intercom.collections.save(collection)
+
+# Update a collection's existing translation
+collection.translated_content.en.name = "English Updated!"
+intercom.collections.save(collection)
+
+# Update a collection by adding a new translation
+collection.translated_content.es = {name: "Colección en español", description: "Descripción en español"}
+intercom.collections.save(collection)
+
+# Delete an collection
+intercom.collections.delete(collection)
 ```
-### Bulk jobs
 
+#### Sections
 ```ruby
-# fetch a job
-intercom.jobs.find(id: 'job_abcd1234')
+# Create a section
+section = intercom.sections.create(name: "New Section", parent_id: "123456")
+
+# Create a section with translations
+section = intercom.sections.create(name: "New Section",
+                                   translated_content: {fr: {name: "Nouvelle section"}, es: {name: "Nueva sección"}})
+
+# Fetch a section
+intercom.sections.find(id: "123456")
 
-# fetch a job's error feed
-intercom.jobs.errors(id: 'job_abcd1234')
+# List all sections
+sections = intercom.sections.all
+sections.each { |section| p section.name }
+
+# Update a section
+section.name = "Section updated!"
+intercom.sections.save(section)
+
+# Update a section's existing translation
+section.translated_content.en.name = "English Updated!"
+intercom.collections.save(section)
+
+# Update a section by adding a new translation
+section.translated_content.es = {name: "Sección en español"}
+intercom.collections.save(section)
+
+# Delete an section
+intercom.sections.delete(section)
 ```
 
 ### Errors
@@ -480,6 +654,7 @@ Intercom::ServerError
 Intercom::ServiceUnavailableError
 Intercom::ServiceConnectionError
 Intercom::ResourceNotFound
+Intercom::BlockedUserError
 Intercom::BadRequestError
 Intercom::RateLimitExceeded
 Intercom::AttributeNotSetError # Raised when you try to call a getter that does not exist on an object
@@ -496,6 +671,12 @@ intercom.rate_limit_details
 #=> {:limit=>180, :remaining=>179, :reset_at=>2014-10-07 14:58:00 +0100}
 ```
 
+You can handle the rate limits yourself but a simple option is to use the handle_rate_limit flag.
+This will automatically catch the 429 rate limit exceeded error and wait until the reset time to retry. After three retries a rate limit exception will be raised. Encountering this error frequently may require a revisiting of your usage of the API.
+
+```
+intercom = Intercom::Client.new(token: ENV['AT'], handle_rate_limit: true)
+```
 
 ### Pull Requests
 
@@ -512,3 +693,24 @@ intercom.rate_limit_details
 - **Send coherent history**. Make sure each individual commit in your pull
   request is meaningful. If you had to make multiple intermediate commits while
   developing, please squash them before sending them to us.
+
+### Development
+
+#### Running tests
+
+```bash
+# all tests
+bundle exec spec
+
+# unit tests
+bundle exec spec:unit
+
+# integration tests
+bundle exec spec:integration
+
+# single test file
+bundle exec m spec/unit/intercom/job_spec.rb
+
+# single test
+bundle exec m spec/unit/intercom/job_spec.rb:49
+```