IntercomRails

The easiest way to install Intercom in a rails app.

For interacting with the Intercom REST API, use the intercom gem (https://github.com/intercom/intercom-ruby)

Installation

Add this to your Gemfile:

gem "intercom-rails"

Then run:

bundle install

Take note of your app_id from here and generate a config file:

rails generate intercom:config YOUR-APP-ID

To make installing Intercom as easy as possible, where possible a <script> tag will be automatically inserted before the closing </body> tag. For most Rails apps, you won't need to do any extra config. Having trouble? Check out troubleshooting below.

Disabling automatic insertion

To disable automatic insertion for a particular controller or action you can:

  skip_after_filter :intercom_rails_auto_include

Troubleshooting

If it's not working make sure:

You've generated a config file with your app_id as detailed above.
Your user object responds to an id or email method.
Your current user is accessible in your controllers as current_user or @user, if not in config/initializers/intercom.rb:

  config.user.current = Proc.new { current_user_object }

Feel free to mail us: team@intercom.io, if you're still having trouble.

Configuration

API Secret

If you want to use secure mode, ensure you set your API secret in config/initializers/intercom.rb:

  config.api_secret = '123456'

Custom Data

Custom data lets you associate any data, specific to your app, with a user in Intercom. For custom data variables you want updated on every request set them in config/initializers/intercom.rb.

You can give either a:

Proc which will be passed the current user object
Or, a method which will be sent to the current user object

to generate the values of the custom data:

  config.user.custom_data = {
    :plan => Proc.new { |user| user.plan.name },
    :is_paid => Proc.new { |user| user.plan.present? },
    :email_verified => :email_verified?
  }

In some situations you'll want to set some custom data specific to a request. You can do this using the intercom_custom_data helper available in your controllers:

class AppsController < ActionController::Base
  def activate
    intercom_custom_data.user[:app_activated_at] = Time.now
    ...
  end

  def destroy
    intercom_custom_data.user[:app_deleted_at] = Time.now
    ...
  end
end

Inbox

Intercom includes an inbox which allows a user to read their past conversations with your app, and start new conversations. It's hidden by default, you can include a link to open it by adding a line to config/initializers/intercom.rb:

To use the default link style, which requires no extra config and includes a small question mark icon in the bottom right corner of your app:

  config.inbox.style = :default

If you want to customize the style of the link that opens the inbox:

  config.inbox.style = :custom

This option attaches the inbox open event to the click event of an element with an id of #Intercom. So the simplest option here would be to add something like the following to your layout:

  <a id="#Intercom">Support</a>

You can read more about configuring the Inbox within Intercom (Config menu -> Inbox Link).

Manually Inserting the Intercom Javascript

Some situations may require manually inserting the Intercom script tag. If you simply wish to place the Intercom javascript in a different place within the page or, on a page without a closing </body> tag:

  <%= intercom_script_tag %>

This will behave exactly the same as the default auto-install. If for whatever reason you can't use auto-install, you can also provide a hash of user data as the first argument:

<% if logged_in? %>
  <%= intercom_script_tag({
    :app_id => 'your-app-id',
    :user_id => current_user.id,
    :email => current_user.email,
    :name => current_user.name,
    :created_at => current_user.created_at,
    :custom_data => {
      'plan' => current_user.plan.name
    }
  }) %>
<% end %>

You can also override IntercomRails::Config options such as your api_secret, or widget configuration with a second hash:

<% if logged_in? %>
  <%= intercom_script_tag({
    :app_id => 'your-app-id',
    :user_id => current_user.id,
    :email => current_user.email,
    :name => current_user.name,
    :created_at => current_user.created_at
  }, {
    :secret => 'your-apps-api-secret',
    :widget => {:activator => '#Intercom'}
  }) %>
<% end %>

Importing your users

To get started faster with Intercom, IntercomRails includes a Rake task that will do an initial import of your users:

rake intercom:import

Any custom data defined in config/initializers/intercom.rb will also be sent.

Contributors

Dr Nic Williams (@drnic) - provided a rails generator for adding the Intercom javascript tag into your layout.
Alexander Chaychuk (@sashich) - fixed bug in user detection when users not persisted (e.g. new session view with devise).

allangrant/intercom-rails