Partilhar via

Configurar os cabeçalhos X SIP para agentes com capacidade de voz

Este artigo explica como configurar os X-headers do Protocolo de Iniciação de Sessão (SIP) para chamadas recebidas e saídas em agentes com voz do Copilot Studio para utilização no Dynamics 365 Contact Center.

Os SIP X-headers permitem-lhe passar metadados personalizados entre sistemas de telefonia e os seus agentes com voz. Os agentes com capacidade de voz do Dynamics 365 Contact Center suportam cabeçalhos X, tanto de entrada como de saída. Esta configuração permite uma troca de dados fluida durante as transferências de chamadas e o encaminhamento.

Pré-requisitos

Configurar os X-headers recebidos

Os cabeçalhos X de entrada contêm metadados transmitidos de sistemas de telefonia externos para o seu agente com capacidade de voz ativada. Para receber e usar estes dados, tem de configurar um nó Analisar Valor para extrair informações do cabeçalho X da variável do sistema Conversation.SipXHeader.

Requisitos do cabeçalho X de entrada

  • Contagem máxima: Cinco X-headers por chamada recebida.

  • Requisito de nomenclatura: Todos os nomes dos X-headers devem começar por x-.

    Observação

    No Copilot Studio, todos os X-headers recebidos devem começar com minúsculas x-, mesmo que o sistema externo que envia o X-header esteja a usar maiúsculas X-. O cabeçalho X de saída definido no Copilot Studio pode estar em minúsculas ou maiúsculas, dependendo do formato que o sistema externo espera.

  • Comprimento do nome: Até 64 caracteres.

  • Valor de comprimento: Até 256 caracteres.

  • É necessário um esquema JSON para todos os X-headers esperados.

  • Atualize o esquema JSON quando os nomes dos X-headers mudarem.

  • Dependência dos dados do canal: os cabeçalhos X têm de estar presentes em Conversation.SipXHeader.

Adicionar Gestão de Variáveis – Nó Analisar Valor

  1. Navegue para o tópico do seu agente com voz ativada.

  2. Adicione um novo nó de tópico.

  3. Selecione Gestão de variáveis e selecione Analisar valor.

    Captura de ecrã da opção Gestão de variáveis, com destaque para Analisar valor.

Configurar o nó Analisar Valor

  1. No menu do Sistema , defina o campo de valor de análise para Conversation.SipXHeader.

  2. Defina o tipo de dados para Com base nos dados de amostra.

  3. Defina a estrutura esperada do X-header selecionando Get schema from sample JSON.

    Captura de ecrã do nó Analisar valor, apresentando os valores de configuração.

Defina esquema JSON para X-headers

No diálogo Obter esquema a partir de amostra JSON, forneça a estrutura JSON que inclui os nomes dos X-headers que espera receber. Por exemplo, se esperar cabeçalhos como X-CallID e X-AAI-Incoming numa chamada recebida, adicione-os ao seu esquema JSON.

Captura de ecrã de uma caixa de diálogo de esquema JSON de exemplo.

Selecione Confirmar para aplicar o esquema.

Importante

A plataforma Dynamics 365 Contact Center normaliza sempre os nomes dos cabeçalhos X para usar um prefixo minúsculo x-, independentemente de como o sistema externo os envia. Isto significa:

  • Se o sistema externo enviar X-CallID, deve defini-lo como x-CallID no seu esquema.

  • Se o sistema externo enviar X-AAI-Incoming, deve defini-lo como x-AAI-Incoming no seu esquema.

Mesmo que o sistema externo possa usar maiúsculas X-, o seu esquema deve sempre usar minúsculas x- para que a plataforma possa mapear e processar corretamente os cabeçalhos.

Exemplo de JSON para X-headers

{

"x-CallID": "",

"x-AAI-Incoming": ""  
}

Guardar os dados analisados

  1. Crie ou selecione uma variável no campo Guardar como (por exemplo, IncomingSipXHeader).

    Captura de ecrã da configuração das propriedades das variáveis para uso com um X-header SIP.

  2. Defina o âmbito da variável para Global para permitir o acesso a vários tópicos no seu agente.

Aceda aos valores X-header nos seus tópicos

Uma vez configurado, pode aceder a valores individuais dos X-headers usando notação de pontos, semelhante aos seguintes exemplos:

  • Global.IncomingSipXHeader.'x-AAI-Incoming'

  • IncomingSIPXHeaders.sipXHeader.'X-CallID'

Comportamento de tempo de execução

  • O Copilot Studio recebe apenas os primeiros cinco X-headers enviados pelo sistema externo.

  • O Copilot Studio preenche automaticamente o registo com valores de X-header quando os nomes correspondem ao esquema.

  • Os X-headers em falta têm valores de string vazios.

  • Atualizações de esquemas são necessárias quando os nomes dos X-headers mudam, ou se quiser receber cabeçalhos extra.

Configurar os X-headers de saída

Pode transmitir dados personalizados ao transferir chamadas para números de telefone externos através de cabeçalhos X de saída. Configure os cabeçalhos no nó Transferir conversação.

Requisitos de saída do X-header

  • Número máximo: cinco cabeçalhos X por transferência.

  • Requisito de nomenclatura: Todos os nomes de cabeçalhos X podem começar por X- ou x-, dependendo do caso que o sistema externo espera.

    Observação

    No Copilot Studio, todos os X-headers recebidos devem começar com minúsculas x-, mesmo que o sistema externo que envia o X-header esteja a usar maiúsculas X-. O cabeçalho X de saída definido no Copilot Studio pode estar em minúsculas ou maiúsculas, dependendo do formato que o sistema externo espera.

  • Comprimento do nome: Até 64 caracteres.

  • Valor de comprimento: Até 256 caracteres.

  • Tipo de transferência: Disponível apenas para transferência externa de número de telefone.

Configurar o nó Transferir conversação

  1. Adiciona um nó Transferir conversação ao fluxo do tópico.

  2. Em Tipo de transferência, selecione Transferência de número de telefone externo e introduza o número de transferência. Por exemplo, +18005551212.

Configurar cabeçalhos X nas propriedades do nó Transferir conversação

  1. Selecione o ícone Mais (...) do nó e, em seguida, selecione Propriedades.

  2. Selecione + Adicionar para adicionar pares chave-valor de cabeçalho X.

    Captura de ecrã de um nó Transferir conversação.

  3. Defina as entradas do cabeçalho X. Os nomes de cabeçalhos X de saída são enviados exatamente como os define no nó Transferir conversação. Escolha o caso apropriado com base no que o sistema recetor espera.

    • Nome-chave: Deve começar por X- ou x- (por exemplo, X-AAI-Outgoing ou X-CallID)
    • Valor: Introduza um valor estático ou atribua uma variável

    Captura de ecrã das propriedades da conversa de Transferência.

Melhores práticas

Design dos esquemas

  • Use nomes descritivos de cabeçalhos X que indiquem claramente o seu propósito.

  • Mantenha o esquema JSON atualizado quando os requisitos dos X-headers mudarem.

  • Documente o esquema do seu X-header para referência da equipa e resolução de problemas.

Gestão de variáveis

  • Use variáveis globais para dados X-header que precisam de ser acessados entre diferentes tópicos.

  • Escolha nomes de variáveis significativas (por exemplo, IncomingSIPXHeaders ou CustomerXHeaders).

  • Inicializa as variáveis cedo no fluxo da tua conversa.

Tratamento de erros

  • Verifica sempre a presença do X-header antes de utilizares valores na tua lógica.

  • Implemente comportamento de fallback para dados do X-header em falta ou inválidos.

  • Teste exaustivamente com vários cenários de cabeçalho X.

Considerações sobre desempenho

  • Analise os cabeçalhos X no início do seu fluxo de conversação.

  • A cache usa frequentemente valores em variáveis separadas, se necessário.

  • Evite a análise repetida dos mesmos dados do canal.

Problemas comuns com os cabeçalhos X de entrada

Valores do X-header não recebidos

  • Verifique se o esquema JSON corresponde exatamente aos nomes esperados dos X-headers.

  • Verifique se o nó Analisar Valor está configurado com Conversation.SipXHeader.

  • Garante que a variável está definida para âmbito global se for acedida a partir de vários tópicos.

  • Certifique-se de que não são esperados mais de cinco cabeçalhos X, e que os cabeçalhos X são os cinco cabeçalhos X principais enviados pelo sistema externo.

Valores vazios ou nulos de X-headers

  • Confirme que o sistema externo está a enviar os X-headers com os nomes esperados.

  • Verifique se o esquema JSON inclui todos os nomes de X-headers necessários com um prefixo minúsculo x- .

Problemas comuns com os X-headers de saída

Cabeçalhos X não enviados durante a transferência

  • Verifique se todos os nomes dos X-headers começam por X- ou x-.

  • Certifique-se de que o tipo de transferência está definido como Transferência de número de telefone externo.

  • Certifique-se de que os valores de cabeçalhos X estão devidamente atribuídos antes do nó Transferir conversação.

A transferência falha com os X-headers

  • Confirme que os nomes e valores dos X-headers não excedem os limites de comprimento.

  • Verifique se o sistema recetor consegue lidar com os X-headers enviados.

  • Verifica se há personagens especiais que possam causar problemas de análise sintática.

Gestão de esquemas

Atualização do esquema do X-header

  • Para receber novos X-headers, atualize o exemplo de JSON em Definir esquema JSON para X-headers.

  • Confirme e guarde o esquema atualizado.

  • Teste o esquema com a nova configuração do X-header.

  • Last updated on