intercom 3.5.10 → 3.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0f98bf7f9725ad035949ca88859ba807a6323a83
-  data.tar.gz: 97e46a4507500d311495e11114fb80d0715cb0a0
+SHA256:
+  metadata.gz: 204538ee7ce2d0d8b41b4c0b8ff4c6d80084570c410850ba02fc936a14292b8d
+  data.tar.gz: 6704e411dcc92ae860d3d519bdd592e35ac2b931fb20e188b934bb4228232f12
 SHA512:
-  metadata.gz: 8c83c5d9c5ad9d4844b5b8f7c3602e6bf76cbbb9e9836b264acbdcfdb5e3567310c1441e23c7cd0b2dac30f0200bbea46175fe9eea5c130aa49d16e9ca5cd2d4
-  data.tar.gz: b480c171fd98135e719c37be86b0d13f7288f65130583d863afad3dd32acdc42de3e66be8941620047ba57db9fc54548b10307cbed55bd5278563825e6728de0
+  metadata.gz: 496d153506de79e3527db4ba20176dd375a29ad37ab259121030f8b70ab5ba934db19fa917c28755d7205f092df2756f493742f47dbbc1eab895ac8ffa15a330
+  data.tar.gz: 7248e5d8c2734a256c499b3145758965b2efd48b0b531a337e1337553724c40f156263b67f8db5612ed5bc2c92fb6a57b3d3068d2360647e412f8861c1a9f205

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

@@ -18,23 +18,29 @@ 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', '~> 3.9.4'
 
 ## 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: '1.0')
+```
+
 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.
 
@@ -43,6 +49,7 @@ 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/teams
     https://api.intercom.io/contacts
     https://api.intercom.io/companies
     https://api.intercom.io/counts
@@ -54,7 +61,6 @@ Resources this API supports:
     https://api.intercom.io/messages
     https://api.intercom.io/subscriptions
     https://api.intercom.io/jobs
-    https://api.intercom.io/bulk
 
 ### Examples
 
@@ -69,9 +75,13 @@ user = intercom.users.find(user_id: "1")
 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
+# archive a user
 user = intercom.users.find(id: "1")
-deleted_user = intercom.users.delete(user)
+archived_user = intercom.users.archive(user)
+# request a hard delete for a user
+(https://developers.intercom.com/intercom-api-reference/reference#delete-users)
+user = intercom.users.find(id: "1")
+deleted_user = intercom.users.request_hard_delete(user)
 # Update custom_attributes for a user
 user.custom_attributes["average_monthly_spend"] = 1234.56
 intercom.users.save(user)
@@ -88,6 +98,14 @@ intercom.users.all.map {|user| user.email }
 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}"}
+
+# Duplicate users? If you have duplicate users you can search for them via their email address.
+# Note this feature is only available from version 1.1 of the API so you will need to switch to that version
+# This will return multiple users if they have the same email address
+usrs = intercom.users.find_all(type: 'users', email: 'myemail@example.com', page: 1, per_page: 10, order: :asc)
+# This returns a user.list so you can access it via
+usrs.to_a.each_with_index {|usr, i| puts "#{i+1}: #{usr.id}"};
+
 # 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
@@ -100,16 +118,6 @@ result = intercom.users.scroll.next
 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')
 ```
 
 #### Admins
@@ -122,6 +130,14 @@ intercom.admins.find(id: admin_id)
 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 }
+```
+
 #### Companies
 ```ruby
 # Add a user to one or more companies
@@ -143,8 +159,13 @@ intercom.companies.save(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 list of users in a company by Intercom Company ID
+intercom.companies.users_by_intercom_company_id(company.id)
+# Get a list of users in a company by external company_id
+intercom.companies.users_by_company_id(company.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
 ```
 
 #### Tags
@@ -157,7 +178,7 @@ intercom.tags.untag(name: 'blue',  users: [{user_id: "42ea2f1b93891f6a99000427"}
 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"}])
 ```
 
 #### Segments
@@ -182,6 +203,9 @@ 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 +213,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,6 +223,11 @@ 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')
@@ -219,6 +248,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,14 +258,25 @@ 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')
 
@@ -327,6 +370,13 @@ intercom.events.create(
   }
 )
 
+# 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")
 
@@ -362,77 +412,73 @@ The metadata key values in the example are treated as follows-
 
 *NB:* This version of the gem reserves the field name `type` in Event data.
 
-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')
-```
-
-### Contacts
+#### Contacts
 
 `Contacts` represent logged out users of your application.
+Note that `contacts` are referred to as `leads` in the [Intercom](https://developers.intercom.com/intercom-api-reference/reference#leads)
 
 ```ruby
 # Create a contact
 contact = intercom.contacts.create(email: "some_contact@example.com")
 
-# Update a contact
+# Update a contact (via create method)
+# You can update a contact by calling the create method but you MUST provide an id or user_id
+# If you just provide an email, for example, it will create a new contact
+# See https://developers.intercom.com/intercom-api-reference/reference#update-lead for more detail
+contact = intercom.contacts.create(email: "some_contact@example.com", id: "3be0398668071a6bc6850413", name:"update_contact")
+
+# Update a contact (via contact object)
 contact.custom_attributes['foo'] = 'bar'
 intercom.contacts.save(contact)
 
 # Find contacts by email
 contacts = intercom.contacts.find_all(email: "some_contact@example.com")
 
+# Using find to search for contacts by email
+contact_list = intercom.contacts.find(email: "some_contact@example.com")
+# This returns a Contact object with type contact.list
+# Note: Multiple contacts can be returned in this list if there are multiple matching contacts found
+# #<Intercom::Contact:0x00007ff3a80789f8
+#   @changed_fields=#<Set: {}>,
+#   @contacts=
+#     [{"type"=>"contact",
+#       "id"=>"5b7fd9b683681ac52274b9c7",
+#       "user_id"=>"05bc4d17-72cc-433e-88ae-0bf88db5d0e6",
+#       "anonymous"=>true,
+#       "email"=>"some_contact@example.com",
+#       ...}],
+#   @custom_attributes={},
+#   @limited=false,
+#   @pages=#<Intercom::Pages:0x00007ff3a7413c58 @changed_fields=#<Set: {}>, @next=nil, @page=1, @per_page=50, @total_pages=1, @type="pages">,
+#   @total_count=1,
+#   @type="contact.list">
+# Access the contact's data
+contact_list.contacts.first
+
 # Convert a contact into a user
-intercom.contacts.convert(contact, user)
+contact = intercom.contacts.find(id: "536e564f316c83104c000020")
+intercom.contacts.convert(contact, Intercom::User.new(email: email))
+# Using find with email will not work here. See https://github.com/intercom/intercom-ruby/issues/419 for more information
+
+# archive a contact
+intercom.contacts.archive(contact)
 
-# Delete a contact
-intercom.contacts.delete(contact)
+# Get a large list of contacts using scroll
+intercom.contacts.scroll.each { |lead| puts lead.id}
+# Please see users scroll for more details of how to use scroll
 ```
 
-### Counts
+#### Customers
+
+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).
+
+```ruby
+# Search for customers
+customers = intercom.customers.search(query: { "field": "name", "operator": "=", "value": "Alice"}, per_page: 50, sort_field: "name", sort_order: "ascending")
+customers.each { |customer| p customer.name }
+```
+
+#### Counts
 
 ```ruby
 # App-wide counts
@@ -442,7 +488,7 @@ intercom.counts.for_app
 intercom.counts.for_type(type: 'user', count: 'segment')
 ```
 
-### Subscriptions
+#### Subscriptions
 
 Subscribe to events in Intercom to receive webhooks.
 
@@ -453,18 +499,13 @@ intercom.subscriptions.create(url: "http://example.com", topics: ["user.created"
 # fetch a subscription
 intercom.subscriptions.find(id: "nsub_123456789")
 
+# delete a subscription
+subscription = intercom.subscriptions.find(id: "nsub_123456789")
+intercom.subscriptions.delete(subscription)
+
 # list subscriptions
 intercom.subscriptions.all
 ```
-### Bulk jobs
-
-```ruby
-# fetch a job
-intercom.jobs.find(id: 'job_abcd1234')
-
-# fetch a job's error feed
-intercom.jobs.errors(id: 'job_abcd1234')
-```
 
 ### Errors
 
@@ -480,6 +521,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 +538,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 +560,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
+```