Gesprekken beheren en sturen met Gespreksautomatisering

Aanroepautomatisering maakt gebruik van een REST API-interface voor het ontvangen van aanvragen voor acties en het verstrekken van antwoorden om te melden of de aanvraag is verzonden of niet. Vanwege de asynchrone aard van het aanroepen hebben de meeste acties overeenkomende gebeurtenissen die worden geactiveerd wanneer de actie is voltooid of mislukt. In dit artikel worden de acties besproken die beschikbaar zijn voor het sturen van oproepen, zoals CreateCall, Transfer, Redirect, en het beheren van deelnemers. Voorbeeldcode laat zien hoe u de specifieke actie aanroept. Sequentiediagrammen beschrijven de gebeurtenissen die worden verwacht nadat u een actie hebt aangeroepen. Met de diagrammen kunt u visualiseren hoe u uw servicetoepassing kunt programmeren met Gespreksautomatisering.

Call Automation ondersteunt andere acties voor het beheren van oproepmedia en -opname met afzonderlijke artikelen.

Prerequisites

  • Lees het artikel over gespreksautomatiseringconcepten concepten waarin het actie-gebeurtenisprogrammeermodel en event callbacks worden beschreven.
  • Meer informatie over de gebruikers-id's zoals CommunicationUserIdentifier en PhoneNumberIdentifier die worden gebruikt in dit artikel.

Voor alle codevoorbeelden client is het CallAutomationClient object dat u kunt maken, zoals wordt weergegeven. callConnection Is ook het CallConnection object dat u verkrijgt van het Answer of CreateCall antwoord. U kunt deze ook verkrijgen via callback-gebeurtenissen die door uw toepassing worden ontvangen.

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

Een uitgaande oproep maken

U kunt een 1:1- of groepsgesprek plaatsen naar een communicatiegebruiker of telefoonnummer (een openbaar nummer of een nummer dat azure Communication Services bezit). Wanneer u een PSTN-eindpunt (public-switched telephone network) belt, moet u ook een telefoonnummer opgeven dat moet worden gebruikt als de bronaanroeper-id en die wordt weergegeven als de oproepmelding naar het PSTN-doeleindpunt.

Als u een aanroep naar een Azure Communication Services-gebruiker wilt plaatsen, moet u een CommunicationUserIdentifier object opgeven in plaats van PhoneNumberIdentifier.

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);

Wanneer u een groepsgesprek voert dat een telefoonnummer bevat, moet u een telefoonnummer opgeven dat moet worden gebruikt als nummer van de beller voor het PSTN-eindpunt.

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);

Het antwoord bevat het CallConnection object dat u kunt gebruiken om verdere acties uit te voeren voor deze aanroep nadat deze verbinding heeft gemaakt. Nadat de oproep is beantwoord, worden twee gebeurtenissen gepubliceerd naar het callback-eindpunt dat u eerder hebt opgegeven:

  • CallConnected: Hiermee wordt aangegeven dat de oproep tot stand is gebracht met de beller.

  • ParticipantsUpdated: Bevat de meest recente lijst met deelnemers aan het gesprek.

    Diagram met de volgorde voor het plaatsen van een uitgaande oproep.

Als de oproep mislukt, ontvangt u een CallDisconnected gebeurtenis en een CreateCallFailed gebeurtenis met foutcodes voor verdere probleemoplossing. Zie Problemen met antwoordcodes voor aanroepen oplossen voor meer informatie over foutcodes.

Verbinding maken met een gesprek

Met de verbindingsactie kan uw service een verbinding tot stand brengen met een doorlopende oproep en acties ondernemen. Deze mogelijkheid is handig om een chatgesprek te beheren of wanneer clienttoepassingen een 1:1- of groepsaanroep starten waarin gespreksautomatisering geen deel uitmaakt. Gebruik de CallLocator eigenschap om de verbinding tot stand te brengen. De typeopties zijn ServerCallLocator, GroupCallLocatoren RoomCallLocator. U kunt deze ID's vinden wanneer de oproep oorspronkelijk tot stand is gebracht of wanneer een ruimte is gecreëerd, en ze kunnen ook worden gepubliceerd als onderdeel van CallStarted-gebeurtenis.

Als u verbinding wilt maken met een 1:1- of groepsgesprek, gebruikt u ServerCallLocator. Als u GroupCallId hebt gebruikt om een gesprek te starten, kunt u ook GroupCallLocator gebruiken.

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);

Als u verbinding wilt maken met een kamergesprek, gebruikt u RoomCallLocator, wat RoomId nodig heeft. Meer informatie over Rooms en hoe u de Call Automation API kunt gebruiken om een doorlopende oproep in Rooms te beheren.

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);

Een geslaagd antwoord biedt u een CallConnection object dat u kunt gebruiken om verdere acties uit te voeren voor deze aanroep. Er worden twee gebeurtenissen gepubliceerd naar het callback-eindpunt dat u eerder hebt opgegeven:

  • CallConnected: Hiermee wordt aangegeven dat u verbinding hebt gemaakt met de oproep.
  • ParticipantsUpdated: Bevat de meest recente lijst met deelnemers aan het gesprek.

Op elk moment na het tot stand brengen van een geslaagde verbinding, als uw service de verbinding met deze oproep verbreekt, wordt u door een CallDisconnected gebeurtenis op de hoogte gebracht. Het niet kunnen verbinden met de oproep in eerste instantie resulteert in de ConnectFailed gebeurtenis.

Diagram met de volgorde voor het maken van verbinding met een aanroep.

Een inkomende oproep beantwoorden

Nadat u zich hebt geabonneerd om binnenkomende oproepmeldingen voor uw resource te ontvangen, kunt u een binnenkomende oproep beantwoorden. Wanneer u een oproep beantwoordt, moet u een callback-URL opgeven. Azure Communication Services plaatst alle volgende gebeurtenissen over deze aanroep naar die 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;

Het antwoord bevat een CallConnection object dat u kunt gebruiken om verdere acties uit te voeren voor deze aanroep nadat deze verbinding heeft gemaakt. Nadat de oproep is beantwoord, worden twee gebeurtenissen gepubliceerd naar het callback-eindpunt dat u eerder hebt opgegeven:

  • CallConnected: Hiermee wordt aangegeven dat de oproep tot stand is gebracht met de beller.
  • ParticipantsUpdated: Bevat de meest recente lijst met deelnemers aan het gesprek.

Diagram met de volgorde voor het beantwoorden van een inkomende oproep.

Als de antwoordbewerking mislukt, ontvangt u een AnswerFailed gebeurtenis met foutcodes voor verdere probleemoplossing. Zie Problemen met antwoordcodes voor aanroepen oplossen voor meer informatie over foutcodes.

Een oproep weigeren

U kunt een inkomende oproep weigeren. Redenen voor de afwijzing zijn None, Busyof Forbidden. Als er niets wordt opgegeven, is de standaardwaarde None.

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

Er worden geen gebeurtenissen gepubliceerd voor de weigeringsactie.

Een oproep omleiden

U kunt een binnenkomende oproep omleiden naar een ander eindpunt zonder deze te beantwoorden. Als u een aanroep omleidt, wordt de mogelijkheid van uw toepassing om het gesprek te beheren met behulp van Gespreksautomatisering verwijderd.

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);

Om de oproep naar een telefoonnummer door te sturen, stelt u het doelnummer en de beller-ID in met 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);

Er worden geen gebeurtenissen gepubliceerd voor omleiding. Als het doel een Azure Communication Services-gebruiker of een telefoonnummer is dat uw resource bezit, wordt er een nieuwe IncomingCall gebeurtenis gegenereerd met het to veld dat is ingesteld op het doel dat u opgeeft.

Een deelnemer doorschakelen tijdens een gesprek

Wanneer uw toepassing een oproep beantwoordt of een uitgaande aanroep naar een eindpunt plaatst, kan uw app het eindpunt overbrengen naar een ander doeleindpunt. Als u een oproep van 1:1 overdraagt, wordt uw toepassing verwijderd uit de oproep en wordt de mogelijkheid om de oproep te beheren met behulp van Gespreksautomatisering verwijderd. De oproepuitnodiging voor het doel toont de nummerweergave van het eindpunt dat wordt overgedragen. Het opgeven van een aangepaste beller-ID wordt niet ondersteund.

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);

