百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
I

intercom-ruby

> 编程语言
开源

Intercom API 的 Ruby 绑定

281 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

Intercom API 的 Ruby 绑定

intercom-ruby

Ruby bindings for the Intercom API.

Project Updates

Maintenance

We're currently building a new team to provide in-depth and dedicated SDK support.

In the meantime, we'll be operating on limited capacity, meaning all pull requests will be evaluated on a best effort basis and will be limited to critical issues.

We'll communicate all relevant updates as we build this new team and support strategy in the coming months.

API Documentation

Gem Documentation

For generating Intercom JavaScript script tags for Rails, please see intercom/intercom-rails

Upgrading information

Version 4 of intercom-ruby is not backwards compatible with previous versions. Please see our migration guide for full details of breaking changes.

This version of the gem is compatible with Ruby 2.1 and above.

Installation

bash
gem install intercom

Using bundler:

bundler
gem 'intercom', '~> 4.1'

Basic Usage

Configure your client

If you already have a personal access token you can find it here. If you want to create or learn more about personal access tokens then you can find more info here.

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.2')

If you are building a third party application you can get your access_tokens by setting-up-oauth for Intercom. You can also use the omniauth-intercom lib which is a middleware helping you to handle the authentication process with Intercom.

Resources

Resources this API supports:

…

Examples

Contacts

Note that this is a new resource compatible only with the new Contacts API released in API v2.0.

…

Visitors

ruby
# 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

…

Data Attributes

Data Attributes are a type of metadata used to describe your customer and company models. These include standard and custom attributes.

…

Events

…

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
# 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: [{company_id: "42ea2f1b93891f6a99000427"}])

# Untag Companies
tag = intercom.tags.untag(name: 'blue', companies: [{ company_id: "42ea2f1b93891f6a99000427" }])

# Delete Tags

# Note : If there any depedent objects for the tag we are trying to delete, then an error TagHasDependentObjects will be thrown.
tag = intercom.tags.find(id:"123")
intercom.tags.delete(tag)

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}"}

Conversations

…

Full loading of an embedded entity

ruby
# Given a conversation with a partial contact, load the full contact. This can be
# done for any entity
intercom.contacts.load(conversation.contacts.first)

Sending messages

…

Admins

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 }

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 }

Counts

ruby
# App-wide counts
intercom.counts.for_app

# Users in segment counts
intercom.counts.for_type(type: 'user', count: 'segment')

Subscriptions

Subscribe to events in Intercom to receive webhooks.

ruby
# create a subscription
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

Subscription Types

List all the subscription types that a contact can opt in to

ruby

# fetch a subscription
intercom.subscription_types.find(id: "1")

intercom.subscription_types.all

Articles

…

Collections

…

Sections

…

Phone Call Redirect (switch)

ruby
# Create a redirect
redirect = intercom.phone_call_redirect.create(phone_number: "+353871234567")

Data Content Export

ruby
# Create a data export
export = intercom.export_content.create(created_at_after: 1667566801, created_at_before: 1668085202)

#View a data export
export = intercom.export_content.find(id: 'k0e27ohsyvh8ef3m')

# Cancel a data export
export = intercom.export_content.cancel('k0e27ohsyvh8ef3m')

Errors

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.

You do not need to deal with the HTTP response from an API call directly. If there is an unsuccessful response then an error that is a subclass of Intercom::IntercomError will be raised. If desired, you can get at the http_code of an Intercom::IntercomError via its http_code method.

The list of different error subclasses are listed below. As they all inherit off Intercom::IntercomError you can choose to rescue Intercom::IntercomError or else rescue the more specific error subclass.

ruby
Intercom::AuthenticationError
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
Intercom::MultipleMatchingUsersError
Intercom::HttpError # Raised when response object is unexpectedly nil
Intercom::GatewayTimeoutError

Rate Limiting

Calling your client's rate_limit_details returns a Hash that contains details about your app's current rate limit.

ruby
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.

ruby
intercom = Intercom::Client.new(token: ENV['AT'], handle_rate_limit: true)

Pull Requests

  • Add tests! Your patch won't be accepted if it doesn't have tests.

  • Document any change in behaviour. Make sure the README and any other relevant documentation are kept up-to-date.

  • Create topic branches. Don't ask us to pull from your master branch.

  • One pull request per feature. If you want to do more than one thing, send multiple pull requests.

  • 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 rake spec

# unit tests
bundle exec rake spec:unit

# integration tests
bundle exec rake 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

Issues· 15 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言