Intercom API Essential Guide

What type of API does Intercom provide?

Intercom utilizes a REST API for its platform. Here are the key points about Intercom's API:

REST API

• Intercom's API is built on REST principles.
• It serves as a core building block of the Intercom Platform.

Key Features

• Allows retrieving and updating information from Intercom accounts.
• Can be used to integrate Intercom functionality into other products.
• Provides flexibility for custom use cases.

Usage

• Developers can use the API to access Intercom data and functionality programmatically.
• It enables building integrations and custom applications on top of Intercom.

Best Practices

• When working with Intercom's REST API, follow standard REST conventions and best practices.
• Use appropriate HTTP methods (GET, POST, PUT, DELETE, etc.) for different operations.
• Handle authentication and authorization as specified in Intercom's API documentation.

While Intercom uses a REST API, it's worth noting that other API types like GraphQL and SOAP have their own advantages for certain use cases. However, REST remains a popular and widely supported choice for building APIs, especially for web and mobile applications.

Does the Intercom API have webhooks?

Yes, the official Intercom API does have webhooks. Here are the key points about Intercom's webhook functionality:

Webhook Availability

Intercom offers webhooks as a way to receive real-time notifications about events happening in your Intercom workspace.

Event Types

You can subscribe to various event types (called "topics" in Intercom) including:

• User events (e.g. user.created, user.updated)
• Conversation events (e.g. conversation.user.created, conversation.admin.replied)
• Ticket events (e.g. ticket.created)
• Content events (e.g. content_stat.email, content_stat.chat)
• And many more

Key Points

• Webhooks are associated with an Intercom app, not a specific workspace.
• You can configure the endpoint URL to receive webhook notifications in your Developer Hub.
• Intercom signs webhook notifications with an X-Hub-Signature header for verification.
• You need to select appropriate permissions to receive notifications for specific topics.

Setting Up Webhooks

1. Navigate to your App in the Developer Hub
2. Go to the Webhooks section under Configure
3. Set up your HTTPS endpoint URL
4. Subscribe to desired webhook topics

Best Practices

• Use HTTPS for your endpoint URL
• Verify webhook signatures to ensure notifications are from Intercom
• Handle retries and errors appropriately

In summary, Intercom's webhook system provides a robust way to receive real-time updates about various events in your Intercom workspace, allowing you to integrate Intercom data with your own systems and workflows.

Rate Limits and other limitations

Here are the key points about the API Rate Limits of the Intercom API:

Rate Limits for Private Apps

• Private apps have a default rate limit of 10,000 API calls per minute per app.
• There is also a limit of 25,000 API calls per minute per workspace for private apps.
• If a workspace has multiple private apps installed, each one contributes towards the total number of requests.

Rate Limits for Public Apps

• Public apps have a default rate limit of 10,000 API calls per minute for each app.
• There is also a limit of 25,000 API calls per minute per workspace for public apps.
• If a workspace has multiple public apps installed, each one has its own separate request limit without contributing to the others.

How Rate Limits Work

• The rate limits are distributed into 10 second windows.
• This means the amount of permitted requests resets every 10 seconds.
• For example, with a 1000 per minute limit, you can send a maximum of 166 operations per 10 second period.

Rate Limit Headers

The API returns rate limit information in response headers:

• X-RateLimit-Limit: Maximum number of requests allowed
• X-RateLimit-Remaining: Number of requests left in the current time window
• X-RateLimit-Reset: Time when the number of requests will be reset (as UNIX timestamp)

Handling Rate Limits

• If you exceed the rate limit, you'll receive a 429 Too Many Requests response.
• You can use the rate limit headers to check remaining requests and implement backoff logic.
• Strategies like randomized exponential backoff can be used to handle rate limiting.

Key Considerations

• Rate limits are in place to protect Intercom's systems from traffic spikes.
• Higher rate limits may be available by contacting Intercom support.
• Rate limits only apply to REST API calls, not webhook requests.

By understanding and properly handling these rate limits, developers can build robust integrations with the Intercom API while respecting the platform's constraints.

Latest API Version

Based on the search results provided, here are the key points regarding the most recent version of the Intercom API:

Current Version

The most recent version of the Intercom API appears to be version 2.11 [3][4].

Key Points

• The Intercom API uses versioning, with the version number incrementing by 0.1 each release, unless major new functionality is introduced, in which case it increments by 1 [1].

• Breaking changes are released in new API versions. Breaking changes can include things like removing operations, renaming parameters, adding required parameters, etc. [1]

• Developers can select which version of the API to use for their apps through the Developer Hub or by setting a version in the header of API calls [2].

• The latest version (2.11) includes some new features and breaking changes compared to previous versions [3].

How to Use the Latest Version

1. You can set the API version in the HTTP header of your requests using the Intercom-Version header [2].

2. Alternatively, you can update the version for your app in the Developer Hub [2].

3. It's recommended to test new versions before fully adopting them, as some changes may require code updates [2].

Best Practices

• Always test new versions of the API to ensure compatibility with your system before fully adopting them [2].

• For production apps, consider setting the version via HTTP header first, allowing you to ship new code and change the version simultaneously [2].

• Stay informed about changes by checking the changelog for each new version [3][4].

Remember to always refer to the official Intercom documentation for the most up-to-date information on API versions and changes.

How to get a Intercom developer account and API Keys?

To get a developer account for Intercom and create an API integration, you need to follow these steps:

1. Set up an Intercom workspace:

   • If you're building a private app for your own use, you can use your existing paid Intercom workspace.
   • If you're building a public app to share with other Intercom customers, you must create a free development workspace.

2. Create an app:

   • Go to the Intercom Developer Hub (https://developers.intercom.com/).
   • In the "Your apps" section, create a new app.
   • Select the workspace where you want to install the app (your paid workspace for private apps, or your development workspace for public apps).
   • Click "Create app" to generate the app and pre-install it in your selected workspace.

3. Get your authentication credentials:

   • For private apps, you'll use an Access Token. You can find this on the Authentication page of your app in the Developer Hub.
   • For public apps, you'll need to set up OAuth. This is required for apps that will access other people's Intercom data.

4. Start using the API:

   • Use your Access Token or OAuth credentials to authenticate your API requests.
   • You can now make API calls to Intercom, such as creating contacts, retrieving data, or performing other actions.

What can you do with the Intercom API?

Based on the provided information, here is a list of data models you can interact with using the Intercom API, along with key points about what is possible for each:

Contacts

• Fetch contact data attributes
• Create custom data attributes for contacts
• Update contact data attributes
• Access standard and custom attributes for contacts

Companies

• Fetch company data attributes
• Create custom data attributes for companies
• Update company data attributes
• Access standard and custom attributes for companies

Conversations

• Fetch conversation data attributes
• Access standard attributes for conversations

Admins

• Interact with admin/team member data

Articles

• Manage Help Center articles

Data Events

• Work with custom events and associated data

Messages

• Interact with various message types

Segments

• Manage contact/company segments

Tags

• Create and manage tags for contacts/companies

Teams

• Manage team data

Tickets

• Work with support ticket data

Visitors

• Access data for anonymous website visitors

Key points to consider:

• Data attributes can be of different types like string, integer, float, boolean, date, etc.
• Custom data attributes can be created for contacts and companies
• Some attributes may be writable via API, UI, or Messenger
• Attributes can be archived (for custom attributes)
• The API uses JSON encoding with UTF-8
• Regional hosting options are available (US, EU, Australia)
• Rate limiting is in place to control request frequency
• Common fields like 'type', 'id', and 'created_at' are present in many objects
• Custom attributes or metadata can be set for certain object types

When working with the Intercom API, ensure you're using the correct endpoints based on your workspace's regional hosting, and be mindful of rate limits and data types when interacting with different models.