0
# Communication
1

2
Conversations, announcements, messaging, and notification management within Canvas. Comprehensive communication tools for connecting students, instructors, and administrators.
3

4
## Capabilities
5

6
### Conversations
7

8
Canvas's internal messaging system for private communication between users.
9

10
```python { .api }
11
def get_conversations(self, **kwargs) -> PaginatedList[Conversation]:
12
    """
13
    Get list of conversations for the current user.
14
    
15
    Parameters:
16
    - scope: Filter conversations ('unread', 'starred', 'sent', 'archived')
17
    - filter: Additional filters ('course_123', 'group_456', 'user_789')
18
    - filter_mode: Filter mode ('and', 'or', 'default')
19
    - interleave_submissions: Include submission comments
20
    - include_all_conversation_ids: Include all conversation IDs in response
21
    - include: Additional data ('participant_avatars', 'participant_contexts')
22
    
23
    Returns:
24
    Paginated list of Conversation objects
25
    """
26

27
def get_conversation(self, conversation, **kwargs) -> Conversation:
28
    """
29
    Get a single conversation by ID.
30
    
31
    Parameters:
32
    - conversation: Conversation object or conversation ID
33
    - include: Additional data to include
34
    - auto_mark_as_read: Automatically mark as read when retrieved
35
    
36
    Returns:
37
    Conversation object
38
    """
39

40
def create_conversation(self, recipients: list, body: str, **kwargs) -> list[Conversation]:
41
    """
42
    Create a new conversation.
43
    
44
    Parameters:
45
    - recipients: List of recipient IDs (can include 'course_123', 'group_456' prefixes)
46
    - body: Message body text
47
    - subject: Conversation subject
48
    - force_new: Force creation of new conversation vs adding to existing
49
    - group_conversation: Create as group conversation
50
    - attachment_ids: List of file attachment IDs
51
    - media_comment_id: Media comment ID
52
    - media_comment_type: Media comment type ('audio', 'video')
53
    - user_note: Add as user note
54
    - mode: Conversation mode ('sync', 'async')
55
    - scope: Conversation scope ('unread', 'starred', etc.)
56
    - filter: Additional filters
57
    - filter_mode: Filter mode
58
    - context_code: Context for the conversation
59
    
60
    Returns:
61
    List of Conversation objects (may be multiple if sent to different contexts)
62
    """
63
```
64

65
### Conversation Management
66

67
Manage existing conversations with bulk operations and status updates.
68

69
```python { .api }
70
def conversations_batch_update(self, conversation_ids: list, event: str, **kwargs) -> Progress:
71
    """
72
    Perform batch operations on multiple conversations.
73
    
74
    Parameters:
75
    - conversation_ids: List of conversation IDs (max 500)
76
    - event: Action to perform ('mark_as_read', 'mark_as_unread', 'star', 'unstar', 'archive', 'destroy')
77
    
78
    Returns:
79
    Progress object for tracking the batch operation
80
    """
81

82
def conversations_mark_all_as_read(self, **kwargs) -> bool:
83
    """
84
    Mark all conversations as read for the current user.
85
    
86
    Returns:
87
    True if successful
88
    """
89

90
def conversations_unread_count(self, **kwargs) -> dict:
91
    """
92
    Get the number of unread conversations.
93
    
94
    Returns:
95
    Dictionary with 'unread_count' key
96
    """
97

98
def conversations_get_running_batches(self, **kwargs) -> dict:
99
    """
100
    Get currently running conversation batch operations.
101
    
102
    Returns:
103
    Dictionary with list of batch objects
104
    """
105
```
106

107
### Individual Conversation Operations
108

109
Operations on specific conversation objects.
110

