Usar o SDK de chamada do ACS para passar dados contextuais de UUI (Informações do Usuário para Usuário) entre chamadas
Neste artigo, você vai aprender a transmitir informações contextuais personalizadas ao direcionar chamadas com os SDKs de Chamada dos Serviços de Comunicação do Azure. Essa funcionalidade permite que os usuários transmitam metadados sobre a chamada, o receptor ou qualquer outra informação relevante para o aplicativo ou a lógica de negócios.
O SDK do WebJS do ACS (Serviços de Comunicação do Azure) fornece aos desenvolvedores para incluir 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 de UUI (Informações do Usuário para Usuário) ou dados da interface do usuário do controle de chamada, são uma pequena parte dos dados inseridos por um aplicativo que inicia a chamada. Os dados de UUI são pouco transparentes para os usuários finais que fazem uma chamada.
As informações contextuais com suporte incluem cabeçalhos personalizados e o cabeçalho SIP padrão de Informação de Usuário para Usuário (UUI). Além disso, quando você recebe uma chamada, esses cabeçalhos personalizados e o UUI também são incluídos no conteúdo incomingCall.
Todos os dados de contexto personalizados são opacos para protocolos SIP ou SDK de Chamadas e seu conteúdo não está relacionado a qualquer função básica.
Os desenvolvedores podem passar esse contexto usando cabeçalhos personalizados, que consistem em pares opcionais chave-valor. Esses pares podem ser incluídos nas ações 'AddParticipant' ou 'Transferência' dentro do SDK de chamada. Depois de adicionado, você poderá fazer a leitura da carga de dados à medida que a chamada se move entre os pontos de extremidade. Ao pesquisar com eficiência esses metadados e associá-los à chamada, os desenvolvedores podem evitar pesquisas de banco de dados externos e ter as informações de conteúdo prontamente disponíveis dentro do objeto de chamada.
O contexto de chamada personalizado 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 UUI (Informações do Usuário para Usuário). Quando uma chamada de entrada é roteada da rede de telefonia, os dados do SBC (Controlador de borda da sessão) nos cabeçalhos personalizados e nas UUI também são incluídos no conteúdo 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 ajudar você a adicionar cabeçalhos de contexto personalizados ao usar o SDK do WebJS.
Importante
Para usar a capacidade de passar dados da UUI (Informações do Usuário para Usuário) usando o SDK de chamada, use a chamada de GA do SDK do WebJS ou versão 1.29.1 de visualização pública ou posterior.
Parâmetros técnicos
O SDK de chamada dá suporte à adição de cinco cabeçalhos do SIP personalizados e 1.000 cabeçalhos do VOIP personalizados. Além disso, os desenvolvedores podem incluir um cabeçalho dedicado de usuário para usuário 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. Ao adicionar o cabeçalho do SIP, o SDK de chamada adicionará automaticamente o prefixo 'X-MS-Custom-' (que pode ser visto se você inspecionar o cabeçalho do SIP com o inspetor de pacotes).
A chave de cabeçalho SIP pode consistir em caracteres alfanuméricos e alguns símbolos selecionados, incluindo ., !, %, *, _, +, ~ e -. 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 em seu SBC. O valor do cabeçalho SIP pode consistir em caracteres alfanuméricos e alguns símbolos selecionados, incluindo =, ;, ., !, %, *, _, +, ~ e -.
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ê poderá optar por adicionar apenas cabeçalhos do SIP, apenas cabeçalhos do VoIP ou ambos podem ser incluídos.
Observação
Atualmente, a adição de cabeçalhos personalizados de Informações do Usuário para Usuário só tem suporte ao iniciar uma chamada 1:1. Atualmente, não há suporte para a passagem de cabeçalhos de Informações do Usuário para Usuário em chamadas de grupo. Para contornar isso depois de iniciar a chamada 1:1, você poderá incluir participantes adicionais, mantendo as Informações do Usuário para Usuário dentro das chamadas.
Para obter detalhes sobre a API de interface de contexto personalizado, consulte a página de recursos da API de contexto personalizado.
Posicionar uma chamada com dados de UUI (Informações do 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',
},
};
});
Fazer a leitura e analisar cabeçalhos de Informações do Usuário para Usuário em uma chamada
A instância callAgent emite um evento incomingCall quando a identidade registrada recebe uma chamada de entrada. Para escutar esse 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`);
}
}
});