Come passare dati contestuali tra chiamate

  • Articolo

Call Automation consente agli sviluppatori di passare informazioni contestuali personalizzate durante il routing delle chiamate. Gli sviluppatori possono passare metadati relativi alla chiamata, al chiamato o a qualsiasi altra informazione rilevante per l'applicazione o la logica di business. Ciò consente alle aziende di gestire e instradare le chiamate tra reti senza doversi preoccupare di perdere contesto.

Il passaggio del contesto è supportato specificando intestazioni personalizzate. Si tratta di un elenco facoltativo di coppie chiave-valore che possono essere incluse come parte di AddParticipant o Transfer azioni. Il contesto può essere recuperato in un secondo momento come parte del payload dell'evento IncomingCall .

Il contesto di chiamata personalizzato viene inoltre inoltrato al protocollo SIP, che include sia le intestazioni personalizzate a mano libera sia l'intestazione SIP standard user-to-user information (UUI). Quando si instrada una chiamata in ingresso dalla rete di telefonia, il set di dati del SBC nelle intestazioni personalizzate e l'interfaccia utente utente sono inclusi in modo analogo nel payload dell'evento IncomingCall .

Tutti i dati di contesto personalizzati sono opachi per i protocolli SIP o Di automazione delle chiamate e il relativo contenuto non è correlato alle funzioni di base.

Di seguito sono riportati esempi su come iniziare a usare le intestazioni di contesto personalizzate in Automazione chiamate.

Come prerequisito, è consigliabile leggere questi articoli per sfruttare al meglio questa guida:

  • Guida ai concetti di Automazione delle chiamate che descrive il modello di programmazione degli eventi action-event e i callback degli eventi.
  • Informazioni sugli identificatori utente, ad esempio CommunicationUserIdentifier e Telefono NumberIdentifier usati in questa guida.

Per tutti gli esempi di codice, client è l'oggetto CallAutomationClient che può essere creato come illustrato ed callConnection è l'oggetto Call Connessione ion ottenuto dalla risposta Answer o CreateCall. È anche possibile ottenerlo dagli eventi di callback ricevuti dall'applicazione.

Parametri tecnici

L'automazione delle chiamate supporta fino a 5 intestazioni SIP personalizzate e 1000 intestazioni VOIP personalizzate. Inoltre, gli sviluppatori possono includere un'intestazione utente-utente dedicata come parte dell'elenco di intestazioni SIP.

La chiave di intestazione SIP personalizzata deve iniziare con un prefisso obbligatorio 'X-MS-Custom-'. La lunghezza massima di una chiave di intestazione SIP è di 64 caratteri, incluso il prefisso X-MS-Custom. La chiave di intestazione SIP può essere costituita da caratteri alfanumerici e da alcuni simboli selezionati che includono ., , %*!, +_, , . -~ La lunghezza massima del valore dell'intestazione SIP è di 256 caratteri. Le stesse limitazioni si applicano quando si configurano le intestazioni SIP nel SBC. Il valore dell'intestazione SIP può essere costituito da caratteri alfanumerici e da alcuni simboli selezionati che includono =, *!%;._, +, . -~

La lunghezza massima di una chiave di intestazione VOIP è di 64 caratteri. Queste intestazioni possono essere inviate senza prefisso 'x-MS-Custom'. La lunghezza massima del valore dell'intestazione VOIP è 1024 caratteri.

Aggiunta di contesto personalizzato quando si invita un partecipante

// Invite a communication services user and include one VOIP header
var addThisPerson = new CallInvite(new CommunicationUserIdentifier("<user_id>"));
addThisPerson.CustomCallingContext.AddVoip("myHeader", "myValue");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);
// Invite a PSTN user and set UUI and custom SIP headers
var callerIdNumber = new PhoneNumberIdentifier("+16044561234"); 
var addThisPerson = new CallInvite(new PhoneNumberIdentifier("+16041234567"), callerIdNumber);

// Set custom UUI header. This key is sent on SIP protocol as User-to-User
addThisPerson.CustomCallingContext.AddSipUui("value");

// This provided key will be automatically prefixed with X-MS-Custom on SIP protocol, such as 'X-MS-Custom-{key}'
addThisPerson.CustomCallingContext.AddSipX("header1", "customSipHeaderValue1");
AddParticipantsResult result = await callConnection.AddParticipantAsync(addThisPerson);

Aggiunta di contesto personalizzato durante il trasferimento delle chiamate

//Transfer to communication services user and include one VOIP header
var transferDestination = new CommunicationUserIdentifier("<user_id>"); 
var transferOption = new TransferToParticipantOptions(transferDestination);   
var transferOption = new TransferToParticipantOptions(transferDestination) {
    OperationContext = "<Your_context>",
    OperationCallbackUri = new Uri("<uri_endpoint>") // Sending event to a non-default endpoint.
};
transferOption.CustomCallingContext.AddVoip("customVoipHeader1", "customVoipHeaderValue1");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption);

//Transfer a PSTN call to phone number and set UUI and custom SIP headers
var transferDestination = new PhoneNumberIdentifier("<target_phoneNumber>");
var transferOption = new TransferToParticipantOptions(transferDestination);
transferOption.CustomCallingContext.AddSipUui("uuivalue");
transferOption.CustomCallingContext.AddSipX("header1", "headerValue");
TransferCallToParticipantResult result = await callConnection.TransferCallToParticipantAsync(transferOption)

Lettura del contesto personalizzato da un evento di chiamata in ingresso

AcsIncomingCallEventData incomingEvent = <incoming call event from Event Grid>;
// Retrieve incoming call custom context
AcsIncomingCallCustomContext callCustomContext = incomingEvent.CustomContext;

// Inspect dictionary with key/value pairs
var voipHeaders = callCustomContext.VoipHeaders;
var sipHeaders = callCustomContext.SipHeaders;

// Get SIP UUI header value
var userToUser = sipHeaders["user-To-User"]

// Proceed to answer or reject call as usual

Risorse aggiuntive