Migration guide for v4

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