🔍 Code Extractor

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.

Purpose

The Call class provides a comprehensive interface for managing voice/video calls in Microsoft Teams/Skype for Business applications. It handles call lifecycle operations (reject, delete/hangup), media processing (cancel operations), recording status updates, muting controls, and provides access to call participants and operations. This class is used by bots and applications to programmatically control calls, manage IVR operations, and interact with call participants.

Source Code

class Call(Entity):
    """
    The call resource is created when there is an incoming call for the application or the application creates a
    new outgoing call via a POST on app/calls.
    """

    def cancel_media_processing(self, client_context=None):
        """
        Cancels processing for any in-progress media operations.

        Media operations refer to the IVR operations playPrompt and recordResponse, which are by default queued
        to process in order. The cancelMediaProcessing method cancels any operation that is in-process as well as
        operations that are queued. For example, this method can be used to clean up the IVR operation queue for
        a new media operation. However, it will not cancel a subscribeToTone operation because it operates independent
        of any operation queue.


        :param str client_context: The client context.
        """
        return_type = CancelMediaProcessingOperation(self.context)
        payload = {
            "clientContext": client_context,
        }
        qry = ServiceOperationQuery(
            self, "cancelMediaProcessing", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def reject(self, reason=None, callback_uri=None):
        """
        Enable a bot to reject an incoming call. The incoming call request can be an invite from a participant in
        a group call or a peer-to-peer call. If an invite to a group call is received, the notification will contain
        the chatInfo and meetingInfo parameters.

        The bot is expected to answer or reject the call before the call times out. The current timeout value is
        15 seconds.

        This API does not end existing calls that have already been answered. Use delete call to end a call.

        :param str reason: The rejection reason. Possible values are None, Busy and Forbidden
        :param str callback_uri: This allows bots to provide a specific callback URI for the current call to receive
            later notifications. If this property has not been set, the bot's global callback URI will be used instead.
            This must be https.
        """
        payload = {"reason": reason, "callbackUri": callback_uri}
        qry = ServiceOperationQuery(self, "reject", None, payload)
        self.context.add_query(qry)
        return self

    def delete(self):
        """
        Delete or hang up an active call. For group calls, this will only delete your call leg and the underlying
        group call will still continue."""
        return super(Call, self).delete_object()

    def update_recording_status(self, status, client_context):
        """
        Update the application's recording status associated with a call.
        This requires the use of the Teams policy-based recording solution.

        :param str status: The recording status. Possible values are: notRecording, recording, or failed.
        :param str client_context: Unique client context string. Max limit is 256 chars.
        """
        return_type = UpdateRecordingStatusOperation(self.context)
        payload = {"status": status, "clientContext": client_context}
        qry = ServiceOperationQuery(
            self, "updateRecordingStatus", None, payload, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def unmute(self, client_context):
        """
        Allow the application to unmute itself.

        This is a server unmute, meaning that the server will start sending audio packets for this participant
        to other participants again.

        :param str client_context: Unique Client Context string. Max limit is 256 chars.
        """
        return_type = UnmuteParticipantOperation(self.context)
        payload = {"clientContext": client_context}
        qry = ServiceOperationQuery(self, "unmute", None, payload, None, return_type)
        self.context.add_query(qry)
        return return_type

    @property
    def callback_uri(self):
        """The callback URL on which callbacks will be delivered. Must be https."""
        return self.properties.get("callbackUri", None)

    @property
    def call_routes(self):
        """The routing information on how the call was retargeted. Read-only."""
        return self.properties.get("callRoutes", ClientValueCollection(CallRoute))

    @property
    def incoming_context(self):
        """Call context associated with an incoming call."""
        return self.properties.get("incomingContext", IncomingContext())

    @property
    def participants(self):
        """
        Participant collection
        """
        return self.properties.get(
            "participants",
            EntityCollection(
                self.context,
                Participant,
                ResourcePath("participants", self.resource_path),
            ),
        )

    @property
    def operations(self):
        """
        CommsOperation collection
        """
        return self.properties.get(
            "operations",
            EntityCollection(
                self.context,
                CommsOperation,
                ResourcePath("operations", self.resource_path),
            ),
        )

Parameters

Parameter Details

context: Inherited from Entity base class - the client context object that manages API communication and query execution for this call resource

properties: Inherited from Entity base class - dictionary containing the call's properties and state data returned from the API

Return Value

Instantiation returns a Call object representing a specific call resource. Methods return various types: cancel_media_processing returns CancelMediaProcessingOperation, reject returns self (Call) for chaining, delete returns result from parent delete_object, update_recording_status returns UpdateRecordingStatusOperation, unmute returns UnmuteParticipantOperation. Properties return specific types like string (callback_uri), ClientValueCollection (call_routes), IncomingContext (incoming_context), or EntityCollection (participants, operations).

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.communications.calls.call import Call
from office365.communications.calls.incoming_context import IncomingContext
from office365.communications.calls.participant import Participant
from office365.communications.calls.route import CallRoute
from office365.communications.operations.cancel_media_processing import CancelMediaProcessingOperation
from office365.communications.operations.comms import CommsOperation
from office365.communications.operations.unmute_participant import UnmuteParticipantOperation
from office365.communications.operations.update_recording_status import UpdateRecordingStatusOperation
from office365.entity import Entity
from office365.entity_collection import EntityCollection
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.paths.resource_path import ResourcePath
from office365.runtime.queries.service_operation import ServiceOperationQuery

Usage Example

# Assuming you have a GraphClient instance and a call_id
from office365.graph_client import GraphClient

# Initialize client with credentials
client = GraphClient.with_client_secret(tenant_id, client_id, client_secret)

# Get an existing call
call = client.communications.calls[call_id].get().execute_query()

# Reject an incoming call
call.reject(reason='Busy', callback_uri='https://myapp.com/callback')
client.execute_query()

# Cancel any in-progress media operations
cancel_op = call.cancel_media_processing(client_context='operation-123')
client.execute_query()

# Update recording status
recording_op = call.update_recording_status(status='recording', client_context='rec-456')
client.execute_query()

# Unmute the application
unmute_op = call.unmute(client_context='unmute-789')
client.execute_query()

# Access participants
participants = call.participants.get().execute_query()
for participant in participants:
    print(participant.info.identity.user.display_name)

# Delete/hang up the call
call.delete()
client.execute_query()

Best Practices

• Always call execute_query() on the context after queuing operations to actually execute them against the API
• For incoming calls, respond with answer or reject within 15 seconds to avoid timeout
• Use client_context parameters (max 256 chars) to track operations and correlate with callbacks
• Callback URIs must use HTTPS protocol for security
• The delete() method only removes your application's call leg in group calls; the group call continues for other participants
• cancelMediaProcessing affects playPrompt and recordResponse operations but not subscribeToTone operations
• Recording operations require Teams policy-based recording solution to be properly configured
• Access nested collections (participants, operations) through properties which return EntityCollection objects
• Chain operations by queuing multiple queries before calling execute_query() for better performance
• Handle the returned operation objects (CancelMediaProcessingOperation, UpdateRecordingStatusOperation, etc.) to track operation status

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class CallCollection 77.0% similar

  CallCollection is a specialized entity collection class for managing Microsoft Teams/Graph API call operations, including creating outgoing calls and logging teleconferencing device quality data.

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

• class CallRecord 70.1% similar

  Represents a single peer-to-peer call or a group call between multiple participants in Microsoft 365, sometimes referred to as an online meeting.

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

• class CloudCommunications 66.2% similar

  CloudCommunications is a class that provides access to Microsoft Graph API cloud communications resources including calls, call records, online meetings, and user presence information.

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

• class Participant 63.2% similar

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

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

• class CallOptions 57.8% similar

  A data class that encapsulates optional configuration features for Microsoft Teams/Office 365 call functionality, specifically controlling bot visibility after escalation and content sharing notifications.

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