Passar dados de informações de utilizador para utilizador (UUI) num cabeçalho

Este artigo descreve como passar informações de utilizador para utilizador (UUI) num cabeçalho ao rotear chamadas com os SDKs de Chamadas dos Serviços de Comunicação 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 permite que os desenvolvedores incluam 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 (informações de usuário para usuário) 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 UUI padrão. Além disso, quando você recebe uma chamada de entrada, os cabeçalhos personalizados e a incomingCall UUI são incluídos na carga.

Todos os dados de contexto personalizados são opacos para os protocolos de chamada SDK ou SIP e o 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 chave-valor opcionais. Esses pares podem ser incluídos nas ações AddParticipant ou Transfer dentro do SDK de chamadas. Uma vez adicionado, é possível ler a carga de dados à medida que a chamada se desloca entre os endpoints. 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 através do protocolo SIP. Essa transmissão inclui os cabeçalhos personalizados e o cabeçalho SIP UUI padrão. Quando uma chamada de entrada é encaminhada da sua rede de telefonia, os dados do seu Controlador de Borda de Sessão (SBC) nos cabeçalhos personalizados e na 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.

Parâmetros técnicos

O SDK de chamada suporta a adição de até cinco (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. Quando você adiciona o cabeçalho SIP ao SDK de chamada, ele adiciona automaticamente o prefixo X-MS-Custom- , que você pode ver inspecionando 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 controlador de borda de sessão (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.

Para obter detalhes sobre a API de interface de contexto personalizada, consulte Recurso de API de contexto personalizado.

Fazer uma chamada com dados UUI (Informações de Utilizador para Utilizador)

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

Próximos passos

• Saiba como gerir chamadas
• Saiba como gerir vídeos
• Saiba como gravar chamadas
• Saiba como transcrever chamadas