Sdílet prostřednictvím

Jak ovládat a řídit volání pomocí automatizace volání

Automatizace volání používá rozhraní REST API k příjmu požadavků na akce a poskytnutí odpovědí, které upozorňují, jestli byl požadavek úspěšně odeslán nebo ne. Vzhledem k asynchronní povaze volání má většina akcí odpovídající události, které se aktivují, když se akce úspěšně dokončí nebo selže. Tato příručka popisuje akce dostupné pro řízení hovorů, jako jsou CreateCall, Transfer, Redirect a správa účastníků. Akce jsou doprovázeny vzorovým kódem o tom, jak vyvolat zmíněné akce a sekvenční diagramy popisující události očekávané po vyvolání akce. Tyto diagramy vám pomůžou vizualizovat, jak programovat aplikaci služby pomocí automatizace volání.

Automatizace volání podporuje různé další akce pro správu médií hovorů a nahrávání, které mají samostatné vodítka.

Jako předpoklad doporučujeme, abyste si přečetli tyto články, které vám pomůžou maximálně využít tohoto průvodce:

  1. Průvodce koncepty automatizace volání, který popisuje model programování na základě akcí a zpětná volání událostí.
  2. Seznamte se s identifikátory uživatelů, jako jsou CommunicationUserIdentifier a PhoneNumberIdentifier používané v této příručce.

Pro všechny ukázky kódu je CallAutomationClient objekt, client který lze vytvořit, jak je znázorněno a callConnection je CallConnection objekt získaný z odpovědi Answer nebo CreateCall. Můžete ho také získat z událostí zpětného volání přijatých vaší aplikací.

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

Uskutečnění odchozího hovoru

Můžete uskutečnit 1:1 nebo skupinový hovor na uživatele nebo telefonní číslo (veřejné číslo nebo číslo vlastněné komunikačními službami). Při volání koncového bodu veřejné telefonní sítě musíte také zadat telefonní číslo, které se použije jako ID zdrojového volajícího a zobrazí se v oznámení o volání cílovému koncovému bodu veřejné telefonní sítě. Chcete-li uskutečnit hovor uživatele komunikační služby, musíte poskytnout objekt CommunicationUserIdentifier namísto 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);

Při skupinovém hovoru, který obsahuje telefonní číslo, musíte zadat telefonní číslo, které se použije jako číslo ID volajícího do koncového bodu veřejné telefonní sítě.

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

Odpověď poskytuje objekt CallConnection, který můžete použít k provedení dalších akcí s tímto voláním po připojení. Po přijetí volání se do koncového bodu zpětného volání, který jste zadali dříve, publikují dvě události:

  1. CallConnected událost s oznámením, že hovor byl navázán s volaným.
  2. ParticipantsUpdated událost, která obsahuje nejnovější seznam účastníků hovoru. Sekvenční diagram pro uskutečnění odchozího volání.

V případě, že dojde k selhání volání, obdržíte CallDisconnected a CreateCallFailed událost s chybovými kódy pro další řešení potíží (další informace o kódech chyb naleznete na této stránce).

Připojte se k hovoru

Akce připojení umožňuje vaší službě navázat spojení s probíhajícím voláním a provádět s ním akce. To je užitečné při správě volání místností nebo při spuštění klientské aplikace 1:1 nebo skupinového volání, které automatizace volání není součástí. Připojení je vytvořeno pomocí CallLocator vlastnost a může být typu: ServerCallLocator, GroupCallLocator a RoomCallLocator. Tyto ID lze nalézt, když je volání původně navázáno, nebo když je vytvořena místnost, a také jsou publikovány jako součást události CallStarted.

Pokud se chcete připojit k libovolnému volání 1:1 nebo skupině, použijte ServerCallLocator. Pokud jste spustili volání pomocí GroupCallId, můžete také použít 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);

Pokud se chcete připojit k hovoru v místnosti, použijte RoomCallLocator, kam zadáte RoomId. Přečtěte si další informace o místnostech a o tom, jak lze rozhraní API pro automatizaci volání použít ke správě probíhajících volání místností.

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

Úspěšná odpověď vám poskytne objekt CallConnection, který můžete použít k provedení dalších akcí s tímto voláním. Do koncového bodu zpětného volání, který jste zadali dříve, se publikují dvě události:

  1. CallConnected událost s oznámením, že jste se úspěšně připojili k volání.
  2. ParticipantsUpdated událost, která obsahuje nejnovější seznam účastníků hovoru.

Pokud se vaše služba od tohoto volání odpojí, budete kdykoli po úspěšném připojení upozorněni prostřednictvím události CallDisconnected. Selhání připojení k volání při prvním pokusu způsobí událost ConnectFailed.

Sekvenční diagram pro připojení k volání

Přijetí příchozího hovoru

