Configure os X-headers SIP para agentes com voz

Note

Este artigo descreve as funcionalidades usadas em agentes ou fluxos de agentes alimentados pelo arnês padrão.

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 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

Importante

Os nomes e valores dos cabeçalhos X do SIP devem conter apenas caracteres suportados. Saiba mais sobre os caracteres suportados em Passar dados contextuais entre chamadas.

Configurar os X-headers recebidos

Os X-headers recebidos contêm metadados transmitidos de sistemas de telefonia externos para o seu agente com voz ativada. Para receber e utilizar estes dados, deve configurar um nó Parse Value para extrair a informação do X-header da variável do sistema Conversation.SipXHeader.

Requisitos de Entrada do X-header

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

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

    Note

    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 X-header de saída definido no Copilot Studio pode ser minúsculo ou maiúsculo, 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 X-headers devem estar presentes em Conversation.SipXHeader.

Adicionar Gestão de Variáveis - Nó de Análise de Valor

  1. Navegue até ao 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 de gestão de variáveis, destacando o valor de parsing.

Configurar o nó de Análise de 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ó de valores de análise, mostrando 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 passar dados personalizados ao transferir chamadas para números de telefone externos usando os X-headers de saída. Configure estes cabeçalhos no nó Transferir conversa.

Requisitos de saída do X-header

  • Número máximo: Cinco X-headers 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.

    Note

    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 X-header de saída definido no Copilot Studio pode ser minúsculo ou maiúsculo, 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ó de transferência de conversa

  1. Adiciona um nó de Transferência de conversa ao teu fluxo de tópicos.

  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 X-headers nas propriedades do nó de conversação de transferência

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

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

    Captura de ecrã de um nó de Transferência.

  3. Defina as entradas do X-header. Os nomes dos X-headers de saída são enviados exatamente como os define no nó de conversa de transferência. 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

Siga estas orientações para design de esquemas, gestão de variáveis, tratamento de erros e desempenho ao trabalhar com SIP X-headers nos seus agentes com voz ativada. Saiba mais em Ferramentas, conhecimento, MCP e API.

Design de esquema

  • 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 X-header.

Considerações sobre desempenho

  • Analise os X-headers no início do seu fluxo de conversa.

  • 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 X-headers que chegam

Se os X-headers recebidos não estiverem a funcionar como esperado, reveja os problemas comuns e passos para resolução de problemas.

Valores do X-header não recebidos

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

  • Verifique se o nó de Valor de Análise está configurado com Conversation.SipXHeader.

  • Assegure-se de que a variável está definida para âmbito global se a aceder a partir de vários tópicos.

  • Certifique-se de que não se esperam mais de cinco X-headers, e que os X-headers são os cinco X-headers 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

Se os X-headers de saída não estiverem a funcionar como esperado, reveja estes problemas comuns e os passos de resolução de problemas.

X-headers não foram 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.

  • Assegurar que os valores dos X-headers sejam devidamente atribuídos antes do nó Transferir conversa.

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

Mantenha o seu esquema X-header organizado e atualizado conforme os seus requisitos mudam.

Atualização do esquema do X-header

  • Atualize o exemplo de JSON em Definir esquema JSON para cabeçalhos X para receber novos cabeçalhos X.

  • Confirme e guarde o esquema atualizado.

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

  • Last updated on