Wanneer uw toepassing een groepsoproep beantwoordt, een uitgaande groepsoproep naar een eindpunt plaatst of een deelnemer toevoegt aan een 1:1-oproep, kan de app het eindpunt overdragen van de oproep naar een ander doeleindpunt, met uitzondering van het eindpunt oproepautomatisering. Als u een deelnemer overdraagt in een groepsgesprek, wordt het eindpunt dat wordt overgedragen uit de oproep verwijderd. De oproepuitnodiging voor het doel toont de nummerweergave van het eindpunt dat wordt overgedragen. Het opgeven van een aangepaste beller-ID wordt niet ondersteund.

// 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);

Het sequentiediagram toont de verwachte stroom wanneer uw toepassing een uitgaande aanroep plaatst en deze vervolgens overdraagt naar een ander eindpunt.

Diagram met de volgorde voor het plaatsen van een 1:1-oproep en vervolgens doorverbinden.

Een deelnemer toevoegen aan een gesprek

U kunt een deelnemer, zoals een Azure Communication Services-gebruiker of een telefoonnummer, toevoegen aan een bestaand gesprek. Wanneer u een telefoonnummer toevoegt, is het verplicht om een beller-ID op te geven. Deze nummerweergave wordt weergegeven bij oproepmelding aan de toegevoegde deelnemer.

// 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);

Als u een Azure Communication Services-gebruiker wilt toevoegen, geeft u CommunicationUserIdentifier dit op in plaats van PhoneNumberIdentifier. Nummerweergave is in dit geval niet verplicht.

AddParticipant Vervolgens publiceert u een AddParticipantSucceeded of AddParticipantFailed gebeurtenis, samen met ParticipantUpdated de meest recente lijst met deelnemers aan het gesprek.

Diagram met de volgorde voor het toevoegen van een deelnemer aan het gesprek.

Een aanvraag voor een deelnemer toevoegen annuleren

// 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);

Een deelnemer verplaatsen naar een gesprek vanuit een ander gesprek

Met azure Communication Services Call Automation SDK kunt u een deelnemer van de ene lopende aanroep naar een andere verplaatsen met behulp van de MoveParticipants-API. Dit maakt dynamische routering en flexibele oproepindeling mogelijk, die gebruikelijk zijn in scenario's zoals het verplaatsen van een vertaler naar een arts-patiëntoproep of het overzetten van een klant vanuit een lobbyoproep naar een actieve ondersteuningsoproep.

Voorbeeldscenario's:

  • Doctor + Translator Room Routing – Verplaats individueel gekozen vertalers naar een hoofdgesprek.

  • Oproepoverdracht lobby: houd deelnemers in een apart gesprek vast totdat ze zijn goedgekeurd om deel te nemen aan het hoofdgesprek.

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

// CallConnectionId for the call that you want to move the participant from
var fromCallId = "<callConnectionId>";

// Move a participant from another call to current call with optional parameters
var moveParticipantsOptions = new MoveParticipantOptions(
    new List<CommunicationIdentifier> { targetParticipant }, 
    fromCallId)
{
    OperationContext = "operationContext",
    OperationCallbackUri = new Uri("uri_endpoint") // Sending event to a non-default endpoint.
};

MoveParticipantsResult result = await callConnection.MoveParticipantsAsync(moveParticipantsOptions);

MoveParticipants publiceert een MoveParticipantSucceededed- of MoveParticipantFailed-gebeurtenis naar de doelaanroep.

Een deelnemer uit een gesprek verwijderen

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);

RemoveParticipant publiceert een RemoveParticipantSucceeded of RemoveParticipantFailed gebeurtenis, samen met een ParticipantUpdated gebeurtenis die de meest recente lijst met deelnemers aan het gesprek biedt. De verwijderde deelnemer wordt weggelaten uit de lijst.

Diagram met de volgorde voor het verwijderen van een deelnemer uit een gesprek.

Een telefoongesprek beëindigen

U kunt de hangUp actie gebruiken om uw toepassing uit de aanroep te verwijderen of een groepsoproep te beëindigen door de forEveryone parameter in te stellen op true. Voor een 1-op-1 gesprek wordt de oproep standaard beëindigd met de andere deelnemer hangUp.

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

De CallDisconnected gebeurtenis wordt gepubliceerd nadat de hangUp actie is voltooid.

Informatie over een gespreksdeelnemer ophalen

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

Informatie over alle gespreksdeelnemers

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

De meest recente informatie over een gesprek ophalen

CallConnectionProperties callConnectionProperties = await callConnection.GetCallConnectionPropertiesAsync();
  • Last updated on