Steuern und Weiterleiten von Anrufen mit der Anrufautomatisierung

Artikel
07/25/2024

Die Anrufautomatisierung verwendet eine REST-API-Schnittstelle, um Anforderungen für Aktionen zu empfangen und Antworten bereitzustellen, um darüber zu informieren, ob die Anforderung erfolgreich übermittelt wurde. Da Anrufe asynchron erfolgen, verfügen die meisten Aktionen über entsprechende Ereignisse, die ausgelöst werden, wenn die Aktion erfolgreich oder mit Fehlern abgeschlossen wird. In diesem Leitfaden werden die verfügbaren Aktionen für die Steuerung von Anrufen behandelt, z. B. das Erstellen von Anrufen, die Übertragung, Umleitung und Verwaltung von Teilnehmenden. Die Aktionen werden mit Beispielcode zum Aufrufen der besagten Aktion und Sequenzdiagramme ergänzt, mit denen die nach dem Aufrufen einer Aktion erwarteten Ereignisse beschrieben werden. Diese Diagramme veranschaulichen die Programmierung Ihrer Dienstanwendung mit Anrufautomatisierung.

Die Anrufautomatisierung unterstützt verschiedene andere Aktionen zum Verwalten von Anrufmedien und Aufzeichnungen, die in anderen Leitfäden behandelt werden.

Als Voraussetzung wird empfohlen, diese Artikel zu lesen, um diesen Leitfaden optimal nutzen zu können:

Im Leitfaden mit Konzepten der Anrufautomatisierung werden das Programmiermodell für Aktionen und Ereignisse sowie Ereignisrückrufe beschrieben.
Erfahren Sie mehr über Benutzerbezeichner wie CommunicationUserIdentifier und PhoneNumberIdentifier, die in diesem Leitfaden verwendet werden.

Für alle Codebeispiele ist client das CallAutomationClient-Objekt, das wie gezeigt erstellt werden kann, und callConnection ist das CallConnection-Objekt, das aus der Antwort oder der CreateCall-Antwort abgerufen wird. Sie können es auch aus Rückrufereignissen abrufen, die von Ihrer Anwendung empfangen wurden.

var client = new CallAutomationClient("<resource_connection_string>");

 CallAutomationClient client = new CallAutomationClientBuilder().connectionString("<resource_connection_string>").buildClient();

const client = new CallAutomationClient("<resource_connection_string>");

call_automation_client = CallAutomationClient.from_connection_string("<resource_connection_string>")

Ausführen eines ausgehenden Anrufs

Sie können einen 1:1- oder Gruppenanruf mit Kommunikationsbenutzer*innen oder Telefonnummern (öffentliche oder Communication Services-Nummer) tätigen. Beim Anrufen eines PSTN-Endpunkts müssen Sie auch eine Telefonnummer angeben, die als Quellanrufer-ID verwendet und in der Anrufbenachrichtigung für den PSTN-Zielendpunkt angezeigt wird. Um Communication Services-Benutzer anzurufen, müssen Sie anstelle von „PhoneNumberIdentifier“ ein CommunicationUserIdentifier-Objekt bereitstellen.

Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events 
var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the Azure Communication Services provisioned phone number for the caller  
var callThisPerson = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber); // person to call
CreateCallResult response = await client.CreateCallAsync(callThisPerson, callbackUri);

String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
PhoneNumberIdentifier callerIdNumber = new PhoneNumberIdentifier("+18001234567"); // This is the Azure Communication Services provisioned phone number for the caller  
CallInvite callInvite = new CallInvite(new PhoneNumberIdentifier("+16471234567"), callerIdNumber); // person to call
CreateCallResult response = client.createCall(callInvite, callbackUri).block();

const callInvite = {
    targetParticipant: { phoneNumber: "+18008008800" }, // person to call
    sourceCallIdNumber: { phoneNumber: "+18888888888" } // This is the Azure Communication Services provisioned phone number for the caller
};
const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
const response = await client.createCall(callInvite, callbackUri);

callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
caller_id_number = PhoneNumberIdentifier(
    "+18001234567"
)  # This is the Azure Communication Services provisioned phone number for the caller
call_invite = CallInvite(
    target=PhoneNumberIdentifier("+16471234567"),
    source_caller_id_number=caller_id_number,
)
call_connection_properties = client.create_call(call_invite, callback_uri)