111
```python { .api }
112
class Conversation(CanvasObject):
113
    def edit(self, **kwargs) -> Conversation:
114
        """
115
        Update conversation properties.
116
        
117
        Parameters:
118
        - conversation: Dictionary with updates:
119
            - workflow_state: New state ('read', 'unread', 'archived')
120
            - subscribed: Whether user is subscribed
121
            - starred: Whether conversation is starred
122
        - scope: Conversation scope filter
123
        - filter: Additional filters
124
        - filter_mode: Filter mode
125
        
126
        Returns:
127
        Updated Conversation object
128
        """
129
    
130
    def delete(self, **kwargs) -> Conversation:
131
        """Delete/remove the conversation."""
132
    
133
    def add_recipients(self, recipients: list, **kwargs) -> Conversation:
134
        """
135
        Add recipients to the conversation.
136
        
137
        Parameters:
138
        - recipients: List of recipient IDs to add
139
        
140
        Returns:
141
        Updated Conversation object
142
        """
143
    
144
    def add_message(self, body: str, **kwargs) -> Conversation:
145
        """
146
        Add a message to the conversation.
147
        
148
        Parameters:
149
        - body: Message body text
150
        - attachment_ids: List of file attachment IDs
151
        - media_comment_id: Media comment ID
152
        - media_comment_type: Media comment type
153
        - recipients: List of specific recipients for this message
154
        - included_messages: List of message IDs to include in context
155
        - user_note: Add as user note
156
        
157
        Returns:
158
        Updated Conversation object with new message
159
        """
160
```
161

162
### Announcements
163

164
Course and account-level announcements for broad communication.
165

166
```python { .api }
167
def get_announcements(self, context_codes: list, **kwargs) -> PaginatedList[DiscussionTopic]:
168
    """
169
    List announcements from specified contexts.
170
    
171
    Parameters:
172
    - context_codes: List of context codes ('course_123', 'account_456')
173
    - start_date: Start date for filtering announcements  
174
    - end_date: End date for filtering announcements
175
    - active_only: Only return active announcements
176
    - latest_only: Only return latest announcement per context
177
    - include: Additional data ('sections', 'course_section')
178
    
179
    Returns:
180
    Paginated list of DiscussionTopic objects representing announcements
181
    """
182
```
183

184
### Communication Messages
185

186
System-generated messages and notifications sent to users.
187

188
```python { .api }
189
def get_comm_messages(self, user, **kwargs) -> PaginatedList[CommMessage]:
190
    """
191
    Get communication messages sent to a user.
192
    
193
    Parameters:
194
    - user: User object or user ID
195
    - start_time: Start date for filtering messages
196
    - end_time: End date for filtering messages
197
    
198
    Returns:
199
    Paginated list of CommMessage objects
200
    """
201

202
class CommMessage(CanvasObject):
203
    """Represents a communication message sent to a user."""
204
    # Read-only object representing system messages
205
```
206

207
### Notification Preferences
208

209
Manage how users receive different types of notifications.
210

211
```python { .api }
212
class NotificationPreference(CanvasObject):
213
    """
214
    Represents user notification preferences for different communication channels.
215
    
216
    Attributes:
217
    - notification: Type of notification
218
    - category: Notification category
219
    - frequency: How often to send ('immediately', 'daily', 'weekly', 'never')
220
    """
221
```
222

223
## Discussion Topics and Announcements
224

225
Extended functionality for discussion-based communication.
226

