Usando o SDK de chamada do ACS para passar dados contextuais de informações de usuário para usuário (UUI) entre chamadas
Neste artigo, você aprenderá a passar informações contextuais personalizadas ao rotear chamadas com SDKs de Chamada dos Serviços de Comunicação do Azure. Esse recurso permite que os usuários passem metadados sobre a chamada, o destinatário ou qualquer outra informação que seja relevante para seu aplicativo ou lógica de negócios.
O SDK WebJS dos Serviços de Comunicação do Azure (ACS) fornece aos desenvolvedores a inclusão de dados contextuais personalizados (incluídos como um cabeçalho no objeto de chamada) ao direcionar e rotear chamadas de uma pessoa para outra. Essas informações, também conhecidas como dados UUI (User-to-User Information) ou dados UUI de controle de chamada, são um pequeno pedaço de dados inseridos por um aplicativo que inicia a chamada. Os dados UUI são opacos para os usuários finais que fazem uma chamada.
As informações contextuais suportadas incluem cabeçalhos personalizados de forma livre e o cabeçalho SIP padrão de informações de usuário para usuário (UUI). Além disso, quando você recebe uma chamada de entrada, os cabeçalhos personalizados e a UUI são incluídos na carga incomingCall.
Todos os dados de contexto personalizados são opacos para chamar protocolos SDK ou SIP e seu conteúdo não está relacionado a nenhuma função básica.
Os desenvolvedores podem passar esse contexto usando cabeçalhos personalizados, que consistem em pares chave-valor opcionais. Esses pares podem ser incluídos nas ações 'AddParticipant' ou 'Transfer' dentro do SDK de chamada. Uma vez adicionado, você pode ler a carga útil de dados à medida que a chamada se move entre os pontos de extremidade. Ao pesquisar eficientemente esses metadados e associá-los à chamada, os desenvolvedores podem evitar pesquisas de banco de dados externo e ter as informações de conteúdo prontamente disponíveis dentro do objeto de chamada.
O contexto de chamada personalizada pode ser transmitido para pontos de extremidade SIP usando o protocolo SIP. Essa transmissão inclui os cabeçalhos personalizados e o cabeçalho SIP padrão de informações do usuário para usuário (UUI). Quando uma chamada de entrada é roteada da sua rede de telefonia, os dados do seu Controlador de Borda de Sessão (SBC) nos cabeçalhos personalizados e UUI também são incluídos na carga útil do evento IncomingCall.
É importante observar que todos os dados de contexto personalizados permanecem transparentes para o SDK de chamada e não estão relacionados a nenhuma das funções fundamentais do SDK quando usados em protocolos SIP. Aqui está um tutorial para ajudá-lo a adicionar cabeçalhos de contexto personalizados ao usar o SDK WebJS.
Importante
Para usar a capacidade de passar dados de informações de usuário para usuário (UUI) usando o SDK de chamada, você deve usar a chamada 1.29.1 WebJS, SDK, GA, ou versão de visualização pública ou posterior.
Parâmetros técnicos
O SDK de chamada suporta a adição de até 5 cabeçalhos SIP personalizados e 1000 cabeçalhos VOIP personalizados. Além disso, os desenvolvedores podem incluir um cabeçalho User-To-User dedicado como parte da lista de cabeçalhos SIP.
O comprimento máximo de uma chave de cabeçalho SIP é de 64 caracteres, incluindo o prefixo X-MS-Custom. Observe que, quando o cabeçalho SIP é adicionado, o SDK de chamada adicionará automaticamente o prefixo 'X-MS-Custom-' (que pode ser visto se você inspecionar o cabeçalho SIP com o inspetor de pacotes).
A chave de cabeçalho SIP pode consistir em caracteres alfanuméricos e alguns símbolos selecionados que incluem , , , , *, _, +, ~. -%!. O comprimento máximo do valor do cabeçalho SIP é de 256 caracteres. As mesmas limitações se aplicam ao configurar os cabeçalhos SIP no SBC. O valor do cabeçalho SIP pode consistir em caracteres alfanuméricos e alguns símbolos selecionados que incluem =, ;, ., !, , %*, _, +, ~, . -
O comprimento máximo de uma chave de cabeçalho VOIP é de 64 caracteres. O comprimento máximo do valor do cabeçalho VOIP é de 1024 caracteres.
Ao adicionar esses cabeçalhos personalizados como desenvolvedor, você pode optar por adicionar apenas cabeçalhos SIP, apenas cabeçalhos VoIP ou ambos podem ser incluídos.
Nota
Atualmente, a adição de cabeçalhos personalizados de informações de usuário para usuário só é suportada ao iniciar uma chamada 1:1. Atualmente, não há suporte para a passagem de cabeçalhos de informações de usuário para usuário em chamadas em grupo. Para contornar isso depois de iniciar a chamada 1:1, você pode incluir participantes adicionais enquanto mantém as informações de usuário para usuário nas chamadas.
Para obter detalhes sobre a API da interface de contexto personalizada, consulte a página de recursos da API de contexto personalizado.
Fazer uma chamada com dados UUI (Informações de Usuário para Usuário)
// Setting custom context UUI Headers
const callOptions = {
customContext: {
voipHeaders: [
{key: 'voip-key-1', value: 'voip-value-1'},
{key: 'voip-key-2', value: 'voip-value-2'}
],
sipHeaders: [
{key: 'sip-key-1', value: 'sip-value-1'},
{key: 'sip-key-2', value: 'sip-value-2'}
],
userToUser: 'userToUserHeader',
},
};
});
Ler e analisar cabeçalhos de informações de usuário para usuário em uma chamada
A callAgent instância emite um incomingCall evento quando a identidade conectada recebe uma chamada de entrada. Para ouvir este evento e extrair informações contextuais, inscreva-se usando uma destas opções:
let info = '';
callAgent.on("incomingCall", (args) => {
const incomingCall = args.incomingCall;
if (incomingCall.customContext) {
if (incomingCall.customContext.userToUser) {
info += `userToUser: '${incomingCall.customContext.userToUser}'\n`;
}
if (incomingCall.customContext.sipHeaders) {
incomingCall.customContext.sipHeaders.forEach(header => info += `sip: ${header.key}: '${header.value}'\n`);
}
if (incomingCall.customContext.voipHeaders) {
incomingCall.customContext.voipHeaders.forEach(header => info += `voip: ${header.key}: '${header.value}'\n`);
}
}
});