Wenn Sie einen Gruppenanruf tätigen, der eine Telefonnummer enthält, müssen Sie eine Telefonnummer angeben, die als Anrufer-ID-Nummer für den PSTN-Endpunkt verwendet wird.

Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events 
var pstnEndpoint = new PhoneNumberIdentifier("+16041234567");
var voipEndpoint = new CommunicationUserIdentifier("<user_id_of_target>"); //user id looks like 8:a1b1c1-...
var groupCallOptions = new CreateGroupCallOptions(new List<CommunicationIdentifier>{ pstnEndpoint, voipEndpoint }, callbackUri)
{
    SourceCallerIdNumber = new PhoneNumberIdentifier("+16044561234"), // This is the Azure Communication Services provisioned phone number for the caller
};
CreateCallResult response = await client.CreateGroupCallAsync(groupCallOptions);

String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
PhoneNumberIdentifier callerIdNumber = new PhoneNumberIdentifier("+18001234567"); // This is the Azure Communication Services provisioned phone number for the caller
List<CommunicationIdentifier> targets = new ArrayList<>(Arrays.asList(new PhoneNumberIdentifier("+16471234567"), new CommunicationUserIdentifier("<user_id_of_target>")));
CreateGroupCallOptions groupCallOptions = new CreateGroupCallOptions(targets, callbackUri);
groupCallOptions.setSourceCallIdNumber(callerIdNumber);
Response<CreateCallResult> response = client.createGroupCallWithResponse(createGroupCallOptions).block();

const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
const participants = [
    { phoneNumber: "+18008008800" },
    { communicationUserId: "<user_id_of_target>" }, //user id looks like 8:a1b1c1-...
];
const createCallOptions = {
    sourceCallIdNumber: { phoneNumber: "+18888888888" }, // This is the Azure Communication Services provisioned phone number for the caller
};
const response = await client.createGroupCall(participants, callbackUri, createCallOptions);

callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
caller_id_number = PhoneNumberIdentifier(
    "+18888888888"
)  # This is the Azure Communication Services provisioned phone number for the caller
pstn_endpoint = PhoneNumberIdentifier("+18008008800")
voip_endpoint = CommunicationUserIdentifier(
    "<user_id_of_target>"
)  # user id looks like 8:a1b1c1-...
call_connection_properties = client.create_group_call(
    target_participants=[voip_endpoint, pstn_endpoint],
    callback_url=callback_uri,
    source_caller_id_number=caller_id_number,
)

Die Antwort enthält das CallConnection-Objekt, das Sie verwenden können, um weitere Aktionen für diesen Aufruf auszuführen, sobald eine Verbindung besteht. Wenn der Anruf entgegengenommen wird, werden für den Rückrufendpunkt, den Sie zuvor angegeben haben, zwei Ereignisse veröffentlicht:

Das CallConnected-Ereignis ist die Benachrichtigung, dass der Anruf mit der oder dem Angerufenen eingerichtet wurde.
Das ParticipantsUpdated-Ereignis enthält die aktuelle Liste der Teilnehmenden am Anruf.

Falls der Anruf fehlschlägt, erhalten Sie die Ereignisse CallDisconnected und CreateCallFailed mit Fehlercodes zur weiteren Problembehandlung (weitere Informationen zu Fehlercodes der Anrufautomatisierung finden Sie auf dieser Seite).

Herstellen einer Verbindung mit einem Anruf (Vorschau)

Die Verbindungsaktion ermöglicht es Ihrem Dienst, eine Verbindung mit einem laufenden Anruf herzustellen und Aktionen dafür auszuführen. Das ist hilfreich, wenn Sie einen Raumanruf verwalten möchten oder wenn von Clientanwendungen ein 1:1-Anruf oder ein Gruppenanruf gestartet wurde, an dem die Anrufautomatisierung nicht beteiligt ist. Die Verbindung wird unter Verwendung der CallLocator-Eigenschaft hergestellt. Folgende Arten von Verbindungen sind möglich: „ServerCallLocator“, „GroupCallLocator“ und „RoomCallLocator“. Diese IDs sind bei der ursprünglichen Anrufeinrichtung oder bei der Raumerstellung verfügbar. Außerdem werden sie im Rahmen des CallStarted-Ereignisses veröffentlicht.

Wenn Sie eine Verbindung mit einem beliebigen 1:1- oder Gruppenanruf herstellen möchten, verwenden Sie das ServerCallLocator-Element. Wenn Sie einen Anruf mit „GroupCallId“ gestartet haben, können Sie auch „GroupCallLocator“ verwenden.

Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events
CallLocator serverCallLocator = new ServerCallLocator("<ServerCallId>");
ConnectCallResult response = await client.ConnectCallAsync(serverCallLocator, callbackUri);

String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
CallLocator serverCallLocator =  new ServerCallLocator("<ServerCallId>");
ConnectCallResult response = client.connectCall(serverCallLocator, callbackUri).block();

const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
const serverCallLocator = { kind: "serverCallLocator", id: "<serverCallId>" };
const response = await client.connectCall(serverCallLocator, callbackUri);

callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
server_call_locator = ServerCallLocator("<server_call_id>")
call_connection_properties = client.connect_call(call_locator=server_call_locator, callback_url=callback_uri)

Wenn Sie eine Verbindung mit einem Raumanruf herstellen möchten, verwenden Sie „RoomCallLocator“ mit der Raum-ID (RoomId). Erfahren Sie mehr über Räume und wie die API für die Anrufautomatisierung verwendet werden kann, um laufende Raumanrufe zu verwalten.

Uri callbackUri = new Uri("https://<myendpoint>/Events"); //the callback endpoint where you want to receive subsequent events
CallLocator roomCallLocator = new RoomCallLocator("<RoomId>");
ConnectCallResult response = await client.ConnectCallAsync(roomCallLocator, callbackUri);

String callbackUri = "https://<myendpoint>/Events"; //the callback endpoint where you want to receive subsequent events
CallLocator roomCallLocator =  new RoomCallLocator("<RoomId>");
ConnectCallResult response = client.connectCall(roomCallLocator, callbackUri).block();

const roomCallLocator = { kind: "roomCallLocator", id: "<RoomId>" };
const callbackUri = "https://<myendpoint>/Events"; // the callback endpoint where you want to receive subsequent events 
const response = await client.connectCall(roomCallLocator, callbackUri);

callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
room_call_locator = RoomCallLocator("<room_id>")
call_connection_properties = client.connect_call(call_locator=room_call_locator, callback_url=callback_uri)

Bei einer erfolgreichen Antwort wird das CallConnection-Objekt bereitgestellt, das Sie verwenden können, um weitere Aktionen für diesen Anruf auszuführen. Für den Rückrufendpunkt, den Sie zuvor angegeben haben, werden zwei Ereignisse veröffentlicht:

CallConnected-Ereignis, das angibt, dass Sie erfolgreich eine Verbindung mit dem Anruf hergestellt haben.
Das ParticipantsUpdated-Ereignis enthält die aktuelle Liste der Teilnehmenden am Anruf.

Wenn Ihr Dienst nach erfolgreicher Verbindungsherstellung von diesem Anruf getrennt wird, werden Sie über ein CallDisconected-Ereignis darüber informiert. Falls gar nicht erst eine Verbindung mit dem Anruf hergestellt werden konnte, tritt ein ConnectFailed-Ereignis auf.

Sequenzdiagramm: Herstellen einer Verbindung mit einem Anruf

Annehmen eines eingehenden Anrufs

Nachdem Sie den Empfang von Benachrichtigungen über eingehende Anrufe für Ihre Ressource abonniert haben, nehmen Sie einen eingehenden Anruf entgegen. Wenn Sie einen Anruf annehmen, müssen Sie eine Rückruf-URL angeben. Communication Services sendet alle nachfolgenden Ereignisse zu diesem Anruf an diese URL.

string incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>"; 
Uri callBackUri = new Uri("https://<myendpoint_where_I_want_to_receive_callback_events"); 

var answerCallOptions = new AnswerCallOptions(incomingCallContext, callBackUri);  
AnswerCallResult answerResponse = await client.AnswerCallAsync(answerCallOptions);
CallConnection callConnection = answerResponse.CallConnection;

String incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>";
String callbackUri = "https://<myendpoint>/Events"; 
 
AnswerCallOptions answerCallOptions = new AnswerCallOptions(incomingCallContext, callbackUri); 
Response<AnswerCallResult> response = client.answerCallWithResponse(answerCallOptions).block();

const incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>";
const callbackUri = "https://<myendpoint>/Events";

const { callConnection } = await client.answerCall(incomingCallContext, callbackUri);

incoming_call_context = "<IncomingCallContext_From_IncomingCall_Event>"
callback_uri = "https://<myendpoint>/Events"  # the callback endpoint where you want to receive subsequent events
call_connection_properties = client.answer_call(
    incoming_call_context=incoming_call_context, callback_url=callback_uri
)

Das CallConnected-Ereignis ist die Benachrichtigung, dass der Anruf mit der oder dem Anrufer*in eingerichtet wurde.
Das ParticipantsUpdated-Ereignis enthält die aktuelle Liste der Teilnehmenden am Anruf.

Sequenzdiagramm für die Beantwortung eines eingehenden Anrufs

Ablehnen eines Anrufs

Sie können einen eingehenden Anruf wie unten gezeigt ablehnen. Sie können einen Ablehnungsgrund angeben: keiner, besetzt oder gesperrt. Wenn keine Angabe erfolgt, wird standardmäßig „keiner“ ausgewählt.

string incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>"; 
var rejectOption = new RejectCallOptions(incomingCallContext); 
rejectOption.CallRejectReason = CallRejectReason.Forbidden; 
_ = await client.RejectCallAsync(rejectOption);

String incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>";  
RejectCallOptions rejectCallOptions = new RejectCallOptions(incomingCallContext) 
        .setCallRejectReason(CallRejectReason.BUSY); 
Response<Void> response = client.rejectCallWithResponse(rejectCallOptions).block();

const incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>";
const rejectOptions = {
    callRejectReason: KnownCallRejectReason.Forbidden,
};
await client.rejectCall(incomingCallContext, rejectOptions);

incoming_call_context = "<IncomingCallContext_From_IncomingCall_Event>"
client.reject_call(
    incoming_call_context=incoming_call_context,
    call_reject_reason=CallRejectReason.FORBIDDEN,
)

Für Ablehnungsaktionen werden keine Ereignisse veröffentlicht.

Umleiten eines Anrufs

Sie können einen eingehenden Anruf an einen anderen Endpunkt umleiten, ohne ihn entgegenzunehmen. Wenn ein Anruf umgeleitet wird, kann er nicht mehr von Ihrer Anwendung über die Anrufautomatisierung gesteuert werden.

string incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>"; 
var target = new CallInvite(new CommunicationUserIdentifier("<user_id_of_target>")); //user id looks like 8:a1b1c1-... 
_ = await client.RedirectCallAsync(incomingCallContext, target);

String incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>"; 
CallInvite target = new CallInvite(new CommunicationUserIdentifier("<user_id_of_target>")); //user id looks like 8:a1b1c1-... 
RedirectCallOptions redirectCallOptions = new RedirectCallOptions(incomingCallContext, target); 
Response<Void> response = client.redirectCallWithResponse(redirectCallOptions).block();

const incomingCallContext = "<IncomingCallContext_From_IncomingCall_Event>";
const target = { targetParticipant: { communicationUserId: "<user_id_of_target>" } }; //user id looks like 8:a1b1c1-...
await client.redirectCall(incomingCallContext, target);

incoming_call_context = "<IncomingCallContext_From_IncomingCall_Event>"
call_invite = CallInvite(
    CommunicationUserIdentifier("<user_id_of_target>")
  )  # user id looks like 8:a1b1c1-...
client.redirect_call(
    incoming_call_context=incoming_call_context, target_participant=call_invite
)

Wenn Sie den Anruf an eine Telefonnummer umleiten möchten, konstruieren Sie das Ziel und die Anrufer-ID mithilfe von „PhoneNumberIdentifier“.

var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the Azure Communication Services provisioned phone number for the caller
var target = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);

PhoneNumberIdentifier callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the Azure Communication Services provisioned phone number for the caller
CallInvite target = new CallInvite(new PhoneNumberIdentifier("+18001234567"), callerIdNumber);

const callerIdNumber = { phoneNumber: "+16044561234" };
const target = {
    targetParticipant: { phoneNumber: "+16041234567" }, 
    sourceCallIdNumber: callerIdNumber,
};

caller_id_number = PhoneNumberIdentifier(
    "+18888888888"
)  # This is the Azure Communication Services provisioned phone number for the caller
call_invite = CallInvite(
    target=PhoneNumberIdentifier("+16471234567"),
    source_caller_id_number=caller_id_number,
)

Für Umleitungsaktionen werden keine Ereignisse veröffentlicht. Wenn es sich bei dem Ziel um einen Communication Services-Benutzer oder um eine Telefonnummer handelt, die Ihrer Ressource gehören, wird ein neues IncomingCall-Ereignis generiert, dessen Feld „to“ auf das von Ihnen angegebene Ziel festgelegt ist.

Durchstellen eines Anrufteilnehmers

Wenn Ihre Anwendung einen Anruf annimmt oder einen ausgehenden Anruf an einen Endpunkt tätigt, kann dieser Endpunkt an einen anderen Zielendpunkt durchgestellt werden. Wenn ein 1:1-Anruf durchgestellt wird, wird Ihre Anwendung aus dem Anruf entfernt und kann somit den Anruf nicht mehr über die Anrufautomatisierung steuern. Die Anrufeinladung für das Ziel enthält die Anrufer-ID des Endpunkts, der durchgestellt wird. Die Angabe einer benutzerdefinierten Anrufer-ID wird nicht unterstützt.

var transferDestination = new CommunicationUserIdentifier("<user_id>"); 
var transferOption = new TransferToParticipantOptions(transferDestination) {
    OperationContext = "<Your_context>",
    OperationCallbackUri = new Uri("<uri_endpoint>") // Sending event to a non-default endpoint.
};
// adding customCallingContext
transferOption.CustomCallingContext.AddVoip("customVoipHeader1", "customVoipHeaderValue1");
transferOption.CustomCallingContext.AddVoip("customVoipHeader2", "customVoipHeaderValue2");

TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption);

CommunicationIdentifier transferDestination = new CommunicationUserIdentifier("<user_id>");
TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination)
                .setOperationContext("<operation_context>")
                .setOperationCallbackUrl("<url_endpoint>"); // Sending event to a non-default endpoint.
// set customCallingContext
options.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");

Response<TransferCallResult> transferResponse = callConnectionAsync.transferToParticipantCallWithResponse(options).block();

const transferDestination = { communicationUserId: "<user_id>" };
const options = { operationContext: "<Your_context>", operationCallbackUrl: "<url_endpoint>" };
// adding customCallingContext
const customCallingContext: CustomCallingContext = [];
customCallingContext.push({ kind: "voip", key: "customVoipHeader1", value: "customVoipHeaderValue1" })
options.customCallingContext = customCallingContext;

const result = await callConnection.transferCallToParticipant(transferDestination, options);

transfer_destination = CommunicationUserIdentifier("<user_id>")
call_connection_client = call_automation_client.get_call_connection("<call_connection_id_from_ongoing_call>")
# set custom context
voip_headers = {"customVoipHeader1", "customVoipHeaderValue1"}

result = call_connection_client.transfer_call_to_participant(
    target_participant=transfer_destination,
    voip_headers=voip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

Wenn Ihre Anwendung einen Gruppenanruf entgegennimmt, einen ausgehenden Gruppenanruf an einen Endpunkt tätigt oder einen Teilnehmer zu einem 1:1-Anruf hinzugefügt hat, kann ein Endpunkt aus dem Anruf an einen anderen Zielendpunkt durchgestellt werden (mit Ausnahme des Endpunkts für die Anrufautomatisierung). Wenn ein Teilnehmer in einem Gruppenanruf durchgestellt wird, wird dadurch der Endpunkt entfernt, der aus dem Anruf durchgestellt wird. Die Anrufeinladung für das Ziel enthält die Anrufer-ID des Endpunkts, der durchgestellt wird. Die Angabe einer benutzerdefinierten Anrufer-ID wird nicht unterstützt.

// Transfer User
var transferDestination = new CommunicationUserIdentifier("<user_id>");
var transferee = new CommunicationUserIdentifier("<transferee_user_id>"); 
var transferOption = new TransferToParticipantOptions(transferDestination);
transferOption.Transferee = transferee;

// adding customCallingContext
transferOption.CustomCallingContext.AddVoip("customVoipHeader1", "customVoipHeaderValue1");
transferOption.CustomCallingContext.AddVoip("customVoipHeader2", "customVoipHeaderValue2");

transferOption.OperationContext = "<Your_context>";
transferOption.OperationCallbackUri = new Uri("<uri_endpoint>");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption);

// Transfer PSTN User
var transferDestination = new PhoneNumberIdentifier("<target_phoneNumber>");
var transferee = new PhoneNumberIdentifier("<transferee_phoneNumber>"); 
var transferOption = new TransferToParticipantOptions(transferDestination);
transferOption.Transferee = transferee;

// adding customCallingContext
transferOption.CustomCallingContext.AddSipUui("uuivalue");
transferOption.CustomCallingContext.AddSipX("header1", "headerValue");

transferOption.OperationContext = "<Your_context>";

// Sending event to a non-default endpoint.
transferOption.OperationCallbackUri = new Uri("<uri_endpoint>");

TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption);

// Transfer User
CommunicationIdentifier transferDestination = new CommunicationUserIdentifier("<user_id>");
CommunicationIdentifier transferee = new CommunicationUserIdentifier("<transferee_user_id>"); 
TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination);
options.setTransferee(transferee);
options.setOperationContext("<Your_context>");
options.setOperationCallbackUrl("<url_endpoint>");

// set customCallingContext
options.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");

Response<TransferCallResult> transferResponse = callConnectionAsync.transferToParticipantCallWithResponse(options).block();

// Transfer Pstn User
CommunicationIdentifier transferDestination = new PhoneNumberIdentifier("<taget_phoneNumber>");
CommunicationIdentifier transferee = new PhoneNumberIdentifier("<transferee_phoneNumber>"); 
TransferCallToParticipantOptions options = new TransferCallToParticipantOptions(transferDestination);
options.setTransferee(transferee);
options.setOperationContext("<Your_context>");
options.setOperationCallbackUrl("<url_endpoint>");

// set customCallingContext
options.getCustomCallingContext().addSipUui("UUIvalue");
options.getCustomCallingContext().addSipX("sipHeaderName", "value");

