Dela via

Kontrollera och styra samtal med Samtalsautomation

Call Automation använder ett REST API-gränssnitt för att ta emot begäranden om åtgärder och ge svar för att meddela om begäran har skickats eller inte. På grund av anropets asynkrona karaktär har de flesta åtgärder motsvarande händelser som utlöses när åtgärden har slutförts eller misslyckas. Den här artikeln beskriver de åtgärder som är tillgängliga för styrningsanrop, till exempel CreateCall, Transferoch , och Redirecthantering av deltagare. Exempelkod visar hur du anropar den specifika åtgärden. Sekvensdiagram beskriver de händelser som förväntas när du anropar en åtgärd. Diagrammen hjälper dig att visualisera hur du programmerar tjänstprogrammet med Samtalsautomation.

Samtalsautomation stöder andra åtgärder för att hantera samtalsmedia och inspelning som har separata artiklar.

Prerequisites

För alla kodexempel är client det CallAutomationClient-objekt som du kan skapa, som det visas. callConnection är det CallConnection objekt som du också hämtar från det Answer- eller CreateCall-svaret. Du kan också hämta den från återuppringningshändelser som din applikation tar emot.

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

Ringa ett utgående samtal

Du kan ringa ett 1:1- eller gruppsamtal till en kommunikationsanvändare eller ett telefonnummer (ett offentligt nummer eller ett som Azure Communication Services äger). När du ringer en PSTN-slutpunkt (public-switched phone network) måste du också ange ett telefonnummer som ska användas som källsamtals-ID och som visas som samtalsmeddelandet till PSTN-målslutpunkten.

Om du vill ringa ett anrop till en Azure Communication Services-användare måste du ange ett CommunicationUserIdentifier objekt i stället för 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);

När du ringer ett gruppsamtal som inkluderar ett telefonnummer måste du ange ett telefonnummer för att använda som identifikationsnummer för PSTN-slutpunkten.

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

Svaret ger dig det CallConnection objekt som du kan använda för att vidta ytterligare åtgärder för det här anropet när det har anslutits. När samtalet har besvarats publiceras två händelser till motringningsslutpunkten som du angav tidigare:

  • CallConnected: Meddelar att samtalet upprättades med anroparen.

  • ParticipantsUpdated: Innehåller den senaste listan över deltagare i samtalet.

    Diagram som visar sekvensen för att placera ett utgående anrop.

Om samtalet misslyckas får du en CallDisconnected händelse och en CreateCallFailed händelse med felkoder för ytterligare felsökning. Mer information om felkoder finns i Felsöka svarskoder för samtalsslut.

Ansluta till ett samtal

Anslutningsåtgärden gör det möjligt för din tjänst att upprätta en anslutning med ett pågående anrop och vidta åtgärder på den. Den här funktionen är användbar för att hantera ett Rum-samtal eller när klientprogram startar ett 1:1- eller gruppsamtal där Samtalsautomation inte är en del. Använd egenskapen CallLocator för att upprätta anslutningen. Typalternativen är ServerCallLocator, GroupCallLocatoroch RoomCallLocator. Du hittar dessa ID:er när anropet upprättas från början eller ett rum skapas, och dessutom kan dessa publiceras som en del av CallStarted-händelsen.

Om du vill ansluta till ett 1:1- eller gruppsamtal använder du ServerCallLocator. Om du brukade GroupCallId starta ett samtal kan du också använda GroupCallLocator.

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

Om du vill ansluta till ett Rooms-samtal använder du RoomCallLocator, vilket tar RoomId. Läs mer om Rum och hur du kan använda API:et för samtalsautomatisering för att hantera ett pågående rumssamtal.

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

Ett lyckat svar ger dig ett CallConnection objekt som du kan använda för att vidta ytterligare åtgärder i det här anropet. Två händelser publiceras till anropsslutpunkten som du angav tidigare.

  • CallConnected: Meddelar att du har anslutit till anropet.
  • ParticipantsUpdated: Innehåller den senaste listan över deltagare i samtalet.

När som helst efter en lyckad anslutning, om tjänsten förlorar anslutningen från det här anropet, meddelas du av en CallDisconnected händelse. Det gick inte att ansluta till samtalet till att börja med, vilket resulterar i händelsen ConnectFailed.

Diagram som visar sekvensen för att ansluta till ett anrop.

Besvara ett inkommande samtal

När du prenumererar för att få inkommande samtalsaviseringar till din resurs kan du svara på ett inkommande samtal. När du svarar på ett samtal måste du ange en motringnings-URL. Azure Communication Services publicerar alla efterföljande händelser om det här anropet till den URL:en.

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;

Svaret ger dig ett CallConnection objekt som du kan använda för att vidta ytterligare åtgärder i det här anropet när det har anslutits. När samtalet har besvarats publiceras två händelser till motringningsslutpunkten som du angav tidigare:

  • CallConnected: Meddelar att samtalet upprättades med anroparen.
  • ParticipantsUpdated: Innehåller den senaste listan över deltagare i samtalet.

