Migration guide for v4 · intercom/intercom-ruby Wiki · GitHub
Skip to content

Repository navigation

Migration guide for v4

Jump to bottom
Matthew Murray edited this page Jan 30, 2020 · 2 revisions

Version 4 of the intercom Ruby SDK contains a number of breaking changes. It has been designed to work with Intercom API version 2.0 and above. See Changelog and API v2.0 documentation for more detail.

This guide will help you update your integration so that it keeps working as expected after you upgrade to v4.

Breaking changes

Deprecated classes

Deprecated Class Replacement Class Notes
User Contact Users & leads (formerly contacts) have been consolidated into one high level Contact resource.
Customer Contact Contact replaces the Customer resource and inherits all the functionality of that class.

Note that the old User and Contact resources will still work in this version of the SDK with API versions 1.4 and below. Contact has been replaced with Lead and User is unchanged.

New and replaced methods

This version of the SDK introduces the concept of nested resources, allowing you to manipulate a child resource through instance methods on its parent.

Operation Old method New/Replacement Method Returns
Create a note on a contact. intercom.notes.create contact.create_note(body: "foo") Note object.
List notes for a contact. intercom.notes.find_all contact.notes CollectionProxy object which responds to [], .each & .map.
Add a tag to a contact. intercom.tags.tag contact.add_tag(id: tag.id) Tag object.
Remove a tag from a contact. intercom.tags.untag contact.remove_tag(id: tag.id) Tag object.
List tags for a contact. - contact.tags CollectionProxy object which responds to [], .each & .map.
Add a contact to a company. user.companies = [{company_id: 6, name: "Intercom"}] contact.add_company(id: company.id) Company object.
Remove a contact from a company. user.companies = [{company_id: 6, name: "Intercom"}, "remove" : true] contact.remove_company(id: company.id) Company object.
List companies for a contact. - contact.companies CollectionProxy object which responds to [], .each & .map.
Get a list of contacts belonging to a given company. intercom.companies.users_by_intercom_company_id & .users_by_company_id company.contacts CollectionProxy object which responds to [], .each & .map.
Add a tag to a conversation. - conversation.add_tag(id: tag.id, admin_id: "123") Tag object
Remove a tag from a conversation. - conversation.remove_tag(id: tag.id, admin_id: "123") Tag object

New Features

  • Added support for new Contacts API released in API version 2.0.

  • Added support for Conversation Search and for Conversation model changes. The updated model can be found here.

  • New DataAttribute class to support the Data Attributes endpoint. See README for details on usage.

  • New method to run assignment rules on a conversation: intercom.conversations.run_assignment_rules(<convo_id>).

Clone this wiki locally