# Telethon Extractor
```{admonition} Module type

<span style='color: #00FF00'>[extractor](/core_modules.md#extractor-modules)</a></span>
```

The `TelethonExtractor` uses the Telethon library to archive posts and media from Telegram channels and groups. 
It supports private and public channels, downloading grouped posts with media, and can join channels using invite links 
if provided in the configuration. 

### Features
- Fetches posts and metadata from Telegram channels and groups, including private channels.
- Downloads media attachments (e.g., images, videos, audio) from individual posts or grouped posts.
- Handles channel invites to join channels dynamically during setup.
- Utilizes Telethon's capabilities for reliable Telegram interactions.
- Outputs structured metadata and media using `Metadata` and `Media` objects.

### Setup
To use the `TelethonExtractor`, you must configure the following:
- **API ID and API Hash**: Obtain these from [my.telegram.org](https://my.telegram.org/apps).
- **Session File**: Optional, but records login sessions for future use (default: `secrets/anon.session`).
- **Bot Token**: Optional, allows access to additional content (e.g., large videos) but limits private channel archiving.
- **Channel Invites**: Optional, specify a JSON string of invite links to join channels during setup.

### First Time Login
The first time you run, you will be prompted to do a authentication with the phone number associated, alternatively you can put your `anon.session` in the root.




## Configuration Options

### YAML
```{code} yaml

# steps configuration
steps:
...
  extractors:
  - telethon_extractor
...

# module configuration
...

telethon_extractor:
  api_id:
  api_hash:
  bot_token:
  session_file: secrets/anon
  join_channels: true
  channel_invites: {}



```

### Command Line:
| Option | Description | Default | Type|
| --- | --- | --- | --- |
| `telethon_extractor.api_id` | Optional. telegram API_ID value, go to https://my.telegram.org/apps | None | string |
| `telethon_extractor.api_hash` | Optional. telegram API_HASH value, go to https://my.telegram.org/apps | None | string |
| `telethon_extractor.bot_token` | Optional. optional, but allows access to more content such as large videos, talk to @botfather | None | string |
| `telethon_extractor.session_file` | Optional. optional, records the telegram login session for future usage, '.session' will be appended to the provided value. | secrets/anon | string |
| `telethon_extractor.join_channels` | Optional. disables the initial setup with channel_invites config, useful if you have a lot and get stuck | True | bool |
| `telethon_extractor.channel_invites` | Optional. (JSON string) private channel invite links (format: t.me/joinchat/HASH OR t.me/+HASH) and (optional but important to avoid hanging for minutes on startup) channel id (format: CHANNEL_ID taken from a post url like https://t.me/c/CHANNEL_ID/1), the telegram account will join any new channels on setup | {} | json_loader |

[API Reference](../../../autoapi/telethon_extractor/index)