{"id":13880418,"url":"https://github.com/intercom/intercom-rails","last_synced_at":"2025-05-14T06:05:47.631Z","repository":{"id":2743271,"uuid":"3739296","full_name":"intercom/intercom-rails","owner":"intercom","description":"The easiest way to install Intercom in a Rails app.","archived":false,"fork":false,"pushed_at":"2025-03-11T11:32:46.000Z","size":642,"stargazers_count":281,"open_issues_count":53,"forks_count":108,"subscribers_count":182,"default_branch":"master","last_synced_at":"2025-04-13T17:46:36.748Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://developers.intercom.io/reference","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intercom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-03-16T13:48:57.000Z","updated_at":"2025-03-11T11:20:38.000Z","dependencies_parsed_at":"2022-08-06T12:31:14.647Z","dependency_job_id":"112c42d0-b15a-4315-9b58-0812928363d3","html_url":"https://github.com/intercom/intercom-rails","commit_stats":{"total_commits":353,"total_committers":73,"mean_commits":4.835616438356165,"dds":0.6090651558073654,"last_synced_commit":"0e654beb0f0b63d73886c1bb90d2291c857bc32a"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fintercom-rails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fintercom-rails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fintercom-rails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intercom%2Fintercom-rails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intercom","download_url":"https://codeload.github.com/intercom/intercom-rails/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254078643,"owners_count":22011010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:03:01.177Z","updated_at":"2025-05-14T06:05:47.587Z","avatar_url":"https://github.com/intercom.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# IntercomRails\n\nThe easiest way to install Intercom in a rails app.\n\nFor interacting with the Intercom REST API, use the `intercom` gem (https://github.com/intercom/intercom-ruby)\n\nRequires Ruby 2.0 or higher.\n\n## Installation\nAdd this to your Gemfile:\n\n```ruby\ngem \"intercom-rails\"\n```\n\nThen run:\n\n```\nbundle install\n```\n\nTake note of your `app_id` from [here](https://app.intercom.com/a/apps/_/settings/web) and generate a config file:\n\n```\nrails generate intercom:config YOUR-APP-ID\n```\n\nTo make installing Intercom easy, where possible a `\u003cscript\u003e` tag **will be automatically inserted before the closing `\u003c/body\u003e` tag**. For most Rails apps, **you won't need to do any extra config**. Having trouble? Check out troubleshooting below.\n\n\n### Live Chat\nWith the Intercom Messenger you can [chat](https://www.intercom.com/live-chat) with users and visitors to your web site. Include the Intercom Messenger on every page by setting:\n```ruby\n  config.include_for_logged_out_users = true\n```\n\n### Disabling automatic insertion\n\nTo disable automatic insertion for a particular controller or action you can:\n\n```ruby\n  skip_after_action :intercom_rails_auto_include\n```\n\n### Troubleshooting\nIf things are not working make sure that:\n\n* You've generated a config file with your `app_id` as detailed above.\n* Your user object responds to an `id` or `email` method.\n* Your current user is accessible in your controllers as `current_user` or `@user`, if not in `config/initializers/intercom.rb`:\n```ruby\n  config.user.current = Proc.new { current_user_object }\n```\nIf your users can be defined in different ways in your app you can also pass an array as follows:\n```ruby\n  config.user.current = [Proc.new { current_user_object }, Proc.new { @user_object }]\n```\n* If you want the Intercom Messenger to be available when there is no current user,  set `config.include_for_logged_out_users = true` in your config.\n\nFeel free to mail us: team@intercom.io, if you're still having trouble and we'll work with you to get you sorted.\n\n## Configuration\n\n### API Secret\nIt is possible to enable Identity Verification for the Intercom Messenger and you can find the documentation in how to do it [here](https://developers.intercom.com/docs/enable-secure-mode-on-your-web-product). We strongly encourage doing this as it makes your installation more secure! If you want to use this feature, ensure you set your Identity Verification Secret as the API secret in `config/initializers/intercom.rb`:\n\n```ruby\n  config.api_secret = '123456'\n```\n**Note: This example is just for the sake of simplicity, you should never include this secret in source control. Instead, you should use the Rails [secret config](http://guides.rubyonrails.org/4_1_release_notes.html#config-secrets-yml) feature.**\n\n### Shutdown\nWe make use of first-party cookies so that we can identify your users the next time they open your messenger. When people share devices with someone else, they might be able to see the most recently logged in user’s conversation history until the cookie expires. Because of this, it’s very important to properly shutdown Intercom when a user’s session on your app ends (either manually or due to an automated logout).\n\n#### Using Devise\n\nIf you use devise, you can override (if not already done) the session_controller by replacing in your `config/routes.rb` file:\n```ruby\ndevise_for :users\n```\nwith\n```ruby\ndevise_for :users, controllers: { sessions: \"sessions\" }\n```\n\nThen you can use the following code to prepare Intercom Shutdown on log out in your `app/session_controller.rb`\n\n```ruby\nclass SessionsController \u003c Devise::SessionsController\n\n  after_action :prepare_intercom_shutdown, only: [:destroy]\n\n  # Your logic here\n\n  protected\n  def prepare_intercom_shutdown\n    IntercomRails::ShutdownHelper.prepare_intercom_shutdown(session)\n  end\nend\n```\n\nAssuming that the `destroy` method of session_controller redirects to your `visitors_controller.rb#index` method, edit your `visitors_controller` as follow :\n\n\n```ruby\nclass VisitorsController \u003c ApplicationController\n  after_action :intercom_shutdown, only: [:index]\n\n  def index\n    # You logic here\n  end\n\n  # You logic here\n\n  protected\n  def intercom_shutdown\n    IntercomRails::ShutdownHelper.intercom_shutdown(session, cookies, request.domain)\n  end\nend\n```\n\n#### Using another service\n\nIf you use another service than Devise or if you implemented your own authentication service, you can call the following method in a controller to shutdown Intercom on logout.\n\n```ruby\nIntercomRails::ShutdownHelper::intercom_shutdown_helper(cookies, domain)\n```\n\n**Be aware that if you call this method before a 'redirect_to' (quite common on logout) it will have no impact** as it is impossible to update cookies when you use a redirection.\nBut you can use the same logic as the `devise` implementation above.\n\n#### Session Duration\n\nTo add a `session_duration` variable (in ms) to the widget, add the following line to `config/initializers/intercom.rb`:\n\n```ruby\nconfig.session_duration = 5 * 60 * 1000\n```\nThat will force your Intercom session to expire after 5 minutes which is the minimum amount of time authorized.\n\nMore information about how session_duration works in [intercom documentation](https://docs.intercom.io/configuring-for-your-product-or-site/customizing-the-intercom-messenger#secure-user-conversations-configure-your-cookie-timeout)\n\n### User Custom data attributes\n\nYou can associate any attributes, specific to your app, with a user in Intercom.\nFor custom data attributes you want updated on every request set them in `config/initializers/intercom.rb`, the latest value will be sent to Intercom on each page visit.\n\nConfigure what attributes will be sent using either a:\n\n  * `Proc` which will be passed the current user object\n  * Or, a method which will be sent to the current user object\n\ne.g.\n\n```ruby\n  config.user.custom_data = {\n    :plan =\u003e Proc.new { |user| user.plan.name },\n    :is_paid =\u003e Proc.new { |user| user.plan.present? },\n    :email_verified =\u003e :email_verified?\n  }\n  # or If User::custom_data method returns a hash\n  config.user.custom_data = Proc.new { |user| user.custom_data }\n```\n\nIn some situations you'll want to set some custom data attribute specific to a request.\nYou can do this using the `intercom_custom_data` helper available in your controllers:\n\n```ruby\nclass AppsController \u003c ActionController::Base\n  def activate\n    intercom_custom_data.user[:app_activated_at] = Time.now\n    ...\n  end\n\n  def destroy\n    intercom_custom_data.user[:app_deleted_at] = Time.now\n    ...\n  end\nend\n```\n\nAttributes must be accessible in order to sync with intercom.\nAdditionally, attributes ending in \"_at\" will be parsed as times.\n\n### Custom attributes for non-signed up users\n\nIn situations where you want to pass in specific request based custom data for non-signed up users or leads,\nyou can do that by setting custom attributes in ```config/initializers/intercom.rb```.\n\nAny of these attributes can be used to pass in custom data.\n\nExample:\n\n**in ```config/initializers/intercom.rb```**\n\n```ruby\nconfig.user.lead_attributes = %w(ref_data utm_source)\n```\n\n**in ```app/controllers/posts_controller.rb```**\n\n```ruby\nclass PostsController \u003c ApplicationController\n\n  before_action :set_custom_attributes, only: [:index]\n\n  # Your logic here\n\n  protected\n  def set_custom_attributes\n    intercom_custom_data.user[:ref_data] = params[:api_ref_data]\n    intercom_custom_data.user[:utm_source] = params[:api_utm_source]\n  end\nend\n```\n\n### Companies\n\nBy default, Intercom treats all Users as unrelated individuals. If for example you know users are part of a company, you can group them as such.\n\nRead more about it here http://docs.intercom.io/configuring-Intercom/grouping-users-by-company\n\nBasic usage is as follows - in `config/initializers/intercom.rb`\n\n```ruby\nconfig.company.current = Proc.new { current_company }\n```\n\n`current_company` is the method/variable that contains the user's current company in your controllers.\nIf you are using devise you should replace `current_company` with `current_user.company` in the above code and every time you see 'current_company' in your configuration file.\nThis will result in injecting the user current company in the widget settings.\n\nand like with Users, you can set custom attribute on companies too:\n\n```ruby\nconfig.company.custom_data = {\n  :number_of_messages =\u003e Proc.new { |app| app.messages.count },\n  :is_interesting =\u003e :is_interesting?\n}\n```\n\nIn some situations you'll want to set some custom company data attribute specific to a request.\nYou can do this similarly to user data attribute set by using the `intercom_custom_data` helper available in your controllers:\n\n```ruby\nclass AppsController \u003c ActionController::Base\n  def activate\n    intercom_custom_data.company[:app_activated_at] = Time.now\n    ...\n  end\n\n  def destroy\n    intercom_custom_data.company[:app_deleted_at] = Time.now\n    ...\n  end\nend\n```\n\n### Messenger\nIntercom includes an in-app messenger which allows a user to read messages and start conversations.\n\nBy default Intercom will add a button that opens the messenger to the page. If you want to customize the style of the link that opens the messenger:\n\n```ruby\n  config.inbox.style = :custom\n```\n\nWith this option enabled, clicks on any element with an id of `Intercom` will open the messenger. So the simplest option here would be to add something like the following to your layout:\n\n```html\n  \u003ca id=\"Intercom\"\u003eSupport\u003c/a\u003e\n```\n\nYou can customize the CSS selector, by setting\n\n```ruby\n  config.inbox.custom_activator = '.intercom-link'\n```\n\nYou can hide default launcher button, by setting\n\n```ruby\n  config.hide_default_launcher = true\n```\n\nYou can read more about configuring the messenger in your applications settings, within Intercom.\n\n### Environments\n\nBy default Intercom will be automatically inserted in development and production Rails environments. If you would like to specify the environments in which Intercom should be inserted, you can do so as follows:\n\n```ruby\n  config.enabled_environments = [\"production\"]\n```\n\n### Manually Inserting the Intercom Javascript\n\nSome 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 `\u003c/body\u003e` tag:\n\n```erb\n  \u003c%= intercom_script_tag %\u003e\n```\n\nThis 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:\n\n```erb\n\u003c% if logged_in? %\u003e\n  \u003c%= intercom_script_tag({\n    :app_id =\u003e 'your-app-id',\n    :user_id =\u003e current_user.id,\n    :email =\u003e current_user.email,\n    :name =\u003e current_user.name,\n    :created_at =\u003e current_user.created_at,\n    :custom_data =\u003e {\n      'plan' =\u003e current_user.plan.name\n    }\n  }) %\u003e\n\u003c% end %\u003e\n```\n\nYou can also override `IntercomRails::Config` options such as your `api_secret`, or widget configuration with a second hash:\n\n```erb\n\u003c% if logged_in? %\u003e\n  \u003c%= intercom_script_tag({\n    :app_id =\u003e 'your-app-id',\n    :user_id =\u003e current_user.id,\n    :email =\u003e current_user.email,\n    :name =\u003e current_user.name,\n    :created_at =\u003e current_user.created_at\n  }, {\n    :secret =\u003e 'your-apps-api-secret',\n    :widget =\u003e {:activator =\u003e '#Intercom'}\n  }) %\u003e\n\u003c% end %\u003e\n```\n### Content Security Policy Level 2 (CSP) support\nAs of version 0.2.30 this gem supports CSP, allowing you to whitelist the include code using both nonces and SHA-256 hashes.\n#### Automatic Insertion\nCSP support for automatic insertion exposes two namespaces that can be defined by the user via monkey patching:\n - String CoreExtensions::IntercomRails::AutoInclude.csp_nonce_hook(controller)\n - nil CoreExtensions::IntercomRails::AutoInclude.csp_sha256_hook(controller, SHA-256 whitelist entry)\n\nFor instance, a CSP nonce can be inserted using the [Github Secure Headers](https://github.com/github/secure_headers) gem with the following code:\n```ruby\nmodule CoreExtensions\n  module IntercomRails\n    module AutoInclude\n      def self.csp_nonce_hook(controller)\n        SecureHeaders.content_security_policy_script_nonce(controller.request)\n      end\n    end\n  end\nend\n```\nor, for whitelisting the SHA-256 hash:\n```ruby\nmodule CoreExtensions\n  module IntercomRails\n    module AutoInclude\n      def self.csp_sha256_hook(controller, sha256)\n        SecureHeaders.append_content_security_policy_directives(controller.request, {script_src: [sha256]})\n      end\n    end\n  end\nend\n```\n#### Manual Insertion\nCSP is supported in manual insertion as well, the request nonce can be passed as an option:\n```erb\n\u003c% if logged_in? %\u003e\n  \u003c%= intercom_script_tag({\n    :app_id =\u003e 'your-app-id',\n    :user_id =\u003e current_user.id,\n    :email =\u003e current_user.email,\n    :name =\u003e current_user.name,\n    :created_at =\u003e current_user.created_at\n  }, {\n    :secret =\u003e 'your-apps-api-secret',\n    :widget =\u003e {:activator =\u003e '#Intercom'},\n    :nonce =\u003e get_nonce_from_your_csp_framework\n  }) %\u003e\n\u003c% end %\u003e\n```\nThe SHA-256 hash is available using `csp_sha256` just after generating the tag itself:\n```erb\n\u003c%= intercom_script_tag %\u003e\n\u003c% add_entry_to_csp_whitelist(intercom_script_tag.csp_sha256) %\u003e\n```\n\n## Deleting your users\nIf you delete a user from your system, you should also delete them from Intercom lest they still receive messages.\n\nYou can do this using the [intercom-ruby](https://github.com/intercom/intercom-ruby) gem. In the example below we're using an ActiveJob to perform the delete in the background.\n\n```\nclass User\n  after_destroy { DeleteFromIntercomJob.perform_later(self) }\nend\n\nclass DeleteFromIntercomJob \u003c ApplicationJob\n  def perform(user)\n    intercom = Intercom::Client.new\n    user = intercom.users.find(id: user.id)\n    deleted_user = intercom.users.delete(user)\n  end\nend\n```\n\n## Running tests/specs\n\nspecs should run on a clean clone of this repo, using the following commands. (developed against ruby 2.1.2 and 1.9.3)\n\n```\nbundle install\nbundle exec rake spec\nor\nbundle exec rspec spec/\n```\n\n\n## Pull Requests\n\n- **Add tests!** Your patch won't be accepted if it doesn't have tests.\n\n- **Document any change in behaviour**. Make sure the README and any other\n  relevant documentation are kept up-to-date.\n\n- **Create topic branches**. Don't ask us to pull from your master branch.\n\n- **One pull request per feature**. If you want to do more than one thing, send\n  multiple pull requests.\n\n- **Send coherent history**. Make sure each individual commit in your pull\n  request is meaningful. If you had to make multiple intermediate commits while\n  developing, please squash them before sending them to us.\n\n\n## Contributors\n\n- Dr Nic Williams (@drnic) - provided a rails generator for adding the Intercom javascript tag into your layout.\n- Alexander Chaychuk (@sashich) - fixed bug in user detection when users not persisted (e.g. new session view with devise).\n\n## License\n\nintercom-rails is released under the [MIT License](http://www.opensource.org/licenses/MIT).\n\n## Copyright\n\nCopyright (c) 2011-2020 Intercom, Inc.  All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintercom%2Fintercom-rails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintercom%2Fintercom-rails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintercom%2Fintercom-rails/lists"}