🔍 Code Extractor

Represents a participant in a call, providing methods to manage participant state including inviting others, controlling hold music, and accessing participant information.

Purpose

This class extends Entity to model a call participant in the Microsoft Graph Communications API. It provides operations to invite additional participants to an active call, put participants on hold with music, remove participants from hold, and access participant metadata. The class follows a query-based pattern where operations are added to a context queue for execution.

Source Code

class Participant(Entity):
    """Represents a participant in a call."""

    def invite(self, participants, client_context):
        """Invite participants to the active call.

        :param list[InvitationParticipantInfo] participants: Unique Client Context string. Max limit is 256 chars.
        :param str client_context: Unique Client Context string. Max limit is 256 chars.
        """
        return_type = InviteParticipantsOperation(self.context)
        payload = {
            "participants": ClientValueCollection(
                InvitationParticipantInfo, participants
            ),
            "clientContext": client_context,
        }
        qry = ServiceOperationQuery(self, "invite", None, payload, None, return_type)
        self.context.add_query(qry)
        return return_type

    def start_hold_music(self, custom_prompt=None, client_context=None):
        """
        Put a participant on hold and play music in the background.

        :param str or None custom_prompt: Audio prompt the participant will hear when placed on hold.
        :param str or None client_context: Unique client context string. Can have a maximum of 256 characters.
        """
        return_type = StartHoldMusicOperation(self.context)
        payload = {"customPrompt": custom_prompt, "clientContext": client_context}
        qry = ServiceOperationQuery(
            self, "startHoldMusic", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def stop_hold_music(self, client_context=None):
        """
        Reincorporate a participant previously put on hold to the call.

        :param str or None client_context: Unique client context string. Can have a maximum of 256 characters.
        """
        return_type = StopHoldMusicOperation(self.context)
        payload = {"clientContext": client_context}
        qry = ServiceOperationQuery(
            self, "stopHoldMusic", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    @property
    def info(self):
        """Information about the participant."""
        return self.properties.get("info", ParticipantInfo())

    @property
    def metadata(self):
        """
        A blob of data provided by the participant in the roster.

        :rtype: str
        """
        return self.properties.get("metadata", None)

Parameters

Parameter Details

context: Inherited from Entity base class. The execution context that manages queries and operations for this participant instance. Required for all service operations.

Return Value

Instantiation returns a Participant object that represents a single call participant. Methods return operation objects (InviteParticipantsOperation, StartHoldMusicOperation, StopHoldMusicOperation) that can be used to track the status of asynchronous operations. Properties return participant data: 'info' returns a ParticipantInfo object, 'metadata' returns a string or None.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.communications.calls.participant import Participant
from office365.communications.calls.invitation_participant_info import InvitationParticipantInfo
from office365.communications.calls.participant_info import ParticipantInfo
from office365.communications.operations.invite_participants import InviteParticipantsOperation
from office365.communications.operations.start_hold_music import StartHoldMusicOperation
from office365.communications.operations.stop_hold_music import StopHoldMusicOperation
from office365.entity import Entity
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.queries.service_operation import ServiceOperationQuery

Usage Example

# Assuming you have an authenticated context and existing participant object
# participant = call.participants.get_by_id('participant_id')

# Invite additional participants to the call
from office365.communications.calls.invitation_participant_info import InvitationParticipantInfo

new_participants = [
    InvitationParticipantInfo(identity={'user': {'id': 'user-id-1'}}),
    InvitationParticipantInfo(identity={'user': {'id': 'user-id-2'}})
]
invite_op = participant.invite(new_participants, client_context='invite-context-123')

# Put participant on hold with custom music
hold_op = participant.start_hold_music(
    custom_prompt='https://example.com/hold-music.mp3',
    client_context='hold-context-456'
)

# Remove participant from hold
unhold_op = participant.stop_hold_music(client_context='unhold-context-789')

# Access participant information
participant_info = participant.info
participant_metadata = participant.metadata

# Execute queued operations
context.execute_query()

Best Practices

• Always provide a unique client_context string (max 256 characters) for tracking operations and debugging
• Operations are queued in the context and not executed immediately - call context.execute_query() to execute
• Check operation status after execution to ensure success before proceeding with dependent operations
• The participant object must be associated with an active call before invoking operations
• When inviting participants, ensure InvitationParticipantInfo objects are properly constructed with valid identity information
• Custom prompts for hold music should be accessible URLs pointing to valid audio files
• Handle exceptions that may occur during context.execute_query() as network or permission issues can cause failures
• Properties (info, metadata) access the internal properties dictionary and may return default values if not populated
• This class follows the Entity pattern and inherits context management from the base class

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class InvitationParticipantInfo 70.6% similar

  A data class representing an entity being invited to a group call, containing participant identification, visibility settings, and call routing configuration.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/calls/invitation_participant_info.py

• class InviteParticipantsOperation 64.2% similar

  Represents the status of a long-running participant invitation operation triggered by a call to the participant-invite API in Microsoft Graph Communications.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/operations/invite_participants.py

• class Call 63.2% similar

  Represents a call resource in Microsoft Graph Communications API, managing both incoming and outgoing calls for applications with capabilities for call control, media operations, and participant management.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/calls/call.py

• class MeetingParticipants 62.1% similar

  A data class representing participants in a meeting, including an organizer and a collection of attendees.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/onlinemeetings/participants.py

• class StopHoldMusicOperation 61.9% similar

  A class representing the status of a stopHoldMusic operation in Microsoft 365 communications, used to track the result of stopping hold music during a call.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/communications/operations/stop_hold_music.py