Diagram som visar sekvensen för att besvara ett inkommande samtal.

Om svarsåtgärden misslyckas får du en AnswerFailed händelse med felkoder för ytterligare felsökning. Mer information om felkoder finns i Felsöka svarskoder för samtalsslut.

Avvisa ett anrop

Du kan avvisa ett inkommande samtal. Orsaker till avslaget är None, Busyeller Forbidden. Om inget anges är Nonestandardvärdet .

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

Inga händelser publiceras för avvisningsåtgärden.

Omdirigera ett anrop

Du kan omdirigera ett inkommande samtal till en annan slutpunkt utan att svara på det. Om du omdirigerar ett samtal tas programmets möjlighet att styra anropet bort med hjälp av Samtalsautomation.

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 du vill omdirigera samtalet till ett telefonnummer skapar du mål- och uppringarens ID med 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);

Inga händelser publiceras för omdirigering. Om målet är en Azure Communication Services-användare eller ett telefonnummer som din resurs äger genererar det en ny IncomingCall händelse med fältet to inställt på det mål som du anger.

Överföra en deltagare i ett samtal

När programmet svarar på ett samtal eller ringer ett utgående samtal till en slutpunkt kan appen överföra slutpunkten till en annan målslutpunkt. Överföring av ett 1:1-anrop tar bort ditt program från anropet och tar bort dess möjlighet att styra samtalet med hjälp av Samtalsautomation. Samtalsinbjudan till målet visar uppringarens ID för slutpunkten som överförs. Det går inte att tillhandahålla en anpassad nummerpresentatör.

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

När ditt program svarar på ett gruppsamtal, placerar ett utgående gruppanrop till en slutpunkt eller lägger till en deltagare i ett 1:1-samtal kan appen överföra slutpunkten från anropet till en annan målslutpunkt, förutom slutpunkten För samtalsautomatisering. Överföring av en deltagare i ett gruppsamtal tar bort slutpunkten som överförs från anropet. Samtalsinbjudan till målet visar uppringarens ID för slutpunkten som överförs. Det går inte att tillhandahålla en anpassad nummerpresentatör.

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

Sekvensdiagrammet visar det förväntade flödet när programmet placerar ett utgående anrop och sedan överför det till en annan slutpunkt.

Diagram som visar sekvensen för att placera ett 1:1-anrop och sedan överföra det.

Lägga till en deltagare i ett anrop

Du kan lägga till en deltagare, till exempel en Azure Communication Services-användare eller ett telefonnummer i ett befintligt samtal. När du lägger till ett telefonnummer är det obligatoriskt att ange en nummerpresentatör. Det här uppringar-ID:t visas vid samtalsmeddelande till den tillagda deltagaren.

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

Om du vill lägga till en Azure Communication Services-användare anger du CommunicationUserIdentifier i stället för PhoneNumberIdentifier. Nummerpresentationen är inte obligatorisk i det här fallet.

AddParticipant Därefter publicerar en AddParticipantSucceeded eller AddParticipantFailed händelse, tillsammans med ParticipantUpdated som innehåller den senaste listan över deltagare i samtalet.

Diagram som visar sekvensen för att lägga till en deltagare i anropet.

Avbryt en begäran om att lägga till deltagare

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

Överför en deltagare till ett samtal från ett annat samtal

Med Azure Communication Services Call Automation SDK kan du flytta en deltagare från ett pågående anrop till ett annat med hjälp av Api:et MoveParticipants. Detta möjliggör dynamisk routning och flexibel samtalsorkestrering – vanligt i scenarier som att flytta en översättare till ett läkar-patientsamtal eller överföra en kund från ett lobbysamtal till ett aktivt supportsamtal.

Exempelscenarier:

  • Doctor + Translator Room Routing – Flytta individuellt uppringda översättare till ett huvudsamtal.

  • Överföring av samtal i lobbyn – Håll deltagarna på en separat linje tills de godkänts för att delta i huvudsamtalet.

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 publicerar en MoveParticipantSucceeded- eller MoveParticipantFailed-händelse till målanropet.

Ta bort en deltagare från ett anrop

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 publicerar en RemoveParticipantSucceeded eller RemoveParticipantFailed händelse, tillsammans med en ParticipantUpdated händelse som innehåller den senaste listan över deltagare i samtalet. Den borttagna deltagaren utelämnas från listan.

Diagram som visar sekvensen för att ta bort en deltagare från ett anrop.

Lägg på ett samtal

Du kan använda åtgärden hangUp för att ta bort programmet från anropet eller för att avsluta ett gruppanrop genom att ange parametern forEveryone till true. För ett 1:1-samtal hangUp avslutar samtalet med den andra deltagaren som standard.

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

Händelsen CallDisconnected publiceras när åtgärden hangUp har slutförts.

Hämta information om en samtalsdeltagare

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

Få information om alla samtalsdeltagare

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

Hämta den senaste informationen om ett samtal

CallConnectionProperties callConnectionProperties = await callConnection.GetCallConnectionPropertiesAsync();