227
```python { .api }
228
class DiscussionTopic(CanvasObject):
229
    def edit(self, **kwargs) -> DiscussionTopic:
230
        """
231
        Edit discussion topic/announcement.
232
        
233
        Parameters:
234
        - title: Discussion title
235
        - message: Discussion message/content
236
        - discussion_type: Type ('side_comment', 'threaded')
237
        - published: Whether published
238
        - delayed_post_at: When to automatically publish
239
        - lock_at: When to automatically lock
240
        - podcast_enabled: Enable podcast feed
241
        - podcast_has_student_posts: Include student posts in podcast
242
        - require_initial_post: Require initial post before viewing replies
243
        - assignment: Assignment data if graded discussion
244
        - is_announcement: Whether this is an announcement
245
        
246
        Returns:
247
        Updated DiscussionTopic object
248
        """
249
    
250
    def delete(self, **kwargs) -> DiscussionTopic:
251
        """Delete the discussion topic/announcement."""
252
    
253
    def post_entry(self, **kwargs) -> DiscussionEntry:
254
        """
255
        Post an entry (reply) to the discussion.
256
        
257
        Parameters:
258
        - message: Entry message text
259
        - attachment: File attachment
260
        - parent_id: Parent entry ID (for replies to specific posts)
261
        
262
        Returns:
263
        DiscussionEntry object
264
        """
265
    
266
    def get_entries(self, **kwargs) -> PaginatedList[DiscussionEntry]:
267
        """
268
        Get discussion entries (posts/replies).
269
        
270
        Parameters:
271
        - ids: Specific entry IDs to retrieve
272
        - include_new_entries: Include entries newer than specified date
273
        
274
        Returns:
275
        Paginated list of DiscussionEntry objects
276
        """
277
    
278
    def mark_as_read(self, **kwargs) -> bool:
279
        """Mark discussion as read for current user."""
280
    
281
    def mark_as_unread(self, **kwargs) -> bool:
282
        """Mark discussion as unread for current user."""
283
    
284
    def subscribe(self, **kwargs) -> bool:
285
        """Subscribe to discussion notifications."""
286
    
287
    def unsubscribe(self, **kwargs) -> bool:
288
        """Unsubscribe from discussion notifications."""
289
```
290

291
## Usage Examples
292

293
### Creating and Managing Conversations
294

295
```python
296
from canvasapi import Canvas
297

298
canvas = Canvas("https://canvas.example.com", "your-token")
299

300
# Create a conversation with multiple recipients
301
recipients = [
302
    '123',           # Individual user ID
303
    '456',           # Another user ID  
304
    'course_789',    # All users in course 789
305
    'group_101'      # All users in group 101
306
]
307

308
conversations = canvas.create_conversation(
309
    recipients=recipients,
310
    subject="Important Course Update",
311
    body="Hello everyone! I wanted to update you on the upcoming assignment changes...",
312
    group_conversation=True
313
)
314

315
# The API may return multiple conversation objects if recipients are in different contexts
316
for conversation in conversations:
317
    print(f"Created conversation {conversation.id} with {len(conversation.participants)} participants")
318

319
# Get all conversations for current user
320
all_conversations = canvas.get_conversations(
321
    scope='unread',
322
    include=['participant_avatars']
323
)
324

325
for conv in all_conversations:
326
    print(f"Unread conversation: {conv.subject} from {conv.last_authored_message_at}")
327
```
328

329
### Managing Conversation Operations
330

331
```python
332
# Get a specific conversation and add a reply
333
conversation = canvas.get_conversation(12345)
334

335
# Add a message to the conversation
336
updated_conv = conversation.add_message(
337
    body="Thanks for the question! Here's the clarification you requested...",
338
    attachment_ids=[file1.id, file2.id]
339
)
340

341
# Add more recipients to the conversation
342
conversation.add_recipients(['new_user_123', 'another_user_456'])
343

344
# Mark conversation as starred and read
345
conversation.edit(
346
    conversation={
347
        'starred': True,
348
        'workflow_state': 'read'
349
    }
350
)
351

352
# Batch operations on multiple conversations
353
conversation_ids = [conv.id for conv in all_conversations[:5]]
354
progress = canvas.conversations_batch_update(
355
    conversation_ids=conversation_ids,
356
    event='mark_as_read'
357
)
358

359
# Monitor the batch operation progress
360
print(f"Batch operation status: {progress.workflow_state}")
361
```
362

363
### Working with Announcements
364