Response<TransferCallResult> transferResponse = callConnectionAsync.transferToParticipantCallWithResponse(options).block();

// Transfer User
const transferDestination = { communicationUserId: "<user_id>" };
const transferee = { communicationUserId: "<transferee_user_id>" };
const options = { transferee: transferee, operationContext: "<Your_context>", operationCallbackUrl: "<url_endpoint>" };

// adding customCallingContext
const customCallingContext: CustomCallingContext = [];
customContext.push({ kind: "voip", key: "customVoipHeader1", value: "customVoipHeaderValue1" })
options.customCallingContext = customCallingContext;

const result = await callConnection.transferCallToParticipant(transferDestination, options);

// Transfer pstn User
const transferDestination = { phoneNumber: "<taget_phoneNumber>" };
const transferee = { phoneNumber: "<transferee_phoneNumber>" };
const options = { transferee: transferee, operationContext: "<Your_context>", operationCallbackUrl: "<url_endpoint>" };

// adding customCallingContext
const customCallingContext: CustomCallingContext = [];
customContext.push({ kind: "sipuui", key: "", value: "uuivalue" });
customContext.push({ kind: "sipx", key: "headerName", value: "headerValue" })
options.customCallingContext = customCallingContext;

const result = await callConnection.transferCallToParticipant(transferDestination, options);

# Transfer to user
transfer_destination = CommunicationUserIdentifier("<user_id>")
transferee = CommnunicationUserIdentifer("transferee_user_id")
call_connection_client = call_automation_client.get_call_connection("<call_connection_id_from_ongoing_call>")

# create custom context
voip_headers = {"customVoipHeader1", "customVoipHeaderValue1"}

result = call_connection_client.transfer_call_to_participant(
    target_participant=transfer_destination,
    transferee=transferee,
    voip_headers=voip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

# Transfer to PSTN user
transfer_destination = PhoneNumberIdentifer("<target_phoneNumber>")
transferee = PhoneNumberIdentifer("transferee_phoneNumber")

# create custom context
sip_headers={}
sip_headers.add("X-MS-Custom-headerName", "headerValue")
sip_headers.add("User-To-User","uuivale")

call_connection_client = call_automation_client.get_call_connection("<call_connection_id_from_ongoing_call>")
result = call_connection_client.transfer_call_to_participant(
    target_participant=transfer_destination,
    transferee=transferee,
    sip_headers=sip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

Das Sequenzdiagramm zeigt den erwarteten Ablauf, wenn Ihre Anwendung einen ausgehenden Anruf tätigt und ihn dann an einen anderen Endpunkt durchstellt.

Sequenzdiagramm eines 1:1-Aufrufs mit anschließendem Durchstellen

Hinzufügen eines Teilnehmers zu einem Anruf

Sie können einem bereits vorhandenen Anruf einen Teilnehmer (Communication Services-Benutzer oder Telefonnummer) hinzufügen. Beim Hinzufügen einer Telefonnummer muss zwingend eine Anrufer-ID angegeben werden. Diese Anrufer-ID wird den hinzugefügten Teilnehmenden in der Anrufbenachrichtigung angezeigt.

// Add user
var addThisPerson = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
// add custom calling context
addThisPerson.CustomCallingContext.AddVoip("myHeader", "myValue");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);

// Add PSTN user
var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the Azure Communication Services provisioned phone number for the caller
var addThisPerson = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);
// add custom calling context
addThisPerson.CustomCallingContext.AddSipUui("value");
addThisPerson.CustomCallingContext.AddSipX("header1", "customSipHeaderValue1");

// Use option bag to set optional parameters
var addParticipantOptions = new AddParticipantOptions(new CallInvite(addThisPerson))
{
    InvitationTimeoutInSeconds = 60,
    OperationContext = "operationContext",
    OperationCallbackUri = new Uri("uri_endpoint"); // Sending event to a non-default endpoint.
};

AddParticipantsResult result = await callConnection.AddParticipantAsync(addParticipantOptions);

// Add user
CallInvite callInvite = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
// add custom calling context
callInvite.getCustomCallingContext().addVoip("voipHeaderName", "voipHeaderValue");
AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite)
                .setOperationContext("<operation_context>")
                .setOperationCallbackUrl("<url_endpoint>");
Response<AddParticipantResult> addParticipantResultResponse = callConnectionAsync.addParticipantWithResponse(addParticipantOptions).block();