Jakmile se zaregistrujete k odběru oznámení o příchozích hovorech na vaší platformu, přijmete příchozí hovor. Při odpovídání na hovor je nutné zadat adresu URL zpětného volání. Služby komunikace publikují všechny následné události týkající se tohoto hovoru na tu adresu 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;

Odpověď poskytuje objekt CallConnection, který můžete použít k provedení dalších akcí s tímto voláním po připojení. Po přijetí volání se do koncového bodu zpětného volání, který jste zadali dříve, publikují dvě události:

  1. CallConnected událost s oznámením, že hovor byl vytvořen s volajícím.
  2. ParticipantsUpdated událost, která obsahuje nejnovější seznam účastníků hovoru.

Sekvenční diagram pro příjem příchozího hovoru

V případě selhání operace odpovědi se zobrazí AnswerFailed událost s kódy chyb pro další řešení potíží (další informace o kódech chyb najdete na této stránce ).

Odmítnutí hovoru

Příchozí hovor můžete odmítnout, jak je znázorněno níže. Můžete zadat důvod zamítnutí: žádný, zaneprázdněný nebo zakázaný. Pokud není nic zadané, není ve výchozím nastavení zvolena žádná.

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

Pro akci zamítnutí nejsou publikovány žádné události.

Přesměrování hovoru

Příchozí hovor můžete přesměrovat do jiného koncového bodu bez odpovědi. Přesměrování volání odebere schopnost aplikace řídit volání pomocí automatizace volání.

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

Pokud chcete hovor přesměrovat na telefonní číslo, vytvořte cílové ID a ID volajícího pomocí 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);

Pro přesměrování se nepublikují žádné události. Pokud je cílem uživatel služeb komunikace nebo telefonní číslo vlastněné vaším prostředkem, vygeneruje novou událost „IncomingCall“ s polem 'to' nastaveným na vámi zadaný cíl.

Přepojit účastníka v hovoru

Když vaše aplikace přijme hovor nebo umístí odchozí volání do koncového bodu, je možné tento koncový bod přenést do jiného cílového koncového bodu. Přenos volání 1:1 odebere vaši aplikaci z hovoru a tím odebere její schopnost řídit volání pomocí automatizace volání. Pozvánka na volání do cíle zobrazí ID volajícího z koncového bodu, který je přenášen. Poskytnutí vlastního ID volajícího se nepodporuje.

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

Když vaše aplikace odpoví na skupinové volání nebo umístí odchozí volání skupiny do koncového bodu nebo přidá účastníka do volání 1:1, může se koncový bod přenést z volání do jiného cílového koncového bodu s výjimkou koncového bodu automatizace volání. Když přepojíte účastníka ve skupinovém hovoru, odebere se účastníkův koncový bod z hovoru. Pozvánka na volání pro cíl zobrazí ID volajícího koncového bodu, který je přenášen. Poskytnutí vlastního ID volajícího se nepodporuje.

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

V sekvenčním diagramu je vidět očekávaný tok, když vaše aplikace umístí odchozí volání a pak ho přenese do jiného koncového bodu.

Sekvenční diagram pro uskutečnění hovoru 1:1 a jeho následné přesměrování

Přidání účastníka do hovoru

Účastníka (uživatel komunikační služby nebo telefonní číslo) můžete přidat do existujícího hovoru. Při přidávání telefonního čísla je povinné zadat ID volajícího. Toto ID volajícího se zobrazí při oznámení o hovoru přidanému účastníkovi.

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

Pokud chcete přidat uživatele Komunikační služby, zadejte místo „PhoneNumberIdentifier“ „CommunicationUserIdentifier“. ID volajícího není v tomto případě povinné.

AddParticipant publikuje AddParticipantSucceeded událost spolu AddParticipantFailed s ParticipantUpdated nejnovějším seznamem účastníků hovoru.

Sekvenční diagram pro přidání účastníka do hovoru

Zrušení žádosti o přidání účastníka

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

Odebrání účastníka z hovoru

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 publikuje RemoveParticipantSucceeded nebo RemoveParticipantFailed událost, spolu s ParticipantUpdated událostí, která poskytuje nejnovější seznam účastníků hovoru. Odebraný účastník se ze seznamu vynechá.
Sekvenční diagram pro odebrání účastníka z hovoru

Zavěsit hovor

Akci Zavěsit můžete použít k ukončení účasti vaší aplikace v hovoru nebo k ukončení skupinového hovoru nastavením parametru forEveryone na hodnotu true. Při hovoru 1:1 se ve výchozím nastavení hovor s druhým účastníkem ukončí.

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

Jakmile se akce hangUp úspěšně dokončí, publikuje se událost CallDisconnected.

Získání informací o účastníkovi hovoru

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

Získání informací o všech účastnících hovoru

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

Získání nejnovějších informací o hovoru

CallConnectionProperties callConnectionProperties = await callConnection.GetCallConnectionPropertiesAsync();