intercom-java
Java bindings for the Intercom API
Project Updates
Retirement of Bintray/JCenter
This project was previously publishing releases to JCenter, which is being retired by JFrog on May 1st 2021.
To allow continued access to past versions, we've migrated them to Maven Central.
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.
Add a dependency
The distribution is hosted on mavenCentral. To use the client, you can add the mavenCentral repository to your dependencies.
Maven
Add the project declaration to your pom.xml:
<dependency>
<groupId>io.intercom</groupId>
<artifactId>intercom-java</artifactId>
<version>2.8.2</version>
</dependency>Gradle
Add mavenCentral to your repositories block:
repositories {
mavenCentral()
}and add the project to the dependencies block in your build.gradle:
dependencies {
implementation 'io.intercom:intercom-java:2.8.2'
} SBT
Add mavenCentral to your resolvers in your build.sbt:
resolvers += "mavenCentral" at "https://repo1.maven.org/maven2"and add the project to your libraryDependencies in your build.sbt:
libraryDependencies += "io.intercom" % "intercom-java" % "2.8.2"Resources
Resources this API supports:
Authorization
If you already have an access token you can find it here. If you want to create or learn more about access tokens then you can find more info here.
# With an OAuth or Access token:
Intercom.setToken("da39a3ee5e6b4b0d3255bfef95601890afd80709");If you are building a third party application you can get your OAuth token by setting-up-oauth for Intercom.
Usage
Users
// Create a user
User user = new User()
.setEmail("[email protected]")
.setUserId("1")
.addCustomAttribute(CustomAttribute.newStringAttribute("role", "sergeant"))
.addCustomAttribute(CustomAttribute.newBooleanAttribute("browncoat", true));
User created = User.create(user);
// Find user by id
user = User.find("541a144b201ebf2ec5000001");
// Find user by email
Map<String, String> params = Maps.newHashMap();
params.put("email", "[email protected]");
user = User.find(params);
// Find user by user_id
params = Maps.newHashMap();
params.put("user_id", "1");
user = User.find(params);
// Update custom_attributes for a user
user.addCustomAttribute(CustomAttribute.newStringAttribute("role", "captain"));
User.update(user);
// Iterate over all users (up to 10k records, to read all use Scroll API)
UserCollection users = User.list();
while(users.hasNext()) {
System.out.println(users.next().getUserId());
}
// List users (sorting)
Map<String, String> params = Maps.newHashMap();
params.put("sort", "updated_at");
params.put("order", "asc");
UserCollection users = User.list(params);
// List users (created within the past X days)
Map<String, String> params = Maps.newHashMap();
params.put("created_since", "2");
UserCollection users = User.list(params);
// List users by tag
Map<String, String> params = Maps.newHashMap();
params.put("tag_id", "12345");
UserCollection users = User.list(params);
// List users by segment
Map<String, String> params = Maps.newHashMap();
params.put("segment_id", "1234567890abcdef12345678");
UserCollection users = User.list(params);
// Retrieve users via Scroll API
ScrollableUserCollection usersScroll = User.scroll();
List<User> users = usersScroll.getPage();
usersScroll = usersScroll.scroll();
// Archive a user by Intercom ID
User user = User.find("541a144b201ebf2ec5000001");
User.archive(user.getId());
// Archive a user by user_id
Map<String, String> params = Maps.newHashMap();
params.put("user_id", "1");
User.archive(params);
// Archive a user by email
Map<String, String> params = Maps.newHashMap();
params.put("email", "[email protected]");
User.archive(params);
// Permanently delete a user by Intercom ID
User.permanentDelete("541a144b201ebf2ec5000001");Contacts
Contacts were added in version 1.1 of the client.
// Create a Contact
Contact contact = new Contact()
.setEmail("[email protected]")
.addCustomAttribute(newStringAttribute("role", "fence"));
Contact created = Contact.create(contact);
// Find a single contact by server supplied user id or id
contact = Contact.findByID("541a144b201ebf2ec5000002");
contact = Contact.findByUserID("e1a7d875-d83a-46f7-86f4-73be98a98584");
// Update a contact
contact.setName("Stitch Hessian");
Contact updated = Contact.update(contact);
// Update a contact by ID
Contact contact = new Contact().setID("541a144b201ebf2ec5000002").setName("Stitch Hessian");
Contact updated = Contact.update(contact);
// Update a contact by User ID
Contact contact = new Contact().setUserID("e1a7d875-d83a-46f7-86f4-73be98a98584").setName("Stitch Hessian");
Contact updated = Contact.update(contact);
// Read a contact list by email
ContactCollection contacts = Contact.listByEmail("[email protected]");
while(contacts.hasNext()) {
System.out.println(contacts.next());
}
// Iterate over all contacts (up to 10k records, to read all use Scroll API)
ContactCollection allContacts = Contact.list();
while(allContacts.hasNext()) {
System.out.println(allContacts.next());
}
// Retrieve contacts via Scroll API
ScrollableContactCollection contactsScroll = Contact.scroll();
List<Contact> contacts = contactsScroll.getPage();
contactsScroll = contactsScroll.scroll();
// List contacts (sorting)
Map<String, String> params = Maps.newHashMap();
params.put("sort", "created_at");
params.put("order", "asc");
ContactCollection contacts = Contact.list(params);
// Remove a contact
Contact.delete(contact);
// Remove a contact by id
Contact.delete(contact.getID());
// Remove a contact by user_id
Contact.deleteByUserID(contact.getUserID());
// Convert a contact
User converted = Contact.convert(contact, user);Visitors
// Find visitor by ID
Visitor visitor = Visitor.findByID("5b69565fa737210d1c2127f1");
// Find visitor by User ID
Visitor visitor = Visitor.findByUserID("6a347bc9-0b96-4925-bbbc-1f8b11f94c50");
// Update a visitor
Visitor visitor = Visitor.findByID("5b69565fa737210d1c2127f1");
visitor.setName("Visitor's Name");
Visitor.update(visitor);
// Delete a visitor by ID
Visitor.delete("5b69565fa737210d1c2127f1");
// Delete a visitor
Visitor visitor = Visitor.findByUserID("6a347bc9-0b96-4925-bbbc-1f8b11f94c50");
Visitor.delete(visitor);
// Convert a visitor to a lead
Visitor visitor = Visitor.findByUserID("6a347bc9-0b96-4925-bbbc-1f8b11f94c50");
Contact contact = Visitor.convertToContact(visitor);
// Convert a visitor to a user
Visitor visitor = Visitor.findByUserID("6a347bc9-0b96-4925-bbbc-1f8b11f94c50");
User user = new User();
user.setUserId("1");
User convertUser = Visitor.convertToUser(visitor, user);Companies
// Create a company
Company company = new Company();
company.setName("Blue Sun");
company.setCompanyID("1");
company.setMonthlySpend(123.10f);
company.setPlan(new Company.Plan("premium"));
company.addCustomAttribute(CustomAttribute.newIntegerAttribute("foddstuff-items", 246));
company.addCustomAttribute(CustomAttribute.newStringAttribute("bestseller", "fruity oaty bar"));
Company.create(company);
// Find a company by company_id
map = Maps.newHashMap();
map.put("company_id", "1");
Company company = Company.find(map);
// Find a company by name
map = Maps.newHashMap();
map.put("name", "Blue Sun");
Company company = Company.find(map);
// Find a company by id
Company company = Company.find("541a144b201ebf2ec5000001");
// Update a company
company.setName("Blue Sun Corporation");
Company.update(company);
// Iterate over all companies
CompanyCollection companies = Company.list();
while(companies.hasNext()) {
System.out.println(companies.next().getName());
}
// Retrieve companies via Scroll API
ScrollableCompanyCollection companiesScroll = Company.scroll();
List<Company> companies = companiesScroll.getPage();
companiesScroll = companiesScroll.scroll();
// Get a list of users in a company
map = Maps.newHashMap();
map.put("company_id", "6");
UserCollection users = Company.listUsers(map);
// Add a user to one or more companies
User user = User.find("541a144b201ebf2ec5000001");
user.addCompany(company);
User.update(user);Admins
// Iterate over all admins
AdminCollection admins = Admin.list();
while(admins.hasNext()) {
System.out.println(admins.next().getName());
}
// Find admin by ID
Admin admin = Admin.find("123456");
// Set admin as away and enable away mode reassignment
Admin admin = Admin.setAwayMode("123456", true, true);Events
// Create an event with a user ID
// This is only valid for users
Event event = new Event()
.setEventName("bought-hat")
.setUserID("1")
.putMetadata("invitee_email", "[email protected]")
.putMetadata("found_date", System.currentTimeMillis())
.putMetadata("new_signup", true);
Event.create(event);
// Create an event with an email
// This is only valid for users
Event event = new Event()
.setEventName("bought-hat")
.setEmail("[email protected]");
Event.create(event);
// Create an event with an ID
// This is valid for both users and leads
Event event = new Event()
.setEventName("bought-hat")
.setId("599d6aeeda850883ed8ba7c2");
Event.create(event);
// List events of a user
Map<String, String> params = Maps.newHashMap();
params.put("type", "user");
params.put("user_id", "1");
// Alternatively list by Intercom ID
// params.put("intercom_user_id", "541a144b201ebf2ec5000001");
// Or by email
// params.put("email", "[email protected]");
EventCollection events = Event.list(params);
while (events.hasNext()) {
System.out.println(events.next().getEventName());
}
// List event summaries of a user
Map<String, String> params = Maps.newHashMap();
params.put("type", "user");
params.put("user_id", "1");
// Alternatively list by Intercom ID
// params.put("intercom_user_id", "541a144b201ebf2ec5000001");
// Or by email
// params.put("email", "[email protected]");
EventSummaryCollection eventSummaryCollection = Event.listSummary(params);
for(EventSummary eventSummary : eventSummaryCollection.getEventSummaries()){
System.out.println(eventSummary);
}Tags
// create a tag
Tag tag = new Tag().setName("alliance");
tag = Tag.create(tag);
// update a tag
tag.setName("independent");
tag = Tag.update(tag);
// tag and untag users
User one = new User().setEmail("[email protected]");
User two = new User().setEmail("[email protected]").untag();
User.create(one);
User.create(two);
Tag.tag(tag, one, two);
// tag and untag contacts
Contact contact1 = Contact.findByID("5ab313046e4997e35bc13e7c");
Contact contact2 = Contact.findByUserID("697ea3e0-227d-4d70-b776-1652e94f9583").untag();
Tag.tag(tag, contact1, contact2);
// iterate over all tags
final TagCollection tags = Tag.list();
while (tags.hasNext()) {
System.out.println(tags.next().getId());
}
// tag and untag companies
Company c1 = new Company().setCompanyID("1");
Company c2 = new Company().setCompanyID("2").untag();
Company.create(c1);
Company.create(c2);
Tag.tag(tag, c1, c2);
// delete a tag
Tag.delete(tag);Segments
// Find a segment
Segment segment = Segment.find("1");
// Update a segment
segment.setName("new name");
Segment.update(segment);
// Iterate over all segments
SegmentCollection segments = Segment.list();
while(segments.hasNext()) {
System.out.println(segments.next().getId());
}Notes
// create a user note
User user = new User().setId("5310d8e8598c9a0b24000005");
Author author = new Author().setId("1");
Note note = new Note()
.setUser(user)
.setAuthor(author)
.setBody("The note");
Note.create(note);
// Find a note by id
note = Note.find("1");
// Iterate over all notes for a user via their user_id
Map<String, String> params = Maps.newHashMap();
params.put("user_id", "1");
NoteCollection notes = Note.list(params);
while(notes.hasNext()) {
System.out.println(notes.next().getBody());
}
// Iterate over all notes for a user via their email address
params = Maps.newHashMap();
params.put("email", "[email protected]");
notes = Note.list(params);
while(notes.hasNext()) {
System.out.println(notes.next().getBody());
}Conversations
// send a message to a user
User user = new User().setId("5310d8e8598c9a0b24000005");
Admin admin = new Admin().setId("1");
AdminMessage adminMessage = new AdminMessage()
.setAdmin(admin)
.setUser(user)
.setSubject("This Land")
.setBody("Har har har! Mine is an evil laugh!")
.setMessageType("email")
.setTemplate("plain");
Conversation.create(adminMessage);
// send a message from a user
UserMessage userMessage = new UserMessage()
.setBody("Hey! Is there, is there a reward?")
.setFrom(user);
Conversation.create(userMessage);
// send a message from a contact
ContactMessage contactMessage = new ContactMessage()
.setBody("Hey! Is there, is there a reward?")
.setFrom(contact);
Conversation.create(contactMessage);
//list all conversations
ConversationCollection conversations = Conversation.list();
while (conversations.hasNext()) {
Conversation conversation = conversations.next();
}
// find admin conversations
Map<String, String> params = Maps.newHashMap();
params.put("type", "admin");
params.put("admin_id", "1");
ConversationCollection adminConversations = Conversation.list(params);
while (adminConversations.hasNext()) {
Conversation conversation = adminConversations.next();
}
// find user conversations
params = Maps.newHashMap();
params.put("type", "user");
params.put("user_id", "1");
ConversationCollection userConversations = Conversation.list(params);
while (userConversations.hasNext()) {
Conversation conversation = userConversations.next();
}
// find a conversation by id
final Conversation conversation = Conversation.find("66");
ConversationMessage conversationMessage = conversation.getConversationMessage();
ConversationPartCollection parts = conversation.getConversationPartCollection();
List<ConversationPart> partList = parts.getPage();
for (ConversationPart part : partList) {
String partType = part.getPartType();
Author author = part.getAuthor();
String body = part.getBody();
}
ConversationPart part = conversation.getMostRecentConversationPart();
Admin assignee = conversation.getAssignee();
User user = conversation.getUser();
// Find all open conversations assigned to an admin and render as plaintext
params = Maps.newHashMap();
params.put("type", "admin");
params.put("admin_id", "7");
params.put("display_as", "plaintext");
ConversationCollection openForAdmin = Conversation.list(params);
// admin reply
Admin admin = new Admin().setId("1");
AdminReply adminReply = new AdminReply(admin);
adminReply.setBody("These apples are healthsome");
adminReply.setAttachmentUrls(new String[]{"http://www.example.com/attachment.jpg"}); // optional - list of attachments
Conversation.reply("66", adminReply);
// admin close
Admin admin = new Admin().setId("1");
AdminReply adminReply = new AdminReply(admin);
adminReply.setMessageType("close");
Conversation.reply("66", adminReply);
// admin snooze
Admin admin = new Admin().setId("1");
AdminReply adminReply = new AdminReply(admin);
adminReply.setSnoozedUntil(1549092382);
Conversation.reply("66", adminReply);
// admin open / unsnooze
Admin admin = new Admin().setId("1");
AdminReply adminReply = new AdminReply(admin);
adminReply.setMessageType("open");
Conversation.reply("66", adminReply);
// user reply
User user1 = new User().setId("5310d8e8598c9a0b24000005");
UserReply userReply = new UserReply(user1);
userReply.setBody("Mighty fine shindig");
userReply.setAttachmentUrls(new String[]{"http://www.example.com/attachment.jpg"}); // optional - list of attachments
System.out.println(MapperSupport.objectMapper().writeValueAsString(userReply));
Conversation.reply("66", userReply);
// run assignment rules
Conversation.runAssignmentRules("19240007891");
// mark conversation as read
Conversation.markAsRead("66");Webhooks
// create a subscription
Subscription subscription = new Subscription();
subscription.setUrl(new URI("https://example.org/webhooks/1"));
subscription.addTopic(Subscription.Topic.USER_CREATED);
subscription.addTopic(Subscription.Topic.USER_TAG_CREATED);
Subscription.create(subscription);
// create a subscribtion and subscribe to events
Subscription subscription = new Subscription();
subscription.addTopic(Subscription.Topic.EVENT_CREATED);
Map<String,ArrayList<String>> metadata = new HashMap<String, ArrayList<String>>();
ArrayList<String> events = new ArrayList<String>(Arrays.asList("cart"));
metadata.put("event_names", events);
subscription.setMetadata(metadata);
subscription.setMetadata(metadata);
Subscription.create(subscription);
// update a subscription
Subscription subscription = Subscription.find("nsub_60ca7690-4020-11e4-b789-4961958e51bd");
subscription.addTopic(Subscription.Topic.COMPANY_CREATED);
Subscription updatedSubscription = Subscription.update(subscription);
// delete a subscription
Subscription subscription = new Subscription();
subscription.setId("nsub_83793feb-8394-4cb6-91d6-68ef4dd08a8e");
Subscription deletedSubscription = Subscription.delete(subscription);
// find a subscription
subscription = Subscription.find("nsub_60ca7690-4020-11e4-b789-4961958e51bd");
// ping a subscription by ID
Subscription.ping("nsub_60ca7690-4020-11e4-b789-4961958e51bd");
// ping a subscription by subscription object
subscription = Subscription.find("nsub_60ca7690-4020-11e4-b789-4961958e51bd");
Subscription.ping(subscription);
// list subscriptions
SubscriptionCollection list = Subscription.list();
while(list.hasNext()) {
Subscription sub = list.next();
String appID = sub.getAppID();
String serviceType = sub.getServiceType();
List<Subscription.Topic> topics = sub.getTopics();
String hubSecret = sub.getHubSecret();
}
// notification sent feed
NotificationCollection sent = Subscription.sentFeed(subscription.getId());
while(sent.hasNext()) {
Notification notification = sent.next();
String id = notification.getId();
String topic = notification.getTopic();
NotificationData data = notification.getData();
String type = data.getType();
// raw map representation of the payload
Map item = data.getItem();
}
// notification error feed
NotificationErrorCollection errors = Subscription.errorFeed(subscription.getId());
while (errors.hasNext()) {
NotificationError notificationError = errors.next();
RequestResponseCapture capture = notificationError.getCapture();
URI requestURI = capture.getRequestURI();
String requestMethod = capture.getRequestMethod();
Map<String, String> requestHeaders = capture.getRequestHeaders();
String requestEntity = capture.getRequestEntity();
int statusCode = capture.getResponseStatusCode();
Map<String, String> responseHeaders = capture.getResponseHeaders();
String responseEntity = capture.getResponseEntity();
}
// consume a webhook notification
InputStream jsonStream = ...;
final Notification notification = Notification.readJSON(jsonStream);
String jsonString = ...;
final Notification notification = Notification.readJSON(jsonString);Counts
// app totals
Counts.Totals totals = Counts.appTotals();
System.out.println("companies: " + totals.getCompany().getValue());
System.out.println("segments: :" + totals.getSegment().getValue());
System.out.println("tags: :" + totals.getTag().getValue());
System.out.println("users: :" + totals.getUser().getValue());
// conversation totals
Counts.Conversation conversationTotals = Counts.conversationTotals();
System.out.println("assigned: " + conversationTotals.getAssigned());
System.out.println("closed: :" + conversationTotals.getClosed());
System.out.println("open: :" + conversationTotals.getOpen());
System.out.println("unassigned: :" + conversationTotals.getUnassigned());
// admin open/close counts
Counts.Conversation adminCounts = Counts.conversationAdmins();
List<Admin> admins = adminCounts.getAdmins();
for (Admin admin : admins) {
System.out.println(admin.getName() + ": " + admin.getClosed() + ", " + admin.getOpen());
}
// tag user counts
System.out.println("tag user counts: ");
List<Counts.CountItem> tags = Counts.userTags();
for (Counts.CountItem tag : tags) {
System.out.println(tag.getName()+": " +tag.getValue());
}
// segment user counts
List<Counts.CountItem> segments = Counts.userSegments();
for (Counts.CountItem segment : segments) {
System.out.println(segment.getName()+": " +segment.getValue());
}
// company user counts
List<Counts.CountItem> companyUsers = Counts.companyUsers();
for (Counts.CountItem company : companyUsers) {
System.out.println(company.getName()+": " +company.getValue());
}
// company tag counts
List<Counts.CountItem> companyTags = Counts.companyTags();
for (Counts.CountItem tag : companyTags) {
System.out.println(tag.getName()+": " +tag.getValue());
}Idioms
HTTP requests
To signal local versus remote methods, calls that result in HTTP requests are performed
using static methods, for example User.find(). The objects returned by static methods
are built from server responses. The exception to the static idiom is where the next(),
hasNext() and nextPage() methods on Collections are used to abstract over pagination.
Pagination
Some API classes have static list() methods that correspond to paginated API responses.
These return a Collection object (eg UserCollection) which can be iterated in two
ways
-
The collection's
getPage(),hasNextPage()andnextPage()methods - these are useful when you want to fetch one or just a few pages directly. -
Java's inbuilt iterator methods
next()andhasNext()- these are useful when you want to fetch data without manually handling pagination. -
User and Contact listing only works up to 10k records. To retrieve all records use the Scroll API via
scroll()
Error handling
You do not need to deal with the HTTP response from an API call directly.
If there is an unsuccessful response then an IntercomException or a subclass
of IntercomException will be thrown. The exception will have Error objects
that can be examined via getErrorCollection and getFirstError for more detail.
The API throws the following runtime exceptions -
- AuthorizationException: for a 401 or 403 response
- InvalidException: for a 422 response or a local validation failure
- RateLimitException: for a 429 rate limit exceeded response
- ClientException: for a general 4xx response
- ServerException: for a 500 or 503 response
- IntercomException: general exception
Configuration
HTTP
The client can be configured to accept any http stack that implements
java.net.HttpURLConnection by implementing the HttpConnectorSupplier
interface.
For example, to use OkHttp as a connection supplier, create a supplier class -
public class OkHttpSupplier implements HttpConnectorSupplier {
private final OkUrlFactory urlFactory;
public OkHttpSupplier(OkUrlFactory urlFactory) {
this.urlFactory = urlFactory;
}
@Override
public HttpURLConnection connect(URI uri) throws IOException {
return urlFactory.open(uri.toURL());
}
}and hand a supplier to the Intercom object -
final OkHttpClient client = new OkHttpClient();
final OkUrlFactory factory = new OkUrlFactory(client);
final OkHttpSupplier supplier = new OkHttpSupplier(factory);
Intercom.setHttpConnectorSupplier(supplier);Timeouts
The default connection and request timeouts can be set in milliseconds using the
Intercom.setConnectionTimeout and Intercom.setRequestTimeout methods.
Target API Server
The base URI to target can be changed for testing purposes
URI baseURI = new URI("https://example.org/server");
Intercom.setApiBaseURI(baseURI);
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent