0
# Client & Bot Management
1

2
Manage bot lifecycle, configuration, connection, and core functionality.
3

4
## Core Client Classes
5

6
### Client
7

8
Main bot client class for Discord applications.
9

10
```python { .api }
11
Client(
12
    *,
13
    token: str | None = None,
14
    intents: Union[int, Intents] = Intents.DEFAULT,
15
    status: Status = Status.ONLINE,
16
    activity: Union[Activity, str] = None,
17
    sync_interactions: bool = True,
18
    sync_ext: bool = True,
19
    delete_unused_application_cmds: bool = False,
20
    enforce_interaction_perms: bool = True,
21
    fetch_members: bool = False,
22
    send_command_tracebacks: bool = True,
23
    auto_defer: Absent[Union[AutoDefer, bool]] = MISSING,
24
    interaction_context: Type[InteractionContext] = InteractionContext,
25
    component_context: Type[BaseContext] = ComponentContext,
26
    autocomplete_context: Type[BaseContext] = AutocompleteContext,
27
    modal_context: Type[BaseContext] = ModalContext,
28
    slash_context: Type[BaseContext] = SlashContext,
29
    context_menu_context: Type[BaseContext] = ContextMenuContext,
30
    owner_ids: Iterable["Snowflake_Type"] = (),
31
    show_ratelimit_tracebacks: bool = False,
32
    shard_id: int = 0,
33
    total_shards: int = 1,
34
    basic_logging: bool = False,
35
    logging_level: int = logging.INFO,
36
    logger: logging.Logger = MISSING,
37
    debug_scope: Absent["Snowflake_Type"] = MISSING,
38
    disable_dm_commands: bool = False,
39
    global_post_run_callback: Absent[Callable[..., Coroutine]] = MISSING,
40
    global_pre_run_callback: Absent[Callable[..., Coroutine]] = MISSING,
41
    **kwargs
42
) -> Client
43
```
44

45
**Core Methods**:
46

47
- `start()` { .api } - Start the bot and connect to Discord
48
- `login()` { .api } - Login to Discord (called automatically by start)
49
- `stop()` { .api } - Stop the bot and disconnect
50
- `change_presence(status, activity)` { .api } - Update bot's status and activity
51
- `synchronise_interactions()` { .api } - Sync application commands with Discord
52

53
**Extension Methods**:
54

55
- `load_extension(name: str)` { .api } - Load an extension
56
- `unload_extension(name: str)` { .api } - Unload an extension
57
- `reload_extension(name: str)` { .api } - Reload an extension
58

59
**Guild Methods**:
60

61
- `get_guild(guild_id: Snowflake)` { .api } - Get guild from cache
62
- `fetch_guild(guild_id: Snowflake)` { .api } - Fetch guild from API
63

64
**Component & Callback Methods**:
65

66
- `add_component_callback(callback)` { .api } - Register component callback
67
- `add_modal_callback(callback)` { .api } - Register modal callback
68
- `wait_for(event, check=None, timeout=None)` { .api } - Wait for specific event
69
- `wait_for_component(custom_id=None, timeout=None)` { .api } - Wait for component interaction
70
- `wait_for_modal(custom_id=None, timeout=None)` { .api } - Wait for modal submission
71

72
### AutoShardedClient
73

74
Automatically sharded version of Client for large bots (2500+ guilds).
75

76
```python
77
AutoShardedClient(
78
    token: str,
79
    shard_count: int = None,
80
    **kwargs
81
) -> AutoShardedClient
82
```
83

84
Inherits all `Client` methods with automatic shard management.
85

86
## Configuration & Metadata
87

88
### Version Information
89

90
```python
91
__version__: str  # Library version
92
__api_version__: int  # Discord API version (10)
93
__py_version__: str  # Required Python version
94
__repo_url__: str  # GitHub repository URL
95
```
96

97
### Logging
98

99
```python
100
get_logger(name: str = None) -> logging.Logger  # Get library logger
101
logger_name: str = "interactions"  # Default logger name
102
```
103

104
### Constants & Limits
105

106
```python
107
# Discord API Limits
108
ACTION_ROW_MAX_ITEMS: int = 5
109
SELECTS_MAX_OPTIONS: int = 25
110
SELECT_MAX_NAME_LENGTH: int = 100
111
CONTEXT_MENU_NAME_LENGTH: int = 32
112
SLASH_CMD_NAME_LENGTH: int = 32
113
SLASH_CMD_MAX_DESC_LENGTH: int = 100
114
SLASH_CMD_MAX_OPTIONS: int = 25
115
SLASH_OPTION_NAME_LENGTH: int = 100
116

117
# Embed Limits
118
EMBED_MAX_NAME_LENGTH: int = 256
119
EMBED_MAX_DESC_LENGTH: int = 4096
120
EMBED_MAX_FIELDS: int = 25
121
EMBED_TOTAL_MAX: int = 6000
122
EMBED_FIELD_VALUE_LENGTH: int = 1024
123

124
# Other Constants
125
DISCORD_EPOCH: int = 1420070400000
126
PREMIUM_GUILD_LIMITS: dict  # Premium tier limits
127
```
128

129
## Sentinel Values
130

131
### Missing Values
132

133
```python
134
MISSING  # Sentinel for missing values
135
Missing  # Missing type class
136
Absent[T]  # Union[T, Missing] type
137
```
138

139
### Scopes
140

141
```python
142
GLOBAL_SCOPE  # Global command scope instance
143
GlobalScope  # Global scope class
144
MENTION_PREFIX  # Mention prefix instance
145
MentionPrefix  # Mention prefix class
146
```
147

148
### Utility Types
149

150
```python
151
Sentinel  # Base sentinel class
152
Singleton  # Singleton metaclass
153
T  # Generic type variable
154
T_co  # Covariant type variable
155
```
156

157
## Client Lifecycle
158

159
### Basic Setup
160

161
```python
162
import interactions
163
from interactions import listen, events
164

165
# Basic bot
166
bot = interactions.Client(token="TOKEN")
167

168
@listen()
169
async def on_ready(event: events.Ready):
170
    print(f"Bot is ready! Logged in as {event.user}")
171

172
bot.start()
173
```
174

175
### Advanced Configuration
176

177
```python
178
import interactions
179
from interactions import Intents, Status, Activity, ActivityType
180

181
bot = interactions.Client(
182
    token="TOKEN",
183
    intents=Intents.ALL,
184
    status=Status.DND,
185
    activity=Activity(
186
        name="Custom Game",
187
        type=ActivityType.PLAYING
188
    ),
189
    sync_interactions=True,
190
    delete_unused_application_cmds=True,
191
    auto_defer=interactions.AutoDefer(enabled=True, time_until_defer=2.0)
192
)
193
```
194

195
### Sharded Bot
196

197
```python
198
import interactions
199

200
# For large bots (2500+ guilds)
201
bot = interactions.AutoShardedClient(
202
    token="TOKEN",
203
    shard_count=4  # Optional, auto-calculated if not provided
204
)
205
```
206

207
## Event Handling
208

209
### Event Listeners
210

211
```python
212
@listen()
213
async def on_ready(event: events.Ready):
214
    """Called when bot is ready"""
215
    pass
216

217
@listen()  
218
async def on_guild_join(event: events.GuildJoin):
219
    """Called when bot joins a guild"""
220
    guild = event.guild
221
```
222

223
### Listener Decorators
224

225
```python
226
@listen()
227
async def on_message_create(event):
228
    """Listen to message create events"""
229
    message = event.message
230
    print(f"Message from {message.author}: {message.content}")
231

232
@listen(interactions.events.GuildJoin)
233
async def on_guild_join(event):
234
    """Listen to guild join events"""
235
    guild = event.guild
236
    print(f"Joined guild: {guild.name}")
237
```
238

239
## Status & Presence
240

241
### Change Status
242

243
```python
244
from interactions import Status, Activity, ActivityType
245

246
# Change status
247
await bot.change_presence(status=Status.IDLE)
248

249
# Set activity
250
activity = Activity(name="Custom Game", type=ActivityType.PLAYING)
251
await bot.change_presence(activity=activity)
252

253
# Combine both
254
await bot.change_presence(
255
    status=Status.DND,
256
    activity=Activity(name="Maintenance", type=ActivityType.WATCHING)
257
)
258
```
259

260
### Activity Types
261

262
```python
263
from interactions import ActivityType
264

265
ActivityType.PLAYING    # "Playing {name}"
266
ActivityType.STREAMING  # "Streaming {name}"  
267
ActivityType.LISTENING  # "Listening to {name}"
268
ActivityType.WATCHING   # "Watching {name}"
269
ActivityType.COMPETING  # "Competing in {name}"
270
```
271

272
## Error Handling
273

274
### Built-in Exceptions
275

276
```python
277
from interactions import errors
278

279
# Common exceptions
280
errors.BotException          # Base bot exception
281
errors.InteractionMissingAccess  # Missing interaction permissions
282
errors.ExtensionLoadException    # Extension loading failed
283
errors.ExtensionNotFound         # Extension not found
284
errors.HTTPException            # HTTP request failed
285
errors.Forbidden               # 403 Forbidden
286
errors.NotFound               # 404 Not Found
287
```
288

289
### Error Event Handling
290

291
```python
292
@listen(interactions.events.Error)
293
async def on_error(event):
294
    """Handle general errors"""
295
    print(f"Error occurred: {event.error}")
296

297
@listen(interactions.events.CommandError) 
298
async def on_command_error(event):
299
    """Handle command errors"""
300
    print(f"Command error in {event.ctx.command}: {event.error}")
301
```
302

303
## Extensions Management
304

305
### Load Extensions
306

307
```python
308
# Load extension
309
bot.load_extension("extensions.moderation")
310

311
# Load multiple extensions
312
extensions = ["extensions.moderation", "extensions.fun", "extensions.admin"]
313
for ext in extensions:
314
    bot.load_extension(ext)
315
```
316

317
### Extension Events
318

319
```python
320
@listen(interactions.events.ExtensionLoad)
321
async def on_extension_load(event):
322
    print(f"Extension loaded: {event.extension}")
323

324
@listen(interactions.events.ExtensionUnload) 
325
async def on_extension_unload(event):
326
    print(f"Extension unloaded: {event.extension}")
327
```
328

329
## Cache & Utilities
330

331
### Cache Access
332

333
```python
334
# Access cached objects
335
guild = bot.get_guild(guild_id)
336
user = bot.get_user(user_id)
337
channel = bot.get_channel(channel_id)
338

339
# Cache properties
340
bot.guilds       # List of cached guilds
341
bot.users        # List of cached users  
342
bot.channels     # List of cached channels
343
```
344

345
### Utility Modules
346

347
```python
348
from interactions import utils, smart_cache
349

350
# Utility functions in bot.utils
351
# Smart caching system in bot.smart_cache
352
```