// Add PSTN user
PhoneNumberIdentifier callerIdNumber = new PhoneNumberIdentifier("+16044561234"); // This is the Azure Communication Services provisioned phone number for the caller
CallInvite callInvite = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);
// add custom calling context
callInvite.getCustomCallingContext().addSipUui("value");
callInvite.getCustomCallingContext().addSipX("header1", "customSipHeaderValue1");
AddParticipantOptions addParticipantOptions = new AddParticipantOptions(callInvite)
                .setOperationContext("<operation_context>")
                .setOperationCallbackUrl("<url_endpoint>");
Response<AddParticipantResult> addParticipantResultResponse = callConnectionAsync.addParticipantWithResponse(addParticipantOptions).block();

// Add user
// add custom calling context
const customCallingContext: CustomCallingContext = [];
customContext.push({ kind: "voip", key: "voipHeaderName", value: "voipHeaderValue" })

const addThisPerson = {
    targetParticipant: { communicationUserId: "<acs_user_id>" },
    customCallingContext: customCallingContext,
};
const addParticipantResult = await callConnection.addParticipant(addThisPerson, {
            operationCallbackUrl: "<url_endpoint>",
            operationContext: "<operation_context>"
});

// Add PSTN user
const callerIdNumber = { phoneNumber: "+16044561234" }; // This is the Azure Communication Services provisioned phone number for the caller
// add custom calling context
const customCallingContext: CustomCallingContext = [];
customContext.push({ kind: "sipuui", key: "", value: "value" });
customContext.push({ kind: "sipx", key: "headerName", value: "headerValue" })
const addThisPerson = {
    targetParticipant: { phoneNumber: "+16041234567" }, 
    sourceCallIdNumber: callerIdNumber,
    customCallingContext: customCallingContext,
};
const addParticipantResult = await callConnection.addParticipant(addThisPerson, {
            operationCallbackUrl: "<url_endpoint>",
            operationContext: "<operation_context>"
});

# Add user
voip_headers = {"voipHeaderName", "voipHeaderValue"}
target = CommunicationUserIdentifier("<acs_user_id>")

call_connection_client = call_automation_client.get_call_connection(
    "<call_connection_id_from_ongoing_call>"
)
result = call_connection_client.add_participant(
    target,
    voip_headers=voip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>"
)

# Add PSTN user
caller_id_number = PhoneNumberIdentifier(
    "+18888888888"
) # This is the Azure Communication Services provisioned phone number for the caller
sip_headers = {}
sip_headers["User-To-User"] = "value"
sip_headers["X-MS-Custom-headerName"] = "headerValue"
target = PhoneNumberIdentifier("+18008008800"),

call_connection_client = call_automation_client.get_call_connection(
    "<call_connection_id_from_ongoing_call>"
)
result = call_connection_client.add_participant(
    target,
    sip_headers=sip_headers,
    opration_context="Your context",
    operationCallbackUrl="<url_endpoint>",
    source_caller_id_number=caller_id_number
)

Um Communication Services-Benutzer*innen hinzuzufügen, geben Sie anstelle von PhoneNumberIdentifier die CommunicationUserIdentifier an. In diesem Fall ist die Anrufer-ID nicht zwingend erforderlich.

„AddParticipant“ veröffentlicht ein AddParticipantSucceeded- oder AddParticipantFailed-Ereignis sowie ParticipantUpdated mit der aktuellen Teilnehmerliste des Anrufs.

Sequenzdiagramm des Hinzufügens von Teilnehmenden zu einem Anruf

Abbrechen einer Anforderung für das Hinzufügen von Teilnehmern

// add a participant
var addThisPerson = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
var addParticipantResponse = await callConnection.AddParticipantAsync(addThisPerson);

// cancel the request with optional parameters
var cancelAddParticipantOperationOptions = new CancelAddParticipantOperationOptions(addParticipantResponse.Value.InvitationId)
{
    OperationContext = "operationContext",
    OperationCallbackUri = new Uri("uri_endpoint"); // Sending event to a non-default endpoint.
}
await callConnection.CancelAddParticipantOperationAsync(cancelAddParticipantOperationOptions);

// Add user
CallInvite callInvite = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
AddParticipantOperationOptions addParticipantOperationOptions = new AddParticipantOptions(callInvite);
Response<AddParticipantResult> addParticipantOperationResultResponse = callConnectionAsync.addParticipantWithResponse(addParticipantOptions).block();

// cancel the request
CancelAddParticipantOperationOptions cancelAddParticipantOperationOptions = new CancelAddParticipantOperationOptions(addParticipantResultResponse.invitationId)
                .setOperationContext("<operation_context>")
                .setOperationCallbackUrl("<url_endpoint>");
callConnectionAsync.cancelAddParticipantOperationWithResponse(cancelAddParticipantOperationOptions).block();

// Add user
const addThisPerson = {
    targetParticipant: { communicationUserId: "<acs_user_id>" },
};
const { invitationId } = await callConnection.addParticipant(addThisPerson, {
            operationCallbackUrl: "<url_endpoint>",
            operationContext: "<operation_context>"
});

