### Synchronous vs. Asynchronous Clients Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/resources-overview.md Illustrates the setup and usage of both synchronous and asynchronous clients for Intercom API interactions. ```java // Synchronous Intercom client = Intercom.builder().token("api-key").build(); Contact contact = client.contacts().find(request); // Asynchronous AsyncIntercom asyncClient = AsyncIntercom.builder().token("api-key").build(); CompletableFuture contactFuture = asyncClient.contacts() .find(request); ``` -------------------------------- ### Basic Client Usage Source: https://github.com/intercom/intercom-java/blob/master/README.md Instantiate the Intercom client with your API token and use it to interact with the API. This example shows how to create an AI content import source. ```java package com.example.usage; import com.intercom.api.Intercom; import com.intercom.api.resources.aicontent.requests.CreateContentImportSourceRequest; public class Example { public static void main(String[] args) { Intercom client = Intercom .builder() .token("") .build(); client.aiContent().createContentImportSource( CreateContentImportSourceRequest .builder() .url("https://www.example.com") .build() ); } } ``` -------------------------------- ### Date Data Type Example Source: https://github.com/intercom/intercom-java/blob/master/reference.md Example of a Date data type, where the key ends with '_date' and the value is a Unix timestamp in UTC. ```json "contact_date": 1392036272 ``` -------------------------------- ### String Data Type Example Source: https://github.com/intercom/intercom-java/blob/master/reference.md Example of a String data type for an event property. ```json "source":"desktop" ``` -------------------------------- ### client.unstable.helpCenter.listHelpCenters Source: https://github.com/intercom/intercom-java/blob/master/reference.md Lists all Help Centers. This operation corresponds to a GET request to the Intercom API. ```APIDOC ## GET /help_center/help_centers ### Description Lists all Help Centers. ### Method GET ### Endpoint https://api.intercom.io/help_center/help_centers ### Request Example ```java client.helpCenters().list( ListHelpCentersRequest .builder() .build() ); ``` ``` -------------------------------- ### client.unstable.helpCenter.retrieveHelpCenter Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches the details of a single Help Center. This operation corresponds to a GET request to the Intercom API. ```APIDOC ## GET /help_center/help_center/{id} ### Description Fetches the details of a single Help Center. ### Method GET ### Endpoint https://api.intercom.io/help_center/help_center/ ### Parameters #### Path Parameters - **id** (Integer) - Required - The unique identifier for the collection which is given by Intercom. ### Request Example ```java client.unstable().helpCenter().retrieveHelpCenter( RetrieveHelpCenterRequest .builder() .id(1) .build() ); ``` ``` -------------------------------- ### FindContactRequest Builder Example Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/types.md Shows how to build a FindContactRequest using either a contact ID or an external ID. ```java FindContactRequest request = FindContactRequest.builder() .id("contact-123") .build(); // Or with external ID lookup FindContactRequest request = FindContactRequest.builder() .externalId("user-456") .build(); ``` -------------------------------- ### Interact with Companies API Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Provides examples of interacting with the Companies API using the initialized Intercom client, including retrieving and creating/updating companies. ```java // Companies API client.companies().retrieve(request); client.companies().createOrUpdate(request); ``` -------------------------------- ### Regenerate SDK using Fern CLI Source: https://github.com/intercom/intercom-java/blob/master/README.md Command to regenerate the Java SDK using the Fern CLI. Ensure Fern CLI is installed and navigate to the Fern config directory. ```bash fern generate --group java-sdk ``` -------------------------------- ### Interact with Contacts API Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Provides examples of interacting with the Contacts API using the initialized Intercom client, including listing and retrieving contacts. ```java // Contacts API client.contacts().list(request); client.contacts().retrieve(request); ``` -------------------------------- ### Access Raw HTTP Response for Contact Find Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/contacts.md This example shows how to retrieve the raw HTTP response when finding a contact. This is useful for accessing metadata like headers or the raw body directly. The `withRawResponse()` method must be called before the `find()` method. ```java var rawResponse = client.contacts() .withRawResponse() .find(request); Contact contact = rawResponse.body(); String contentType = rawResponse.headers().get("Content-Type"); ``` -------------------------------- ### Initialize Client with Custom Environment Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Demonstrates initializing an Intercom client and setting it to use a custom environment, such as the EU production environment. ```java Intercom client = Intercom.builder() .token("api-key") .environment(Environment.EU_PRODUCTION) .build(); ``` -------------------------------- ### Number Data Type Example Source: https://github.com/intercom/intercom-java/blob/master/reference.md Example of a Number data type for an event property. ```json "load": 3.67 ``` -------------------------------- ### Basic Intercom Client Initialization and Contact Listing Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/README.md Demonstrates how to create an Intercom client using a token and then list contacts, printing their emails. Requires importing necessary classes. ```java import com.intercom.api.Intercom; import com.intercom.api.resources.contacts.requests.ListContactsRequest; // Create client Intercom client = Intercom.builder() .token("your-api-token") .build(); // List contacts client.contacts().list( ListContactsRequest.builder() .perPage(50) .build() ).forEach(contact -> { System.out.println(contact.getEmail()); }); ``` -------------------------------- ### Link Data Type Example Source: https://github.com/intercom/intercom-java/blob/master/reference.md Example of a Link data type, where the value is an HTTP or HTTPS URI. ```json "article": "https://example.org/ab1de.html" ``` -------------------------------- ### Initialize AsyncIntercom Client Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Set up an asynchronous Intercom client using AsyncIntercom. Requires an API key and handles responses via callbacks. ```java import com.intercom.api.AsyncIntercom; AsyncIntercom client = AsyncIntercom.builder() .token("api-key") .build(); client.contacts() .find(request) .thenAccept(response -> { System.out.println("Found contact: " + response.getContact()); }) .exceptionally(e -> { System.err.println("Error: " + e.getMessage()); return null; }); ``` -------------------------------- ### Synchronous Client Initialization Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Demonstrates how to create a synchronous Intercom client. It covers creating a client with default settings, using a specific API token, and configuring advanced options like environment, timeouts, retries, and custom headers. ```APIDOC ## Synchronous Client Initialization ### Description Initialize the synchronous Intercom client using the `Intercom.builder()` pattern. This allows for default configuration, setting a specific API token, or customizing various aspects of the client. ### Usage **1. With Defaults:** Uses `INTERCOM_API_KEY` environment variable for authentication and targets the US production environment. ```java import com.intercom.api.Intercom; Intercom client = Intercom.builder().build(); ``` **2. With Token:** Specify the API token directly. ```java import com.intercom.api.Intercom; Intercom client = Intercom.builder() .token("your-api-token") .build(); ``` **3. With Custom Configuration:** Configure environment, timeouts, retries, and custom headers. ```java import com.intercom.api.Intercom; import com.intercom.api.core.Environment; import okhttp3.OkHttpClient; Intercom client = Intercom.builder() .token("your-api-token") .environment(Environment.EU_PRODUCTION) .timeout(30) .maxRetries(3) .addHeader("X-Custom-Header", "value") .httpClient(customOkHttpClient) .build(); ``` ### Builder Methods (`com.intercom.api.IntercomBuilder`) | Method | Parameter Type | Return Type | Description | |---|---|---|---| | `token(String token)` | string | IntercomBuilder | Set API token (defaults to INTERCOM_API_KEY environment variable) | | `environment(Environment environment)` | Environment | IntercomBuilder | Set API environment (US_PRODUCTION, EU_PRODUCTION, AU_PRODUCTION, or custom) | | `url(String url)` | string | IntercomBuilder | Set custom base URL (creates custom environment) | | `timeout(int timeout)` | int (seconds) | IntercomBuilder | Set request timeout in seconds (default: 60) | | `maxRetries(int maxRetries)` | int | IntercomBuilder | Set maximum retry attempts (default: 2) | | `httpClient(OkHttpClient httpClient)` | OkHttpClient | IntercomBuilder | Provide custom OkHttp client instance | | `addHeader(String name, String value)` | string, string | IntercomBuilder | Add custom header to all requests | | `build()` | — | Intercom | Build and return Intercom client instance | ``` -------------------------------- ### Accessing Intercom Resource Modules Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/resources-overview.md Demonstrates how to initialize the Intercom client and access different resource modules like contacts, companies, and conversations. ```java import com.intercom.api.Intercom; Intercom client = Intercom.builder().token("api-key").build(); client.admins() // Admin management client.contacts() // User and lead management client.companies() // Company management client.conversations() // Conversation management client.messages() // Message creation client.tickets() // Ticket management // ... and 29 more resource modules ``` -------------------------------- ### Monetary Amount Data Type Example Source: https://github.com/intercom/intercom-java/blob/master/reference.md Example of a Monetary Amount data type, where the value is a JSON object with 'amount' (in cents) and 'currency' keys. ```json "price": {"amount": 34999, "currency": "eur"} ``` -------------------------------- ### Rich Link Data Type Example Source: https://github.com/intercom/intercom-java/blob/master/reference.md Example of a Rich Link data type, where the value is a JSON object containing 'url' and 'value' keys. ```json "article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"} ``` -------------------------------- ### Handling TooManyRequestsError Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/errors.md Example of catching a TooManyRequestsError after the SDK has exhausted its retries. ```java try { client.contacts().list(request); } catch (TooManyRequestsError e) { // SDK has already retried this request up to maxRetries times System.out.println("Rate limit exceeded even after retries"); System.out.println("Retry-After: " + e.headers().get("Retry-After")); } ``` -------------------------------- ### Create Synchronous Client with Custom Configuration Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Initializes a synchronous Intercom client with custom configurations including API token, environment, timeout, max retries, custom headers, and a custom OkHttpClient. ```java import com.intercom.api.Intercom; import com.intercom.api.core.Environment; import okhttp3.OkHttpClient; Intercom client = Intercom.builder() .token("your-api-token") .environment(Environment.EU_PRODUCTION) .timeout(30) .maxRetries(3) .addHeader("X-Custom-Header", "value") .httpClient(customOkHttpClient) .build(); ``` -------------------------------- ### client.unstable.helpCenter.createCollection Source: https://github.com/intercom/intercom-java/blob/master/reference.md Creates a new collection in the help center. Supports setting name, description, translated content, parent collection, and help center ID. ```APIDOC ## client.unstable.helpCenter.createCollection ### Description You can create a new collection by making a POST request to `https://api.intercom.io/help_center/collections.` ### Parameters #### Request Body - **name** (String) - The name of the collection. For multilingual collections, this will be the name of the default language's content. - **description** (Optional) - The description of the collection. For multilingual collections, this will be the description of the default language's content. - **translatedContent** (Optional) - Translated content for the collection. - **parentId** (Optional) - The id of the parent collection. If `null` then it will be created as the first level collection. - **helpCenterId** (Optional) - The id of the help center where the collection will be created. If `null` then it will be created in the default help center. ### Request Example ```java client.helpCenters().collections().create( CreateCollectionRequest .builder() .name("Thanks for everything") .build() ); ``` ``` -------------------------------- ### Handling UnprocessableEntityError Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/errors.md Example of catching an UnprocessableEntityError when a request fails semantic validation. ```java try { client.companies().createOrUpdate(request); } catch (UnprocessableEntityError e) { System.out.println("Semantic validation failed: " + e.body()); } ``` -------------------------------- ### Search Articles Source: https://github.com/intercom/intercom-java/blob/master/reference.md Searches for articles. GET requests are made to the articles/search endpoint. ```java client.unstable().articles().searchArticles() ``` -------------------------------- ### client.customObjectInstances.createCustomObjectInstances Source: https://github.com/intercom/intercom-java/blob/master/reference.md Create or update a custom object instance. ```APIDOC ## client.customObjectInstances.createCustomObjectInstances ### Description Create or update a custom object instance. ### Method Not specified, likely a client method call. ### Endpoint Not specified. ### Parameters #### Request Body - **customObjectTypeIdentifier** (String) - Required - The unique identifier of the custom object type. - **externalId** (String) - Required - The external identifier for the custom object instance. - **externalCreatedAt** (Integer) - Optional - The timestamp when the custom object instance was created externally. - **externalUpdatedAt** (Integer) - Optional - The timestamp when the custom object instance was last updated externally. - **customAttributes** (Map>) - Optional - A map of custom attributes for the object instance. - **order_number** (String) - Optional - The order number. - **total_amount** (String) - Optional - The total amount. ### Request Example ```java client.customObjectInstances().createCustomObjectInstances( CreateOrUpdateCustomObjectInstanceRequest .builder() .customObjectTypeIdentifier("Order") .externalId("123") .externalCreatedAt(1392036272) .externalUpdatedAt(1392036272) .customAttributes( new HashMap>() {{ put("order_number", Optional.of("ORDER-12345")); put("total_amount", Optional.of("custom_attributes")); }} ) .build() ); ``` ### Response Success Response (200) - **customObjectInstance** (Optional) - Description not specified. Response Example - Not specified. ``` -------------------------------- ### Common Workflow: Onboard New Contact Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md A multi-step workflow to onboard a new contact: create the contact, add them to a company, and send a welcome message. ```java // 1. Create contact Contact contact = client.contacts().create( CreateContactRequest.of( CreateContactRequest.WithEmail.builder() .email("newuser@example.com") .name("New User") .customAttributes(Map.of("plan", "starter")) .build() ) ); // 2. Add to company client.companies().attachContact( AttachContactToCompanyRequest.builder() .contactId(contact.getId()) .companyId("company-123") .build() ); // 3. Send welcome message client.messages().create(Optional.of( CreateMessageRequest.builder() .messageType("inapp") .body("Welcome! Check out our docs.") .to(CreateMessageRequest.Recipient.builder() .type("contact") .id(contact.getId()) .build()) .from(CreateMessageRequest.From.builder() .type("admin") .id("onboarding-bot") .build()) .build() )); ``` -------------------------------- ### Get Macro by ID Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves a specific macro (saved reply) by its unique identifier. ```APIDOC ## Get Macro by ID ### Description Retrieves a single macro (saved reply) by its unique identifier. ### Method GET (assumed, based on SDK method name) ### Endpoint `/macros/{id}` (assumed) ### Parameters #### Path Parameters - **id** (String) - Required - The unique identifier for the macro. ### Request Example (No specific request example provided for the HTTP call, only SDK usage) ### Response - **Optional[Macro]** (Object) - Contains the macro object if found, otherwise empty. ### Error Handling (No specific error handling details provided in source) ``` -------------------------------- ### Get Job Status Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves the status of a job execution using its unique identifier. ```APIDOC ## Get Job Status ### Description Retrieves the current status of a job execution. ### Method GET (assumed, based on SDK method name) ### Endpoint `/jobs/{id}/status` (assumed) ### Parameters #### Path Parameters - **id** (String) - Required - The unique identifier for the job provided by Intercom. ### Request Example (No specific request example provided for the HTTP call, only SDK usage) ### Response - **Jobs** (Object) - Contains the job status information. ### Error Handling (No specific error handling details provided in source) ``` -------------------------------- ### Create Synchronous Client with Defaults Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Initializes a synchronous Intercom client using default settings. It relies on the INTERCOM_API_KEY environment variable for authentication and targets the US production environment. ```java import com.intercom.api.Intercom; Intercom client = Intercom.builder().build(); ``` -------------------------------- ### Get Job Status Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieve the status of a job execution using its unique identifier. ```java client.unstable().jobs().status( JobsStatusRequest .builder() .id("id") .build() ); ``` -------------------------------- ### List Help Centers Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieve a list of all Help Centers. Supports pagination with optional page and perPage parameters. ```java client.helpCenters().list( ListHelpCentersRequest .builder() .build() ); ``` -------------------------------- ### Create Help Center Collection Source: https://github.com/intercom/intercom-java/blob/master/reference.md Creates a new help center collection. The 'name' parameter is required for the default language content. ```java client.helpCenters().collections().create( CreateCollectionRequest .builder() .name("Thanks for everything") .build() ); ``` -------------------------------- ### Retrieve/Get Operations Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/resources-overview.md Common patterns for retrieving or getting specific resources by ID or query. ```APIDOC ## Retrieve/Get Operations ```java T retrieve(Id id) T retrieve(Id id, RequestOptions options) T find(Query query) T find(Query query, RequestOptions options) ``` ``` -------------------------------- ### client.aiContent.listContentImportSources() Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves a list of all available content import sources for a workspace. ```APIDOC ## GET /ai/content/import_sources ### Description Retrieves a list of all content import sources for a workspace. ### Method GET ### Endpoint /ai/content/import_sources ### Response #### Success Response (200) - **contentImportSources** (ContentImportSourcesList) - A list of content import sources. ``` -------------------------------- ### client.unstable.internalArticles.listInternalArticles Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a list of all internal articles. This operation corresponds to a GET request to the Intercom API. ```APIDOC ## GET /internal_articles ### Description Fetches a list of all internal articles. ### Method GET ### Endpoint https://api.intercom.io/internal_articles ### Request Example ```java client.internalArticles().listInternalArticles(); ``` ``` -------------------------------- ### client.customObjectInstances().createCustomObjectInstances Source: https://github.com/intercom/intercom-java/blob/master/reference.md Create or update a custom object instance. ```APIDOC ## client.customObjectInstances().createCustomObjectInstances(customObjectTypeIdentifier, request) ### Description Create or update a custom object instance. ### Method POST ### Endpoint /custom_object_instances ### Parameters #### Path Parameters - **customObjectTypeIdentifier** (String) - Required - The unique identifier of the custom object type that defines the structure of the custom object instance. #### Request Body - **externalId** (Optional) - A unique identifier for the Custom Object instance in the external system it originated from. - **externalCreatedAt** (Optional) - The time when the Custom Object instance was created in the external system it originated from. - **externalUpdatedAt** (Optional) - The time when the Custom Object instance was last updated in the external system it originated from. - **customAttributes** (Optional>>) - The custom attributes which are set for the Custom Object instance. ### Request Example { "example": "client.customObjectInstances().createCustomObjectInstances( CreateOrUpdateCustomObjectInstanceRequest .builder() .customObjectTypeIdentifier(\"Order\") .externalId(\"123\") .externalCreatedAt(1392036272) .externalUpdatedAt(1392036272) .customAttributes( new HashMap>() {{ put(\"order_number\", Optional.of(\"ORDER-12345\")); put(\"total_amount\", Optional.of(\"custom_attributes\")); }} ) .build() );" } ### Response #### Success Response (200) - **CustomObjectInstance** (Optional) - The created or updated custom object instance. ``` -------------------------------- ### client.unstable.helpCenter.retrieveCollection Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves the details of a single collection. This operation corresponds to a GET request to the Intercom API. ```APIDOC ## GET /collections/{id} ### Description Retrieves the details of a single collection. ### Method GET ### Endpoint https://api.intercom.io/collections/ ### Parameters #### Path Parameters - **id** (Integer) - Required - The unique identifier for the collection which is given by Intercom. ### Request Example ```java client.unstable().helpCenter().retrieveCollection( RetrieveCollectionRequest .builder() .id(1) .build() ); ``` ``` -------------------------------- ### Asynchronous Client Initialization Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Shows how to create an asynchronous Intercom client using `AsyncIntercom.builder()`. The interface is identical to the synchronous builder, but it returns an `AsyncIntercom` client that uses CompletableFuture for async operations. ```APIDOC ## Asynchronous Client Initialization ### Description Initialize the asynchronous Intercom client using the `AsyncIntercom.builder()` pattern. This client provides the same interface as the synchronous client but operates with async/await patterns through `CompletableFuture`. ### Usage ```java import com.intercom.api.AsyncIntercom; AsyncIntercom client = AsyncIntercom.builder() .token("your-api-token") .build(); ``` ### Builder Methods (`com.intercom.api.AsyncIntercomBuilder`) The `AsyncIntercomBuilder` has an identical interface to `IntercomBuilder`. All methods behave the same, and the `build()` method returns an `AsyncIntercom` instance. ``` -------------------------------- ### Get Custom Object Instance by ID Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a custom object instance by its type identifier and ID. ```APIDOC ## GET /customObjectInstances/{id} ### Description Fetches a single Custom Object Instance by its ID. ### Method GET ### Endpoint `/customObjectInstances/{id}` ### Parameters #### Path Parameters - **id** (String) - Required - The ID or external_id of the custom object instance. #### Query Parameters - **customObjectTypeIdentifier** (String) - Required - The unique identifier of the custom object type. ``` -------------------------------- ### List Help Centers Source: https://github.com/intercom/intercom-java/blob/master/reference.md Lists all available Help Centers. Supports pagination. ```APIDOC ## List Help Centers ### Description Lists all available Help Centers. Supports pagination. ### Method GET ### Endpoint /help_center/help_centers ### Parameters #### Query Parameters - **page** (Optional Integer) - The page of results to fetch. Defaults to the first page. - **perPage** (Optional Integer) - How many results to display per page. Defaults to 15. ### Request Example (No specific request example provided in source, but implies calling list() with optional parameters) ### Response #### Success Response (200) - **SyncPagingIterable<HelpCenter>** (Iterable) - An iterable collection of HelpCenter objects. #### Response Example (No specific response example provided in source) ``` -------------------------------- ### Retrieve a Help Center Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetch the details of a specific Help Center using its unique ID. This is useful for retrieving configuration or metadata. ```java client.unstable().helpCenter().retrieveHelpCenter( RetrieveHelpCenterRequest .builder() .id(1) .build() ); ``` -------------------------------- ### Get Ticket Type by ID Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches the details of a specific ticket type using its unique identifier. ```java client.ticketTypes().get( FindTicketTypeRequest .builder() .ticketTypeId("ticket_type_id") .build() ); ``` -------------------------------- ### Handling Pagination with SyncPagingIterable Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/resources-overview.md Shows how to use `SyncPagingIterable` to automatically handle pagination when listing resources like contacts. ```java SyncPagingIterable contacts = client.contacts().list( ListContactsRequest.builder() .perPage(50) .build() ); contacts.forEach(contact -> { System.out.println("Contact: " + contact.getEmail()); }); ``` -------------------------------- ### client.articles.search() Source: https://github.com/intercom/intercom-java/blob/master/reference.md Searches for articles based on specified criteria. This operation corresponds to a GET request to the /articles/search endpoint. ```APIDOC ## GET /articles/search ### Description Searches for articles based on specified criteria such as a phrase, state, or help center ID. ### Method GET ### Endpoint https://api.intercom.io/articles/search ### Parameters #### Query Parameters - **phrase** (Optional) - Optional - The phrase within your articles to search for. - **state** (Optional) - Optional - The state of the Articles returned. One of `published`, `draft` or `all`. - **helpCenterId** (Optional) - Optional - The ID of the Help Center to search in. - **highlight** (Optional) - Optional - Return a highlighted version of the matching content within your articles. ### Request Example ```json { "example": "(Request body not applicable for GET, parameters are query)" } ``` ### Response #### Success Response (200) - **ArticleSearchResponse** - (Object) - The response containing search results for articles. #### Response Example ```json { "example": "(Response structure not detailed in source)" } ``` ``` -------------------------------- ### Environment Configuration Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Explains how to configure the API environment for the Intercom client, including predefined environments and the option to set a custom URL. ```APIDOC ## Environment Configuration ### Description Configure the API endpoint environment for the Intercom client. You can use predefined environments or specify a custom base URL. ### Predefined Environments (`com.intercom.api.core.Environment`) - `Environment.US_PRODUCTION` // https://api.intercom.io - `Environment.EU_PRODUCTION` // https://api.eu.intercom.io - `Environment.AU_PRODUCTION` // https://api.au.intercom.io ### Custom Environment Specify a custom base URL for the API endpoint. ```java Environment customEnv = Environment.custom("https://custom.api.endpoint.com"); ``` ### Example Usage Set the environment during client initialization: ```java import com.intercom.api.Intercom; import com.intercom.api.core.Environment; Intercom client = Intercom.builder() .token("api-key") .environment(Environment.EU_PRODUCTION) .build(); ``` ``` -------------------------------- ### Get External Page Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves a specific external page using its unique Intercom-assigned page ID. ```APIDOC ## Get External Page ### Description Retrieves a specific external page using its unique Intercom-assigned page ID. ### Method GET ### Endpoint `/external-pages/{pageId}` ### Parameters #### Path Parameters - **pageId** (String) - Required - The unique identifier for the external page which is given by Intercom. ### Response #### Success Response (200) - **ExternalPage** - The retrieved external page object. ``` -------------------------------- ### client.aiContent.createContentImportSource(request) Source: https://github.com/intercom/intercom-java/blob/master/reference.md Creates a new content import source for a workspace. ```APIDOC ## POST /ai/content/import_sources ### Description Creates a new content import source by sending a POST request to this endpoint. ### Method POST ### Endpoint /ai/content/import_sources ### Request Body - **url** (String) - Required - The URL for the content import source. ### Request Example { "url": "https://www.example.com" } ### Response #### Success Response (200) - **contentImportSource** (ContentImportSource) - The newly created content import source. ``` -------------------------------- ### client.unstable.conversations.listConversations() Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a list of all conversations. Supports pagination with optional per page count and starting after cursor. ```APIDOC ## client.unstable.conversations.listConversations() ### Description Fetches a list of all conversations. Supports pagination with optional per page count and starting after cursor. ### Method GET (Assumed based on list operation) ### Endpoint /conversations ### Parameters #### Query Parameters - **perPage**: `Optional` - Optional - The number of results to return per page. Defaults to 20. - **startingAfter**: `Optional` - Optional - A cursor to specify the starting point for fetching the next page of conversations. ``` -------------------------------- ### Use API Key from Environment Variable Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/README.md Instantiate the Intercom client without explicitly providing a token, allowing it to be automatically loaded from the `INTERCOM_API_KEY` environment variable. ```java // Token automatically loaded from INTERCOM_API_KEY Intercom client = Intercom.builder().build(); ``` -------------------------------- ### Create a New Content Import Source Source: https://github.com/intercom/intercom-java/blob/master/reference.md Create a new content import source by providing a URL. This allows for integrating external content into your Intercom workspace. ```java client.aiContent().createContentImportSource( CreateContentImportSourceRequest .builder() .url("https://www.example.com") .build() ); ``` -------------------------------- ### Get Ticket by ID Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetch the details of a single ticket using its unique identifier. Requires the ticket ID. ```java client.unstable().tickets().getTicket( GetTicketRequest .builder() .id("id") .build() ); ``` -------------------------------- ### Accessing Resource Modules Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/resources-overview.md Demonstrates how to access different resource modules (e.g., contacts, conversations, tickets) through the main Intercom client instance. This pattern is consistent across all available resource modules. ```APIDOC ## Access Pattern All resources are accessed through the main client: ```java import com.intercom.api.Intercom; Intercom client = Intercom.builder().token("api-key").build(); client.admins() // Admin management client.contacts() // User and lead management client.companies() // Company management client.conversations() // Conversation management client.messages() // Message creation client.tickets() // Ticket management // ... and 29 more resource modules ``` ``` -------------------------------- ### Get Job Status Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieve the status of a job execution using its unique identifier. The jobId is provided by Intercom. ```java client.jobs().status( JobsStatusRequest .builder() .jobId("job_id") .build() ); ``` -------------------------------- ### client.internalArticles.searchInternalArticles Source: https://github.com/intercom/intercom-java/blob/master/reference.md Searches for internal articles. This operation corresponds to a GET request to the Intercom API's search endpoint. ```APIDOC ## GET https://api.intercom.io/internal_articles/search ### Description Searches for internal articles. ### Parameters #### Query Parameters - **folderId** (Optional) - The ID of the folder to search in. ### Response #### Success Response (200) - **InternalArticleSearchResponse** - The search results for internal articles. ``` -------------------------------- ### Create Contact Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Create a new contact with basic information like email, name, phone, and custom attributes. ```java Contact contact = client.contacts().create( CreateContactRequest.of( CreateContactRequest.WithEmail.builder() .email("newuser@example.com") .name("John Doe") .phone("+1234567890") .customAttributes(Map.of("plan", "premium")) .build() ) ); ``` -------------------------------- ### Configure RequestOptions with Timeout and Custom Headers Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/configuration.md Demonstrates how to build RequestOptions to override client-level settings for a specific request. This includes setting a custom timeout and adding request-specific headers. ```java import com.intercom.api.core.RequestOptions; import java.util.concurrent.TimeUnit; client.contacts().list( request, RequestOptions.builder() .timeout(30) .addHeader("X-Request-ID", "abc-123") .addHeader("X-Timestamp", System::currentTimeMillis) .build() ); ``` -------------------------------- ### client.unstable.helpCenter.listAllCollections Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a list of all collections in the help center, ordered by the most recently updated. ```APIDOC ## client.unstable.helpCenter.listAllCollections ### Description You can fetch a list of all collections by making a GET request to `https://api.intercom.io/help_center/collections`. Collections will be returned in descending order on the `updated_at` attribute. This means if you need to iterate through results then we'll show the most recently updated collections first. ### Usage ```java client.helpCenters().collections().list( ListCollectionsRequest .builder() .build() ); ``` ``` -------------------------------- ### Search Conversations Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Search for conversations based on specific criteria. This allows for targeted retrieval of conversations, for example, by source type. ```java SyncPagingIterable results = client.conversations() .search(SearchRequest.builder() .query(SearchRequest.SearchQuery.builder() .field("source.type") .operator("=") .value("email") .build()) .build()); ``` -------------------------------- ### Retrieve a Newsfeed Source: https://github.com/intercom/intercom-java/blob/master/reference.md Get the details of a specific newsfeed using its unique identifier. This is useful for inspecting the configuration and status of a newsfeed. ```java client.unstable().news().retrieveNewsfeed( RetrieveNewsfeedRequest .builder() .id("123") .build() ); ``` -------------------------------- ### Build Intercom Client Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/README.md Use the builder pattern to configure and create an Intercom client instance. Supports authentication, environment selection, timeouts, retries, and custom headers. ```java Intercom client = Intercom.builder() .token("api-key") // Authentication .environment(Environment.EU_PRODUCTION) // Region .timeout(30) // Request timeout .maxRetries(3) // Retry attempts .addHeader("X-Custom", "value") // Custom headers .build(); ``` -------------------------------- ### getExternalPage Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves a specific external page by its unique identifier. Use this to get details of a previously created external page. ```APIDOC ## GET /intercom/intercom-java/aiContent/getExternalPage ### Description Retrieves an external page. ### Method GET ### Endpoint /intercom/intercom-java/aiContent/getExternalPage ### Parameters #### Query Parameters - **id** (String) - Required - The unique identifier for the external page which is given by Intercom. ### Request Example (No request body specified) ### Response #### Success Response (200) - **ExternalPage** - Type not specified - Description not specified #### Response Example (No example provided in source) ``` -------------------------------- ### Access Resource Clients Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Shows how to access various resource-specific clients (e.g., contacts, companies, conversations) from an initialized Intercom client instance. ```java Intercom client = Intercom.builder().token("api-key").build(); // Access resource clients client.contacts() client.companies() client.conversations() client.messages() client.admins() client.tags() client.segments() client.tickets() client.articles() // ... and 27 other resource modules ``` -------------------------------- ### Get Current Admin User Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Retrieve details about the currently authenticated admin user. This is useful for personalization or logging purposes. ```java Optional me = client.admins().identify(); me.ifPresent(admin -> { System.out.println("Name: " + admin.getName()); System.out.println("Email: " + admin.getEmail()); System.out.println("App: " + admin.getApp().getName()); }); ``` -------------------------------- ### List Macros with Pagination and Filtering Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetch a list of all macros (saved replies) in your workspace. Supports pagination using 'startingAfter' and filtering by 'updatedSince'. ```java client.unstable().macros().listMacros( ListMacrosRequest .builder() .perPage(1) .startingAfter("WzE3MTk0OTM3NTcuMCwgIjEyMyJd") .updatedSince(1000000L) .build() ); ``` -------------------------------- ### CompanyList Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/types.md Represents a paginated list of companies. It includes methods to get the company data, the response type, and pagination metadata. ```APIDOC ## CompanyList ### Description Represents a paginated list of companies. It includes methods to get the company data, the response type, and pagination metadata. ### Fields - **data** (List) - List of company items - **type** (String) - Always "list" - **pages** (Pagination) - Pagination metadata ``` -------------------------------- ### List All Tags Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a list of all tags for the current workspace. No parameters are required. ```java client.tags().list(); ``` -------------------------------- ### Create Asynchronous Client Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Initializes an asynchronous Intercom client using the builder pattern. This client supports async/await patterns via CompletableFuture. ```java import com.intercom.api.AsyncIntercom; AsyncIntercom client = AsyncIntercom.builder() .token("your-api-token") .build(); ``` -------------------------------- ### Clear Maven Credentials in generators.yml Source: https://github.com/intercom/intercom-java/blob/master/README.md Example configuration to clear Maven credentials in `generators.yml` to skip the publish step during SDK regeneration. ```yaml # Example: Clear Maven credentials to skip publish username: "" password: "" signing-key-id: "" ``` -------------------------------- ### Create Article Source: https://github.com/intercom/intercom-java/blob/master/reference.md Creates a new article. POST requests are made to the articles endpoint. ```java client.unstable().articles().createArticle(new HashMap() {{put("key", "value"); }}); ``` -------------------------------- ### Show Call Recording Source: https://github.com/intercom/intercom-java/blob/master/reference.md Get a redirect to a signed URL for a call's recording, if one exists. Requires the call ID. ```java client.calls().showCallRecording( ShowCallRecordingRequest .builder() .callId("call_id") .build() ); ``` -------------------------------- ### Get Content Import Source Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieves a specific content import source by its ID. Use this to fetch details of an existing source. ```java client.aiContent().getContentImportSource( GetContentImportSourceRequest .builder() .sourceId("source_id") .build() ); ``` -------------------------------- ### Get Error Details Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Explains how to extract detailed information from an `IntercomApiException`, including the HTTP status code, response body, and headers. ```APIDOC ## Get Error Details ### Description Retrieves detailed information from an API exception. ### Exception Handling - **IntercomApiException**: Provides methods to access status code, body, and headers. ### Example ```java try { client.contacts().find(request); } catch (IntercomApiException e) { int status = e.statusCode(); Object body = e.body(); Map> headers = e.headers(); System.out.println("Status: " + status); System.out.println("Retry-After: " + headers.get("Retry-After")); } ``` ``` -------------------------------- ### Create Synchronous Client with API Token Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/client-initialization.md Initializes a synchronous Intercom client by explicitly providing an API token. This is useful when the API key is not set as an environment variable. ```java import com.intercom.api.Intercom; Intercom client = Intercom.builder() .token("your-api-token") .build(); ``` -------------------------------- ### Configure Intercom Client with Custom HTTP Client Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/README.md Integrate a custom OkHttpClient instance with the Intercom client builder. This allows for advanced network configurations like custom interceptors and connection settings. ```java import okhttp3.OkHttpClient; OkHttpClient customClient = new OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(30, TimeUnit.SECONDS) .addInterceptor(new CustomLoggingInterceptor()) .build(); Intercom client = Intercom.builder() .token("api-key") .httpClient(customClient) .build(); ``` -------------------------------- ### Get Admin Activity Logs Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Retrieve a list of all administrative activity logs. This is valuable for auditing and tracking actions performed by administrators. ```java ActivityLogList logs = client.admins() .listAllActivityLogs(ListAllActivityLogsRequest.builder().build()); logs.getData().forEach(log -> { System.out.println(log.getAdminName() + ": " + log.getAction()); }); ``` -------------------------------- ### Get Conversation Details Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Fetch detailed information about a specific conversation, including its messages. Use this to retrieve the full context of a conversation. ```java Conversation conversation = client.conversations() .find(FindConversationRequest.builder() .id("conversation-123") .build()); // Access conversation parts (messages) conversation.getConversationParts() .ifPresent(parts -> { parts.getData().forEach(part -> { System.out.println(part.getBody()); }); }); ``` -------------------------------- ### client.news().items().create Source: https://github.com/intercom/intercom-java/blob/master/reference.md Creates a new news item. This method allows for detailed configuration of the news item, including title, sender, body, state, delivery options, labels, reactions, and newsfeed assignments. ```APIDOC ## client.news().items().create ### Description Creates a new news item with specified details. ### Method Not applicable (SDK method) ### Parameters #### Request Body - **request** (NewsItemRequest) - Required - An object containing the details for the news item to be created. - **title** (string) - Required - The title of the news item. - **senderId** (Integer) - Required - The ID of the sender. - **body** (string) - Required - The main content of the news item, potentially in HTML format. - **state** (NewsItemRequestState) - Required - The state of the news item (e.g., LIVE). - **deliverSilently** (boolean) - Required - Whether to deliver the news item silently. - **labels** (Optional>) - Optional - A list of labels to associate with the news item. - **reactions** (Optional>) - Optional - A list of reactions for the news item. - **newsfeedAssignments** (Optional>) - Optional - Assignments for the newsfeed. - **newsfeedId** (Integer) - Required - The ID of the newsfeed. - **publishedAt** (Integer) - Required - The timestamp when the news item should be published. ### Request Example ```java client.news().items().create( NewsItemRequest .builder() .title("Halloween is here!") .senderId(991267834) .body("