365
```python
366
# Get announcements from multiple courses
367
course_codes = ['course_123', 'course_456', 'course_789']
368
announcements = canvas.get_announcements(
369
    context_codes=course_codes,
370
    active_only=True,
371
    start_date='2024-01-01',
372
    end_date='2024-12-31'
373
)
374

375
for announcement in announcements:
376
    print(f"Announcement: {announcement.title}")
377
    print(f"Posted: {announcement.posted_at}")
378
    print(f"Course: {announcement.context_code}")
379
    print("---")
380

381
# Create an announcement in a course
382
course = canvas.get_course(12345)
383
announcement = course.create_discussion_topic(
384
    title="Week 5 Assignment Reminder",
385
    message="<p>Don't forget that your research papers are due this Friday at 11:59 PM.</p><p>Please submit them via Canvas.</p>",
386
    is_announcement=True,
387
    published=True,
388
    delayed_post_at=None  # Post immediately
389
)
390
```
391

392
### Advanced Discussion Management
393

394
```python
395
# Get a discussion topic and manage it
396
course = canvas.get_course(12345)
397
discussions = course.get_discussion_topics(
398
    order_by='recent_activity',
399
    include=['all_dates', 'sections']
400
)
401

402
for discussion in discussions:
403
    print(f"Discussion: {discussion.title}")
404
    
405
    # Get entries (posts) in the discussion
406
    entries = discussion.get_entries()
407
    
408
    for entry in entries:
409
        print(f"  Post by User {entry.user_id}: {entry.message[:100]}...")
410
        
411
        # Reply to an entry
412
        if entry.user_id != current_user.id:  # Don't reply to own posts
413
            reply = discussion.post_entry(
414
                message="Thanks for sharing your perspective!",
415
                parent_id=entry.id
416
            )
417
    
418
    # Subscribe to discussion notifications
419
    discussion.subscribe()
420

421
# Create a graded discussion
422
graded_discussion = course.create_discussion_topic(
423
    title="Week 3 Case Study Discussion",
424
    message="Analyze the case study and provide your recommendations...",
425
    discussion_type='threaded',
426
    published=True,
427
    require_initial_post=True,
428
    assignment={
429
        'name': 'Case Study Discussion',
430
        'points_possible': 25,
431
        'due_at': '2024-12-01T23:59:59Z',
432
        'grading_type': 'points'
433
    }
434
)
435
```
436

437
### Communication Channel Management
438

439
```python
440
# Get current user and manage communication channels
441
current_user = canvas.get_current_user()
442

443
# List existing communication channels
444
channels = current_user.get_communication_channels()
445
for channel in channels:
446
    print(f"Channel: {channel.address} ({channel.type}) - {channel.workflow_state}")
447

448
# Add a new email communication channel
449
new_channel = current_user.create_communication_channel({
450
    'address': 'alternate.email@example.com',
451
    'type': 'email'
452
})
453

454
# The new channel will need to be confirmed before it becomes active
455
print(f"Created channel {new_channel.id} - Status: {new_channel.workflow_state}")
456
```
457

458
### Monitoring Communication Activity
459

460
```python
461
# Get unread message count
462
unread_info = canvas.conversations_unread_count()
463
print(f"You have {unread_info['unread_count']} unread conversations")
464

465
# Get communication messages sent to a specific user (admin function)
466
user = canvas.get_user(12345)
467
comm_messages = canvas.get_comm_messages(
468
    user=user,
469
    start_time='2024-01-01T00:00:00Z',
470
    end_time='2024-12-31T23:59:59Z'
471
)
472

473
for message in comm_messages:
474
    print(f"Message sent: {message.created_at}")
475
    print(f"Subject: {message.subject}")
476
    print(f"Sent to: {message.to}")
477

478
# Check for running batch operations
479
running_batches = canvas.conversations_get_running_batches()
480
if running_batches:
481
    print("Active batch operations:")
482
    for batch in running_batches:
483
        print(f"  Batch {batch['id']}: {batch['workflow_state']}")
484
```