// cancel the request
await callConnection.cancelAddParticipantOperation(invitationId, {
            operationCallbackUrl: "<url_endpoint>",
            operationContext: "<operation_context>"
});

# Add user
target = CommunicationUserIdentifier("<acs_user_id>")

call_connection_client = call_automation_client.get_call_connection(
    "<call_connection_id_from_ongoing_call>"
)
result = call_connection_client.add_participant(target)

# cancel the request
call_connection_client.cancel_add_participant_operation(result.invitation_id, opration_context="Your context", operationCallbackUrl="<url_endpoint>")

Entfernen eines Teilnehmers aus einem Anruf

var removeThisUser = new CommunicationUserIdentifier("<user_id>"); 

// remove a participant from the call with optional parameters
var removeParticipantOptions = new RemoveParticipantOptions(removeThisUser)
{
    OperationContext = "operationContext",
    OperationCallbackUri = new Uri("uri_endpoint"); // Sending event to a non-default endpoint.
}

RemoveParticipantsResult result = await callConnection.RemoveParticipantAsync(removeParticipantOptions);

CommunicationIdentifier removeThisUser = new CommunicationUserIdentifier("<user_id>");
RemoveParticipantOptions removeParticipantOptions = new RemoveParticipantOptions(removeThisUser)
                .setOperationContext("<operation_context>")
                .setOperationCallbackUrl("<url_endpoint>");
Response<RemoveParticipantResult> removeParticipantResultResponse = callConnectionAsync.removeParticipantWithResponse(removeParticipantOptions).block();

const removeThisUser = { communicationUserId: "<user_id>" };
const removeParticipantResult = await callConnection.removeParticipant(removeThisUser, {
            operationCallbackUrl: "<url_endpoint>",
            operationContext: "<operation_context>"
});

remove_this_user = CommunicationUserIdentifier("<user_id>")
call_connection_client = call_automation_client.get_call_connection(
    "<call_connection_id_from_ongoing_call>"
)
result = call_connection_client.remove_participant(remove_this_user, opration_context="Your context", operationCallbackUrl="<url_endpoint>")

„RemoveParticipant“ veröffentlicht ein RemoveParticipantSucceeded- oder RemoveParticipantFailed-Ereignis sowie ein ParticipantUpdated-Ereignis mit der aktuellen Teilnehmerliste des Anrufs. Der entfernte Teilnehmer ist in der Liste nicht enthalten.
Sequenzdiagramm des Entfernens von Teilnehmenden aus dem Anruf

Auflegen eines Anrufs

Die hangUp-Aktion (Auflegen) kann verwendet werden, um Ihre Anwendung aus dem Aufruf zu entfernen oder einen Gruppenaufruf zu beenden, indem Sie den forEveryone-Parameter auf TRUE festlegen. Bei einem 1:1-Anruf wird durch Auflegen standardmäßig der Anruf mit dem anderen Teilnehmer beendet.

_ = await callConnection.HangUpAsync(forEveryone: true);

Response<Void> response = callConnectionAsync.hangUpWithResponse(true).block();

await callConnection.hangUp(true);

call_connection_client.hang_up(is_for_everyone=True)

Das CallDisconnected-Ereignis wird einmal veröffentlicht, nachdem die hangUp-Aktion erfolgreich abgeschlossen wurde.

Abrufen von Informationen zu einzelnen Anrufteilnehmenden

CallParticipant participantInfo = await callConnection.GetParticipantAsync(new CommunicationUserIdentifier("<user_id>"));

CallParticipant participantInfo = callConnection.getParticipant(new CommunicationUserIdentifier("<user_id>")).block();

const participantInfo = await callConnection.getParticipant({ communicationUserId: "<user_id>" });

participant_info = call_connection_client.get_participant(
    CommunicationUserIdentifier("<user_id>")
)

Abrufen von Informationen zu allen Anrufteilnehmenden

List<CallParticipant> participantList = (await callConnection.GetParticipantsAsync()).Value.ToList();

List<CallParticipant> participantList = Objects.requireNonNull(callConnection.listParticipants().block()).getValues();

const participantList = await callConnection.listParticipants();

participant_list = call_connection_client.list_participants()

Abrufen der neuesten Informationen zu einem Anruf

CallConnectionProperties callConnectionProperties = await callConnection.GetCallConnectionPropertiesAsync();

CallConnectionProperties callConnectionProperties = callConnection.getCallProperties().block();

const callConnectionProperties = await callConnection.getCallConnectionProperties();

call_connection_properties = call_connection_client.get_call_properties()

Freigeben über