New costumes in store for this spooky season

") .state(NewsItemRequestState.LIVE) .deliverSilently(true) .labels( Optional.of( Arrays.asList("Product", "Update", "New") ) ) .reactions( Optional.of( Arrays.asList(Optional.of("😆"), Optional.of("😅")) ) ) .newsfeedAssignments( Optional.of( Arrays.asList( NewsfeedAssignment .builder() .newsfeedId(53) .publishedAt(1664638214) .build() ) ) ) .build() ); ``` ### Response #### Success Response Returns the created `NewsItem` object. #### Response Example (Response structure not provided in source) ``` -------------------------------- ### Articles Resource Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/api-reference/resources-overview.md Create and manage help center articles. ```APIDOC ## Articles Resource ### Description Create and manage help center articles. ### Client Method `.articles()` ``` -------------------------------- ### Retrieve Article Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches the details of a single article using its unique identifier. GET requests are made to the articles endpoint with the article ID. ```java client.unstable().articles().retrieveArticle( RetrieveArticleRequest .builder() .id(1) .build() ); ``` -------------------------------- ### List All Articles Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a list of all articles. Articles are sorted in descending order by `updated_at`. ```java client.articles().list( ListArticlesRequest .builder() .build() ); ``` -------------------------------- ### Get External Page Source: https://github.com/intercom/intercom-java/blob/master/reference.md Retrieve an existing external page using its unique identifier. This is useful for fetching page details before updating or for verification. ```java client.aiContent().getExternalPage( GetExternalPageRequest .builder() .pageId("page_id") .build() ); ``` -------------------------------- ### Get Activity Logs Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/QUICKSTART.md Retrieves a list of activity logs for admins using the Intercom Java SDK. This provides a record of actions performed by admins. ```APIDOC ## Get Activity Logs ### Description Retrieves a list of activity logs for admins. ### Method GET (implied by `listAllActivityLogs` method) ### Endpoint `/admin_activity_logs` (implied) ### Parameters #### Query Parameters - **perPage** (integer) - Optional - The number of logs to return per page. ### Response #### Success Response - **data** (array) - An array of activity log objects. - **adminName** (string) - The name of the admin who performed the action. - **action** (string) - The action performed. ### Response Example ```json { "data": [ { "adminName": "John Doe", "action": "conversation_replied" } ] } ``` ``` -------------------------------- ### Create and Push Release Tag Source: https://github.com/intercom/intercom-java/blob/master/README.md Manually create and push a Git tag for a new release. This action typically triggers the publish workflow. ```bash git tag v4.0.x git push origin v4.0.x ``` -------------------------------- ### List Available Datasets and Attributes Source: https://github.com/intercom/intercom-java/blob/master/reference.md Use this method to retrieve a list of all available datasets and their attributes for export. ```java client.export().listAvailableDatasetsAndAttributes(); ``` -------------------------------- ### Custom Attributes Source: https://github.com/intercom/intercom-java/blob/master/_autodocs/types.md Details how custom attributes are managed using `Map`. It shows examples of retrieving and setting custom attributes on contact objects. ```APIDOC ## Custom Attributes Custom attributes are stored as `Map`: ```java Contact contact = ...; // Getting custom attributes Optional> attrs = contact.getCustomAttributes(); attrs.ifPresent(map -> { String plan = (String) map.get("subscription_plan"); Integer credits = (Integer) map.get("remaining_credits"); }); // Setting custom attributes CreateContactRequest request = CreateContactRequest.of( CreateContactRequest.WithEmail.builder() .email("user@example.com") .customAttributes( Map.of( "plan", "premium", "credits", 1000, "region", "US-West" ) ) .build() ); ``` ``` -------------------------------- ### List Help Center Collections Source: https://github.com/intercom/intercom-java/blob/master/reference.md Fetches a list of all help center collections. Collections are returned in descending order of their update time. ```java client.helpCenters().collections().list( ListCollectionsRequest .builder() .build() ); ```