Så här styr och styr du samtal med Samtalsautomation

  • Artikel

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 slutförs eller misslyckas. Den här guiden beskriver de åtgärder som är tillgängliga för styrningsanrop, till exempel CreateCall, Transfer, Redirect och managing participants. Åtgärder åtföljs av exempelkod om hur du anropar åtgärden och sekvensdiagrammen som beskriver de händelser som förväntas efter att en åtgärd har anropats. De här diagrammen hjälper dig att visualisera hur du programmerar tjänstprogrammet med Samtalsautomation.

Call Automation stöder olika andra åtgärder för att hantera samtalsmedia och inspelning som har separata guider.

Som en förutsättning rekommenderar vi att du läser dessa artiklar för att få ut det mesta av den här guiden:

  1. Guide för att anropa Automation-begrepp som beskriver programmeringsmodellen för åtgärdshändelser och återanrop till händelser.
  2. Lär dig mer om användaridentifierare som CommunicationUserIdentifier och PhoneNumberIdentifier som används i den här guiden.

För alla kodexempel client är Det CallAutomationClient-objekt som kan skapas som det visas och callConnection är CallConnection-objektet som hämtas från Svar eller CreateCall-svar. Du kan också hämta den från motringningshändelser som tas emot av ditt program.

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 (offentligt nummer eller kommunikationstjänsters ägda nummer). När du anropar en PSTN-slutpunkt måste du också ange ett telefonnummer som används som källanropar-ID och som visas i samtalsmeddelandet till PSTN-målslutpunkten. Om du vill ringa ett samtal till en 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 innehåller ett telefonnummer måste du ange ett telefonnummer som används som nummerpresentation till 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 ett CallConnection-objekt som du kan använda för att vidta ytterligare åtgärder i det här anropet när det är anslutet. När samtalet har besvarats publiceras två händelser till den motringningsslutpunkt som du angav tidigare:

  1. CallConnected händelse som meddelar att samtalet har upprättats med den anropande personen.
  2. ParticipantsUpdated som innehåller den senaste listan över deltagare i samtalet. Sekvensdiagram för att placera ett utgående anrop.

Om samtalet misslyckas får du en CallDisconnected och-händelse CreateCallFailed med felkoder för ytterligare felsökning (se den här sidan för mer information om felkoder för samtalsautomatisering).

Ansluta till ett samtal (i förhandsversion)

Med connect-åtgärden kan din tjänst upprätta en anslutning med ett pågående anrop och vidta åtgärder på den. Det här är användbart för att hantera ett Rum-samtal eller när klientprogram startade ett 1:1- eller gruppsamtal som Samtalsautomation inte ingår i. Anslutningen upprättas med egenskapen CallLocator och kan vara av olika typer: ServerCallLocator, GroupCallLocator och RoomCallLocator. Dessa ID:er kan hittas när anropet ursprungligen upprättas eller ett rum skapas och även publiceras som en del av CallStarted-händelsen .

Om du vill ansluta till ett 1:1- eller gruppanrop använder du ServerCallLocator. Om du startade ett samtal med GroupCallId 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 rumssamtal använder du RoomCallLocator som tar RoomId. Läs mer om Rum och hur Api för samtalsautomatisering kan användas för att hantera 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 motringningsslutpunkten som du angav tidigare:

  1. CallConnected händelse som meddelar att du har anslutit till samtalet.
  2. ParticipantsUpdated som innehåller den senaste listan över deltagare i samtalet.

När som helst efter en lyckad anslutning meddelas du via en CallDisconected-händelse om tjänsten är frånkopplad från det här samtalet. Det gick inte att ansluta till anropet i första hand resulterar i ConnectFailed-händelsen.

Sekvensdiagram för att ansluta till anrop.

Besvara ett inkommande samtal

När du har prenumererat för att få inkommande samtalsaviseringar till din resurs svarar du på ett inkommande samtal. När du svarar på ett samtal är det nödvändigt att ange en url för återanrop. 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 är anslutet. När samtalet har besvarats publiceras två händelser till den motringningsslutpunkt som du angav tidigare:

  1. CallConnected händelse som meddelar att samtalet har upprättats med uppringaren.
  2. ParticipantsUpdated som innehåller den senaste listan över deltagare i samtalet.

Sekvensdiagram för att besvara ett inkommande samtal.

Avvisa ett anrop

Du kan välja att avvisa ett inkommande samtal enligt nedan. Du kan ange en avvisningsorsak: ingen, upptagen eller förbjuden. Om inget anges väljs ingen som standard.

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 välja att omdirigera ett inkommande samtal till en annan slutpunkt utan att svara på det. Om du omdirigerar ett samtal tas programmets möjlighet att styra samtalet med hjälp av samtalsautomation bort.

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 nummerpresentationen 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 Communication Services-användare eller ett telefonnummer som ägs av resursen genereras en ny IncomingCall-händelse med fältet "till" inställt på det mål som du angav.

Överföra en deltagare i anropet

När ditt program besvarar ett samtal eller placerar ett utgående anrop till en slutpunkt kan slutpunkten överföras till en annan målslutpunkt. Överföring av ett 1:1-anrop tar bort ditt program från anropet och tar därför 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 ange ett anpassat nummerpresentation.

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 eller placerar ett utgående gruppanrop till en slutpunkt eller har lagt till en deltagare i ett 1:1-samtal kan en slutpunkt överföras 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 ange ett anpassat nummerpresentation.

// 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.

Sekvensdiagram 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 (Communication Services-användare eller telefonnummer) i ett befintligt samtal. När du lägger till ett telefonnummer är det obligatoriskt att ange ett nummerpresentation. Det här uppringar-ID:t visas vid samtalsmeddelande till deltagaren som läggs till.

// 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 Communication Services-användare anger du en CommunicationUserIdentifier i stället för PhoneNumberIdentifier. Nummerpresentation är inte obligatoriskt i det här fallet.

AddParticipant publicerar en AddParticipantSucceeded eller AddParticipantFailed en händelse, tillsammans med en ParticipantUpdated lista över deltagare i samtalet.

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

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 ett evenemang, tillsammans med en ParticipantUpdated händelse som tillhandahåller den senaste listan över deltagare i samtalet. Den borttagna deltagaren utelämnas från listan.
Sekvensdiagram för att ta bort en deltagare från anropet.

Lägg på vid ett samtal

Lägg på kan användas för att ta bort programmet från anropet eller för att avsluta ett gruppanrop genom att ange parameternEveryone till true. För ett 1:1-samtal avslutas samtalet med den andra deltagaren som standard.

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

CallDisconnected-händelsen publiceras när hangUp-åtgärden 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();

Få senaste information om ett samtal

CallConnectionProperties callConnectionProperties = await callConnection.GetCallConnectionPropertiesAsync();