### Navigating the SDK Reference

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/README.md

Guidance on how to use the SDK reference documentation, directing users to specific sections for initial setup, quick start examples, detailed API module documentation, error handling, pagination, and common types.

```markdown
1. **First time?** Start with [INDEX.md](INDEX.md) for overview
2. **Setup needed?** Go to [00-CLIENT-INITIALIZATION.md](00-CLIENT-INITIALIZATION.md)
3. **Quick example?** Check [16-QUICK-START.md](16-QUICK-START.md)
4. **Specific method?** Find the matching API module doc
5. **Error handling?** Read [12-ERRORS-EXCEPTIONS.md](12-ERRORS-EXCEPTIONS.md)
6. **Large datasets?** See [13-PAGINATION.md](13-PAGINATION.md)
7. **Data types?** Check [15-COMMON-TYPES.md](15-COMMON-TYPES.md)
```

--------------------------------

### Install Intercom Python Library

Source: https://github.com/intercom/python-intercom/blob/master/README.md

Install the library using pip. This is the first step to using the Intercom Python SDK.

```sh
pip install python-intercom
```

--------------------------------

### Python CallsClient list() Example

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/09-NOTES-VISITORS-CALLS-API.md

Example of how to fetch and iterate through call records using the list method of the CallsClient, specifying the number of records per page.

```python
calls = client.calls.list(per_page=50)
for call in calls:
    print(call.id)
```

--------------------------------

### JSON String Example

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Example of a JSON string value for event metadata.

```json
"source":"desktop"
```

--------------------------------

### JSON Rich Link Example

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Example of a JSON rich link value, containing 'url' and 'value' keys.

```json
"article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"}
```

--------------------------------

### Python CallsClient retrieve_with_transcripts() Example

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/09-NOTES-VISITORS-CALLS-API.md

Example of how to fetch call records with their transcripts using the retrieve_with_transcripts method, iterating through the response data to print call IDs and transcripts.

```python
response = client.calls.retrieve_with_transcripts(per_page=20)
for call_data in response.data:
    print(call_data.call.id)
    print(call_data.call.transcript)
```

--------------------------------

### JSON Date Example

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Example of a JSON date value, represented as a Unix timestamp in UTC. The key must end with '_date'.

```json
"contact_date": 1392036272
```

--------------------------------

### Async Usage Example

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/16-QUICK-START.md

Utilize asynchronous operations for non-blocking API calls. This example shows how to fetch a contact and list conversations asynchronously.

```python
import asyncio
from intercom import AsyncIntercom

async def main():
    client = AsyncIntercom(token="YOUR_TOKEN")
    
    # Fetch contact
    contact = await client.contacts.find(email="user@example.com")
    print(f"Name: {contact.name}")
    
    # List conversations
    conversations = client.conversations.list()
    async for conv in conversations:
        print(f"Conversation: {conv.id}")

asyncio.run(main())
```

--------------------------------

### Send an Email Message

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/16-QUICK-START.md

This example demonstrates how to send an email message to a user. The 'client' object must be properly configured.

```python
message = client.messages.create(
    request={
        "message_type": "email",
        "subject": "Important Update",
        "body": "<p>Check out our new features</p>",
        "from": {"type": "admin", "id": 123},
        "to": {"email": "user@example.com"}
    }
)
```

--------------------------------

### GET /help_center/help_center/{id}

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches the details of a single Help Center.

```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/<id>

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique identifier for the Help Center.

#### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **help_center** (object) - Details of the Help Center.

#### Response Example
```json
{
  "id": 123,
  "name": "My Help Center",
  "created_at": 1678886400,
  "updated_at": 1678886400
}
```
```

--------------------------------

### Admin Priority Pattern

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/07-ADMINS-TEAMS-API.md

Examples for managing admin away status and retrieving their current status.

```APIDOC
## Admin Priority Pattern

### Set admin as away with reassignment
```python
client.admins.away(
    admin_id=123,
    away_mode_enabled=True,
    away_mode_reassign=True
)
```

### Set admin back as available
```python
client.admins.away(
    admin_id=123,
    away_mode_enabled=False,
    away_mode_reassign=False
)
```

### Get current away status
```python
admin = client.admins.retrieve(admin_id=123)
if admin.away_mode_enabled:
    print("Admin is away")
else:
    print("Admin is available")
```
```

--------------------------------

### GET /help_center/collections

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches a list of all help center collections. Collections are returned in descending order of `updated_at`.

```APIDOC
## GET /help_center/collections

### Description
Fetches a list of all help center collections. Collections are returned in descending order of `updated_at`.

### Method
GET

### Endpoint
/help_center/collections

### Parameters
#### Query Parameters
- **page** (typing.Optional[int]) - Optional - The page of results to fetch. Defaults to the first page.
- **per_page** (typing.Optional[int]) - Optional - How many results to display per page. Defaults to 15.
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **collections** (list) - A list of help center collections.

#### Response Example
```json
[
  {
    "id": "1",
    "name": "Getting Started",
    "description": "Basic guides to get you started.",
    "updated_at": 1678886400
  }
]
```
```

--------------------------------

### Customer Identifier Examples

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/15-COMMON-TYPES.md

Illustrates different ways to identify a customer using union types. Choose the appropriate key based on the identifier available.

```python
# By Intercom ID
{"intercom_user_id": "contact_123"}
```

```python
# By external ID
{"user_id": "external_id_123"}
```

```python
# By email
{"email": "user@example.com"}
```

--------------------------------

### JSON Number Example

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Example of a JSON number value for event metadata.

```json
"load": 3.67
```

--------------------------------

### Full Intercom Client Initialization Example

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/14-CONFIGURATION.md

Configure the Intercom client with authentication token, environment, custom base URL, request settings like timeout and redirects, additional headers, and an optional custom httpx client.

```python
from intercom import Intercom, IntercomEnvironment
import httpx

client = Intercom(
    # Authentication
    token="YOUR_API_TOKEN",
    
    # Environment/Region
    environment=IntercomEnvironment.EU_PRODUCTION,
    
    # Custom base URL (overrides environment)
    # base_url="https://custom.api.endpoint.com",
    
    # Request settings
    timeout=30.0,
    follow_redirects=True,
    
    # Additional headers
    headers={
        "User-Agent": "MyApp/1.0",
        "X-Custom-Header": "value"
    },
    
    # Advanced: custom httpx client
    # httpx_client=httpx.Client(
    #     proxy="http://proxy.example.com:8080",
    #     verify=False,  # SSL verification
    # )
)
```

--------------------------------

### Initializing Client with Static Token

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/00-CLIENT-INITIALIZATION.md

Shows how to initialize the Intercom client using a static API token string.

```python
client = Intercom(token="abc123...")
```

--------------------------------

### List All Subscription Types

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/11-SUBSCRIPTION-TYPES-NEWS-API.md

Fetches all available subscription types. Use this to get a comprehensive list of preferences users can subscribe to. The results are paginated.

```python
from intercom import Intercom

client = Intercom(token="YOUR_TOKEN")
subscriptions = client.subscription_types.list()
for sub_type in subscriptions:
    print(sub_type.name, sub_type.consent_type)
```

--------------------------------

### JSON Monetary Amount Example

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Example of a JSON monetary amount, with 'amount' in cents and 'currency'.

```json
"price": {"amount": 34999, "currency": "eur"}
```

--------------------------------

### Initializing Client with Environment Variable

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/00-CLIENT-INITIALIZATION.md

Demonstrates initializing the Intercom client without a token parameter, relying on the INTERCOM_API_KEY environment variable to be set.

```python
client = Intercom()  # Reads INTERCOM_API_KEY from environment
```

--------------------------------

### JSON Link Example

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Example of a JSON link value, which must be an HTTP or HTTPS URI.

```json
"article": "https://example.org/ab1de.html"
```

--------------------------------

### Configure Intercom Client for Production Environments

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/14-CONFIGURATION.md

Shows how to initialize the Intercom client using environment variables for the API key and selecting the correct production environment (US or EU). Includes setting a custom timeout.

```python
import os
from intercom import Intercom, IntercomEnvironment

# Read from environment
token = os.getenv("INTERCOM_API_KEY")
if not token:
    raise ValueError("INTERCOM_API_KEY environment variable not set")

# Select environment
env = IntercomEnvironment.EU_PRODUCTION if os.getenv("REGION") == "eu" else IntercomEnvironment.US_PRODUCTION

client = Intercom(
    token=token,
    environment=env,
    timeout=30.0
)
```

--------------------------------

### ListResponse Usage Example

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/15-COMMON-TYPES.md

Demonstrates how to interpret a ListResponse object after fetching data, such as a list of tags. Access the 'data' attribute for the items and 'pages' for navigation.

```python
response = client.tags.list()
# response.type == "list"
# response.data == [Tag, Tag, ...]
# response.pages == pagination info
```

--------------------------------

### Initialize Intercom Client with Different Environments

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/14-CONFIGURATION.md

Instantiate the Intercom client for different production regions by specifying the `environment` parameter. Defaults to US Production if not provided.

```python
from intercom import Intercom, IntercomEnvironment

# US Production (default)
client = Intercom(
    token="YOUR_TOKEN",
    environment=IntercomEnvironment.US_PRODUCTION
)

# EU Production
client = Intercom(
    token="YOUR_TOKEN",
    environment=IntercomEnvironment.EU_PRODUCTION
)

# AU Production
client = Intercom(
    token="YOUR_TOKEN",
    environment=IntercomEnvironment.AU_PRODUCTION
)
```

--------------------------------

### List Help Centers with Python SDK

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Use this method to retrieve a list of all available Help Centers. It requires authentication with your Intercom token.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
client.unstable.help_center.list_help_centers()
```

--------------------------------

### Initialize Intercom Client with API Key

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/INDEX.md

Instantiate the Intercom client by passing your API key directly to the constructor. Use this method if you prefer not to set an environment variable.

```python
client = Intercom(token="your_token_here")
```

--------------------------------

### Initialize Intercom Client for EU Environment

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/INDEX.md

Demonstrates how to initialize the Intercom client, specifying the token and the EU production environment. This is necessary for directing API requests to the correct regional endpoint.

```python
from intercom import Intercom, IntercomEnvironment

client = Intercom(
    token="YOUR_TOKEN",
    environment=IntercomEnvironment.EU_PRODUCTION
)
```

--------------------------------

### GET /segments

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Retrieves a list of segments.

```APIDOC
## GET /segments

### Description
Retrieves a list of segments.

### Method
GET

### Endpoint
/segments

### Response
#### Success Response (200 OK)
Returns a list of segments.
```

--------------------------------

### Instantiate and Use Intercom Client

Source: https://github.com/intercom/python-intercom/blob/master/README.md

Create an instance of the Intercom client with your API token and make a call to create an AI content import source.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
client.ai_content.create_content_import_source(
    url="https://www.example.com",
)
```

--------------------------------

### Create Help Center Collection in Python

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Create a new help center collection. You can specify the name, description, and parent collection. For multilingual collections, provide default language content.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
client.help_centers.collections.create(
    name="collection 51",
    description="Missing required parameter",
)
```

--------------------------------

### AdminsClient.retrieve()

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/07-ADMINS-TEAMS-API.md

Get a single admin by ID.

```APIDOC
## AdminsClient.retrieve()

### Description
Get a single admin by ID.

### Method
```python
def retrieve(
    self,
    admin_id: int,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> typing.Optional[Admin]
```

### Parameters
#### Path Parameters
- **admin_id** (int) - Required - Admin ID.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Returns
`Admin`

### Request Example
```python
admin = client.admins.retrieve(admin_id=123)
print(admin.name)
```
```

--------------------------------

### GET /conversations/list_handling_events

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Lists all pause/resume events for a conversation.

```APIDOC
## GET /conversations/list_handling_events

### Description
List all pause/resume events for a conversation. These events track when teammates paused or resumed handling a conversation.
Requires the `read_conversations` OAuth scope.

### Method
GET

### Endpoint
/conversations/{id}/handling_events

### Parameters
#### Path Parameters
- **id** (str) - Required - The identifier for the conversation as given by Intercom.

#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
from intercom import Intercom

client = Intercom(token="YOUR_TOKEN")
client.unstable.conversations.list_handling_events(id="123")
```

### Response
#### Success Response (200)
- **events** (list) - A list of handling events for the conversation.

#### Response Example
```json
{
  "events": [
    {
      "type": "conversation_handling_event",
      "id": "123",
      "created_at": 1678886400,
      "admin": {
        "type": "admin",
        "id": "5017690",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "event_type": "conversation_paused"
    }
  ]
}
```
```

--------------------------------

### GET /calls

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Retrieves a paginated list of calls.

```APIDOC
## GET /calls

### Description
Retrieve a paginated list of calls.

### Method
GET

### Endpoint
/calls

### Query Parameters
- **page** (integer) - Optional - The page of results to fetch. Defaults to the first page.
- **per_page** (integer) - Optional - How many results to display per page. Defaults to 25. Maximum is 25.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
client.calls.list_calls(page=1, per_page=1)
```

### Response
#### Success Response (200)
- **calls** (array) - A list of call objects.
- **total_count** (integer) - The total number of calls.

#### Response Example
```json
{
  "calls": [
    {
      "id": "call_123",
      "type": "inbound",
      "created_at": 1678886400
    }
  ],
  "total_count": 10
}
```
```

--------------------------------

### Create Article

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/05-ARTICLES-HELP-CENTER-API.md

Create a new help center article with specified details including title, body, author, and parent collection.

```APIDOC
## Create Article

### Description
Create a new article.

### Method
POST

### Endpoint
/articles

### Parameters
#### Request Body
- **request** (CreateArticleRequest) - Required - Article data.
  - **title** (str) - Required - Article title.
  - **body** (str) - Required - Article content (HTML allowed).
  - **author_id** (int) - Required - Author admin ID.
  - **parent_id** (str) - Required - Parent collection ID.
  - **parent_type** (str) - Required - 'collection' or 'help_center'.
  - **state** (str) - Optional - 'draft' or 'published' (default: 'published').
  - **translated_content** (Dict[str, Dict]) - Optional - Content in other languages.

### Response
#### Success Response (200)
- **id** (str) - The unique identifier for the created article.
- **title** (str) - The title of the article.
- **body** (str) - The content of the article.
- **author_id** (int) - The ID of the author.
- **parent_id** (str) - The ID of the parent collection or help center.
- **parent_type** (str) - The type of the parent ('collection' or 'help_center').
- **state** (str) - The current state of the article ('draft' or 'published').

### Request Example
```python
article = client.articles.create(
    request={
        "title": "How to use our service",
        "body": "<p>Steps to get started...</p>",
        "author_id": 123,
        "parent_id": "collection_456",
        "parent_type": "collection",
        "state": "published"
    }
)
print(article.id)
```
```

--------------------------------

### Get a Ticket

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/16-QUICK-START.md

Retrieves a specific ticket by its ID.

```APIDOC
## Get a Ticket

### Description
Retrieves a specific ticket using its unique identifier.

### Method
`client.tickets.retrieve()`

### Parameters
- `ticket_id` (string) - Required - The ID of the ticket to retrieve.

### Request Example
```python
ticket = client.tickets.retrieve(ticket_id="ticket_123")
```

### Response
#### Success Response
Returns a `Ticket` object.

#### Response Example
```python
print(f"Subject: {ticket.subject}")
print(f"State: {ticket.ticket_state.name}")
```
```

--------------------------------

### List All Help Centers

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/05-ARTICLES-HELP-CENTER-API.md

Fetches a list of all available help centers. Iterates through the 'data' attribute of the response to access individual help center objects.

```python
help_centers = client.help_centers.list()
for hc in help_centers.data:
    print(hc.name)
```

--------------------------------

### Initializing Client with Dynamic Token

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/00-CLIENT-INITIALIZATION.md

Illustrates initializing the Intercom client with a callable function that returns a dynamic API token. This function is called on each request.

```python
def get_token():
    return os.getenv("INTERCOM_API_KEY")

client = Intercom(token=get_token)
```

--------------------------------

### Get a Conversation

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/16-QUICK-START.md

Retrieves a specific conversation by its ID.

```APIDOC
## Get a Conversation

### Description
Retrieves a specific conversation using its unique identifier.

### Method
`client.conversations.retrieve()`

### Parameters
- `conversation_id` (string) - Required - The ID of the conversation to retrieve.

### Request Example
```python
conversation = client.conversations.retrieve(
    conversation_id="conv_123"
)
```

### Response
#### Success Response
Returns a `Conversation` object.

#### Response Example
```python
print(f"State: {conversation.state}")
print(f"Subject: {conversation.subject}")
```
```

--------------------------------

### Track a Customer Action with Python

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/16-QUICK-START.md

Record a single customer action or event. This requires the event name, a timestamp, the customer's email, and optional metadata.

```python
client.events.create(
    request={
        "event_name": "purchase",
        "created_at": int(time.time()),
        "email": "user@example.com",
        "metadata": {
            "item_id": "product_123",
            "amount": 9900
        }
    }
)
```

--------------------------------

### GET /internal_articles

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches a list of all internal articles.

```APIDOC
## GET /internal_articles

### Description
Fetches a list of all internal articles.

### Method
GET

### Endpoint
https://api.intercom.io/internal_articles

### Parameters
#### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **articles** (array) - A list of internal article objects.

#### Response Example
```json
[
  {
    "id": 1,
    "title": "Troubleshooting Guide",
    "author_id": 1295,
    "owner_id": 1295,
    "created_at": 1678886400,
    "updated_at": 1678886400
  }
]
```
```

--------------------------------

### List Help Center Collections in Python

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetch a list of all help center collections. Results are ordered by `updated_at` in descending order. Supports pagination.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
response = client.help_centers.collections.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page
```

--------------------------------

### AdminsClient.identify()

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/07-ADMINS-TEAMS-API.md

Get information about the currently authenticated admin.

```APIDOC
## AdminsClient.identify()

### Description
Get information about the currently authenticated admin.

### Method
```python
def identify(
    self,
    *,
    request_options: typing.Optional[RequestOptions] = None,
) -> typing.Optional[AdminWithApp]
```

### Returns
`AdminWithApp` containing admin details and app/workspace information.

### Request Example
```python
from intercom import Intercom

client = Intercom(token="YOUR_TOKEN")
admin = client.admins.identify()
print(admin.name)
print(admin.email)
print(admin.app.name)  # Workspace name
```
```

--------------------------------

### GET /intercom/python-intercom/unstable/articles/search_articles

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Searches for articles based on provided criteria.

```APIDOC
## GET /intercom/python-intercom/unstable/articles/search_articles

### Description
Searches for articles based on provided criteria.

### Method
GET

### Endpoint
/intercom/python-intercom/unstable/articles/search

### Parameters
#### Query Parameters
- **phrase** (str) - Required - The search phrase to look for in articles.
- **state** (str) - Optional - The state of the articles to search for (e.g., "published").
- **help_center_id** (int) - Optional - The ID of the help center to search within.
- **highlight** (bool) - Optional - Whether to highlight search terms in the results.
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
client.unstable.articles.search_articles(
    phrase="Getting started",
    state="published",
    help_center_id=1,
    highlight=True,
)
```

### Response
#### Success Response (200)
- **articles** (list) - A list of article objects matching the search criteria.

#### Response Example
```json
{
  "articles": [
    {
      "id": "789",
      "title": "Getting Started Guide",
      "state": "published"
    }
  ]
}
```
```

--------------------------------

### Synchronous Client Initialization

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/00-CLIENT-INITIALIZATION.md

Initialize the synchronous `Intercom` client with your API token and optional parameters.

```APIDOC
## Intercom (Synchronous Client)

**Module:** `intercom.client`

### Description
Initializes the synchronous Intercom client.

### Constructor
`Intercom(
    token: str | Callable[[], str] = "YOUR_TOKEN",
    base_url: str = None,
    environment: IntercomEnvironment = IntercomEnvironment.US_PRODUCTION,
    headers: Dict[str, str] = None,
    timeout: float = 60.0,
    follow_redirects: bool = True,
    httpx_client: httpx.Client = None
)`

### Parameters

#### `token`
- **Type**: `str | Callable[[], str]`
- **Required**: No
- **Default**: `INTERCOM_API_KEY` env var
- **Description**: API token for authentication. If callable, will be invoked on each request.

#### `base_url`
- **Type**: `str`
- **Required**: No
- **Description**: Custom base URL for API requests.

#### `environment`
- **Type**: `IntercomEnvironment`
- **Required**: No
- **Default**: `IntercomEnvironment.US_PRODUCTION`
- **Description**: API environment. Options: `US_PRODUCTION`, `EU_PRODUCTION`, `AU_PRODUCTION`.

#### `headers`
- **Type**: `Dict[str, str]`
- **Required**: No
- **Description**: Additional headers to include in all requests.

#### `timeout`
- **Type**: `float`
- **Required**: No
- **Default**: `60.0`
- **Description**: Request timeout in seconds. Ignored if custom `httpx_client` provided.

#### `follow_redirects`
- **Type**: `bool`
- **Required**: No
- **Default**: `True`
- **Description**: Whether HTTP redirects should be followed. Ignored if custom `httpx_client` provided.

#### `httpx_client`
- **Type**: `httpx.Client`
- **Required**: No
- **Description**: Custom preconfigured httpx client for advanced use cases.

### Request Example
```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
    timeout=30.0,
)
```

### Module Access

The client provides access to all Intercom API modules through properties:

| Property | Type | Description |
|----------|------|-------------|
| admins | `AdminsClient` | Admin user management |
| ai_content | `AiContentClient` | AI content import sources |
| articles | `ArticlesClient` | Help center articles |
| away_status_reasons | `AwayStatusReasonsClient` | Away status configuration |
| calls | `CallsClient` | Call records and transcripts |
| companies | `CompaniesClient` | Company/organization management |
| contacts | `ContactsClient` | Contact/user management |
| conversations | `ConversationsClient` | Conversation management |
| custom_channel_events | `CustomChannelEventsClient` | Custom channel events |
| custom_object_instances | `CustomObjectInstancesClient` | Custom object instances |
| data_attributes | `DataAttributesClient` | Data attribute definitions |
| data_events | `DataEventsClient` | Data event tracking |
| data_export | `DataExportClient` | Data export operations |
| events | `EventsClient` | Event creation and queries |
| export | `ExportClient` | Reporting data export |
| help_centers | `HelpCentersClient` | Help center management |
| internal_articles | `InternalArticlesClient` | Internal article management |
| ip_allowlist | `IpAllowlistClient` | IP allowlist configuration |
| jobs | `JobsClient` | Background job tracking |
| messages | `MessagesClient` | Message creation and delivery |
| news | `NewsClient` | News and newsfeed management |
| notes | `NotesClient` | Contact notes |
| phone_call_redirects | `PhoneCallRedirectsClient` | Phone call redirect configuration |
| segments | `SegmentsClient` | Segment queries and management |
| subscription_types | `SubscriptionTypesClient` | Subscription type management |
| tags | `TagsClient` | Tag management |
| teams | `TeamsClient` | Team management |
| ticket_states | `TicketStatesClient` | Ticket state configuration |
| ticket_types | `TicketTypesClient` | Ticket type definitions |
| tickets | `TicketsClient` | Ticket management |
| visitors | `VisitorsClient` | Visitor management |
```

--------------------------------

### Identify and Tag a New User

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/16-QUICK-START.md

This workflow demonstrates how to find an existing contact by email, tag them as a 'new_user', and record a 'user_signup' event. Ensure the 'new_user_tag_id' is a valid tag ID in your Intercom workspace.

```python
# Create or find contact
contact = client.contacts.find(email="user@example.com")

# Tag as new user
client.tags.tag_contact(
    contact_id=contact.id,
    tag_id="new_user_tag_id"
)

# Update with signup event
client.events.create(
    request={
        "event_name": "user_signup",
        "created_at": int(time.time()),
        "intercom_user_id": contact.id,
        "metadata": {"source": "web"}
    }
)
```

--------------------------------

### GET /intercom/python-intercom/unstable/articles/retrieve_article

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches the details of a single article by its ID.

```APIDOC
## GET /intercom/python-intercom/unstable/articles/retrieve_article

### Description
Fetches the details of a single article by its ID.

### Method
GET

### Endpoint
/intercom/python-intercom/unstable/articles/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique identifier for the article which is given by Intercom.

#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Request Example
```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
client.unstable.articles.retrieve_article(
    id=1,
)
```

### Response
#### Success Response (200)
- **article** (object) - The article object with its details.

#### Response Example
```json
{
  "id": "1",
  "title": "Example Article",
  "body": "Content of the example article."
}
```
```

--------------------------------

### GET /calls/{call_id}

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Retrieves a single call by its ID.

```APIDOC
## GET /calls/{call_id}

### Description
Retrieve a single call by its ID.

### Method
GET

### Endpoint
/calls/{call_id}

### Path Parameters
- **call_id** (string) - Required - The ID of the call to retrieve.

### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
client.calls.show_call(call_id="call_id")
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the call.
- **type** (string) - The type of the call (e.g., 'inbound', 'outbound').
- **created_at** (integer) - Timestamp when the call was created.

#### Response Example
```json
{
  "id": "call_123",
  "type": "inbound",
  "created_at": 1678886400
}
```
```

--------------------------------

### Type Hinting with Optional

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/15-COMMON-TYPES.md

Shows how to use type hints, specifically `typing.Optional`, for function parameters. This improves code readability and allows for static analysis.

```python
from typing import Optional
from intercom import Intercom, Contact

def process_contact(contact: Optional[Contact]) -> None:
    if contact is None:
        return
    
    print(f"Email: {contact.email}")
```

--------------------------------

### GET /subscription_types

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Retrieves a list of all available subscription types.

```APIDOC
## GET /subscription_types

### Description
You can list all subscription types. A list of subscription type objects will be returned.

### Method
GET

### Endpoint
/subscription_types

### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
client.subscription_types.list()
```

### Response
#### Success Response (200)
- **subscription_types** (array) - A list of subscription type objects.

#### Response Example
```json
[
  {
    "id": "sub_123",
    "name": "Premium Plan"
  }
]
```
```

--------------------------------

### Create Contact with Custom Attributes

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/INDEX.md

Shows how to create a new contact and assign custom attributes like 'plan' and 'lifetime_value'. This is useful for storing flexible, user-specific data.

```python
contact = client.contacts.create(
    request={
        "email": "user@example.com",
        "custom_attributes": {
            "plan": "premium",
            "lifetime_value": 5000
        }
    }
)
```

--------------------------------

### GET /ai_content/external_pages

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Retrieves a list of all external pages for a workspace.

```APIDOC
## GET /ai_content/external_pages

### Description
Retrieves a list of all external pages for a workspace.

### Method
GET

### Endpoint
/ai_content/external_pages

### Response
#### Success Response (200)
- **external_pages** (array) - A list of external page objects.
  - **id** (str) - The unique identifier for the external page.
  - **url** (str) - The URL of the external page.
  - **title** (str) - The title of the external page.
  - **status** (str) - The status of the external page.
  - **created_at** (int) - The timestamp when the external page was created.

#### Response Example
```json
{
  "external_pages": [
    {
      "id": "ep_1",
      "url": "https://www.example.com/page1",
      "title": "Example Page 1",
      "status": "processed",
      "created_at": 1678886400
    },
    {
      "id": "ep_2",
      "url": "https://www.example.com/page2",
      "title": "Example Page 2",
      "status": "pending",
      "created_at": 1678886500
    }
  ]
}
```
```

--------------------------------

### List Available Datasets and Attributes Python

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Lists all available datasets and their corresponding attributes for data export. Requires an initialized Intercom client.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
client.export.list_available_datasets_and_attributes()
```

--------------------------------

### Initialize Asynchronous Intercom Client

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/00-CLIENT-INITIALIZATION.md

Instantiate the asynchronous Intercom client. All methods on this client are async and return coroutines, requiring `asyncio` to run.

```python
import asyncio
from intercom import AsyncIntercom

async def main():
    client = AsyncIntercom(
        token="YOUR_TOKEN",
    )
    result = await client.contacts.find(email="test@example.com")
    print(result)

asyncio.run(main())
```

--------------------------------

### Retrieve Article

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/05-ARTICLES-HELP-CENTER-API.md

Get a single article by its unique identifier.

```APIDOC
## Retrieve Article

### Description
Get a single article by ID.

### Method
GET

### Endpoint
/articles/{article_id}

### Parameters
#### Path Parameters
- **article_id** (str) - Required - The unique identifier of the article.

### Response
#### Success Response (200)
- **id** (str) - The unique identifier for the article.
- **title** (str) - The title of the article.
- **body** (str) - The content of the article.
- **author_id** (int) - The ID of the author.
- **parent_id** (str) - The ID of the parent collection or help center.
- **parent_type** (str) - The type of the parent ('collection' or 'help_center').
- **state** (str) - The current state of the article ('draft' or 'published').

### Request Example
```python
article = client.articles.retrieve(article_id="article_123")
print(article.title)
```
```

--------------------------------

### List All Help Centers

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Retrieves a list of all Help Centers. Supports pagination by page number and results per page. The response can be iterated directly or paginated page-by-page.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
response = client.help_centers.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page
```

--------------------------------

### GET /emails

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Lists all sender email address settings for the workspace.

```APIDOC
## GET /emails

### Description
Lists all sender email address settings for the workspace.

### Method
GET

### Endpoint
/emails

### Parameters
#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **emails** (list) - A list of email setting objects.

#### Response Example
```json
[
  {
    "id": "email_1",
    "email": "support@example.com",
    "type": "sender"
  }
]
```
```

--------------------------------

### Create and Update Contact (Synchronous)

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/INDEX.md

Demonstrates basic synchronous usage for creating and updating contacts. Requires an API token for authentication.

```python
from intercom import Intercom

client = Intercom(token="YOUR_API_TOKEN")

# Create a contact
contact = client.contacts.create(
    request={
        "email": "user@example.com",
        "name": "John Doe"
    }
)

# Find and update
contact = client.contacts.find(email="user@example.com")
client.contacts.update(
    contact_id=contact.id,
    request={"name": "Jane Doe"}
)
```

--------------------------------

### GET /brands/{id}

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches a specific brand by its unique identifier.

```APIDOC
## GET /brands/{id}

### Description
Fetches a specific brand by its unique identifier.

### Method
GET

### Endpoint
/brands/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The unique identifier of the brand.

#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **brand** (object) - The brand object.

#### Response Example
```json
{
  "id": "1",
  "name": "Default Brand",
  "workspace_id": "123"
}
```
```

--------------------------------

### GET /internal_articles/search

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Searches for internal articles based on specified criteria.

```APIDOC
## GET /internal_articles/search

### Description
Searches for internal articles by making a GET request to the search endpoint. You can filter by folder ID.

### Method
GET

### Endpoint
https://api.intercom.io/internal_articles/search

### Parameters
#### Query Parameters
- **folder_id** (str) - Optional - The ID of the folder to search in.

### Request Example
```python
{
  "folder_id": "your_folder_id"
}
```

### Response
#### Success Response (200)
- **articles** (array) - A list of internal articles matching the search criteria.
- **total_count** (int) - The total number of articles found.

#### Response Example
{
  "articles": [
    {
      "id": 123,
      "title": "Example Article",
      "body": "This is the content of the article."
    }
  ],
  "total_count": 1
}
```

--------------------------------

### Initialize Synchronous Intercom Client

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/00-CLIENT-INITIALIZATION.md

Instantiate the synchronous Intercom client with your API token. The token can be provided directly or loaded from the INTERCOM_API_KEY environment variable.

```python
from intercom import Intercom

client = Intercom(
    token="YOUR_TOKEN",
)
```

--------------------------------

### GET /segments/{segment_id}

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches the details of a single segment by its ID.

```APIDOC
## GET /segments/{segment_id}

### Description
Fetches the details of a single segment.

### Method
GET

### Endpoint
/segments/{segment_id}

### Path Parameters
- **segment_id** (string) - Required - The unique identifier of the segment.

### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
client.segments.find(segment_id="123")
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the segment.
- **name** (string) - The name of the segment.
- **created_at** (integer) - Timestamp when the segment was created.
- **updated_at** (integer) - Timestamp when the segment was last updated.

#### Response Example
```json
{
  "id": "123",
  "name": "Active Users",
  "created_at": 1678886400,
  "updated_at": 1678886400
}
```
```

--------------------------------

### create()

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/04-TICKETS-API.md

Create a new ticket with specified details including contacts, subject, and description.

```APIDOC
## create()

### Description
Create a new ticket with specified details including contacts, subject, and description.

### Method
POST

### Endpoint
/tickets

### Parameters
#### Request Body
- **request** (CreateTicketRequestBody) - Optional - Ticket data.
  - **display_as** (str) - Yes - 'plaintext' or 'html'.
  - **ticket_type_id** (str) - Yes - Ticket type ID.
  - **contacts** (List[Contact]) - Yes - Contact details.
  - **subject** (str) - No - Ticket subject/title.
  - **description** (str) - No - Ticket description.
  - **created_at** (int) - No - Creation timestamp.
  - **assignment** (Dict) - No - `{"admin_id": 123}` or `{"team_id": 456}`.
  - **custom_attributes** (Dict[str, Any]) - No - Custom fields.
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **ticket** (Ticket) - The newly created ticket object.

### Request Example
```json
{
  "display_as": "plaintext",
  "ticket_type_id": "type_123",
  "subject": "Bug report",
  "description": "Issue with feature X",
  "contacts": [
    {
      "id": "contact_123"
    }
  ]
}
```

### Response Example
```json
{
  "id": "ticket_456",
  "display_as": "plaintext",
  "ticket_type_id": "type_123",
  "subject": "Bug report",
  "description": "Issue with feature X",
  "created_at": 1678886400,
  "assignee_id": null,
  "team_id": null,
  "custom_attributes": {},
  "contacts": [
    {
      "id": "contact_123"
    }
  ]
}
```
```

--------------------------------

### GET /notes

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches a list of notes associated with a specific contact.

```APIDOC
## GET /notes

### Description
Fetches a list of notes that are associated to a contact.

### Method
GET

### Endpoint
/notes

### Parameters
#### Query Parameters
- **contact_id** (str) - Required - The unique identifier of a contact.
- **page** (int) - Optional - The page of results to fetch. Defaults to the first page.
- **per_page** (int) - Optional - How many results to display per page. Defaults to 15.

### Request Example
```json
{
  "contact_id": "contact_id",
  "page": 1,
  "per_page": 15
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the note.
- **body** (string) - The content of the note.
- **contact_id** (string) - The identifier of the contact the note is associated with.

#### Response Example
```json
[
  {
    "id": "note_id_1",
    "body": "This is the first note.",
    "contact_id": "contact_id"
  },
  {
    "id": "note_id_2",
    "body": "This is the second note.",
    "contact_id": "contact_id"
  }
]
```
```

--------------------------------

### GET /internal_articles/{id}

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches the details of a single internal article.

```APIDOC
## GET /internal_articles/<id>

### Description
Fetches the details of a single internal article.

### Method
GET

### Endpoint
https://api.intercom.io/internal_articles/<id>

### Parameters
#### Path Parameters
- **id** (int) - Required - The unique identifier for the internal article.

#### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **article** (object) - Details of the internal article.

#### Response Example
```json
{
  "id": 1,
  "title": "Troubleshooting Guide",
  "body": "This is the body of the troubleshooting guide.",
  "author_id": 1295,
  "owner_id": 1295,
  "created_at": 1678886400,
  "updated_at": 1678886400
}
```
```

--------------------------------

### GET /emails/{id}

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches a specific email setting by its unique identifier.

```APIDOC
## GET /emails/{id}

### Description
Fetches a specific email setting by its unique identifier.

### Method
GET

### Endpoint
/emails/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The unique identifier of the email setting.

#### Query Parameters
- **request_options** (typing.Optional[RequestOptions]) - Optional - Request-specific configuration.

### Response
#### Success Response (200)
- **email** (object) - The email setting object.

#### Response Example
```json
{
  "id": "email_1",
  "email": "support@example.com",
  "type": "sender"
}
```
```

--------------------------------

### Documentation Formatting Conventions

Source: https://github.com/intercom/python-intercom/blob/master/_autodocs/README.md

The documentation uses Markdown with code fences, tables for parameter details, inline code for types, and descriptive headings. Examples are provided with realistic usage patterns to illustrate API interactions.

```markdown
- **Markdown** with code fences
- **Tables** for parameter documentation
- **Inline code** for types and identifiers
- **Sections** with descriptive headings
- **Examples** with realistic patterns
```

--------------------------------

### Get Ticket Type

Source: https://github.com/intercom/python-intercom/blob/master/reference.md

Fetches the details of a single ticket type by its ID.

```APIDOC
## GET /intercom/python-intercom/unstable/ticket_types/{id}

### Description
Fetches the details of a single ticket type.

### Method
GET

### Endpoint
/intercom/python-intercom/unstable/ticket_types/{id}

### Parameters
#### Path Parameters
- **id** (str) - Required - The unique identifier for the ticket type which is given by Intercom.

#### Query Parameters
- **request_options** (RequestOptions) - Optional - Request-specific configuration.

### Request Example
```python
from intercom import Intercom

client = Intercom(token="YOUR_TOKEN")
client.unstable.ticket_types.get_ticket_type(id="id")
```

### Response
#### Success Response (200)
- **ticket_type** (object) - The ticket type object.

#### Response Example
```json
{
  "ticket_type": {
    "id": "123",
    "name": "Support Request",
    "description": "For general support inquiries."
  }
}
```
```