Configure cabeçalhos SIP X para agentes com suporte para voz

Este artigo explica como configurar cabeçalhos X do SIP (Protocolo de Iniciação de Sessão) para chamadas de entrada e saída em agentes habilitados para voz do Copilot Studio para uso em Dynamics 365 Contact Center.

Os X-headers SIP permitem que você passe metadados personalizados entre sistemas telefônicos e seus agentes com voz habilitada. Dynamics 365 Contact Center agentes com suporte para voz dão suporte a cabeçalhos X de entrada e saída. Essa configuração permite uma troca de dados fluida durante transferências de chamadas e roteamento.

Pré-requisitos

Configurar os cabeçalhos X recebidos

Os cabeçalhos-X recebidos contêm metadados transmitidos de sistemas telefônicos externos para o seu agente com suporte a voz. Para receber e usar esses dados, você deve configurar um nó Parse Value para extrair informações do X-header da variável Conversation.SipXHeader do sistema.

Requisitos de X-headers recebidos

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

  • Requisito de nomeação: Todos os nomes de X-headers devem começar com x-.

    Note

    No Copilot Studio, todos os cabeçalhos X de entrada devem começar com letras minúsculas x-, mesmo que o sistema externo que envia o cabeçalho X esteja usando uma letra maiúscula X-. O cabeçalho X de saída definido no Copilot Studio pode estar em letras minúsculas ou maiúsculas, dependendo de qual caso o sistema externo está esperando.

  • Comprimento do nome: Até 64 caracteres.

  • Valor de duração: Até 256 caracteres.

  • Um esquema JSON é exigido para todos os X-headers esperados.

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

  • Dependência dos dados do canal: X-headers devem estar presentes em Conversation.SipXHeader.

Adicionar Gerenciamento de Variáveis - Nó de Valor de Análise

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

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

  3. Selecione Gerenciamento de Variáveis e selecione Analisar Valor.

    Captura de tela da opção de gerenciamento de variáveis, destacando o valor do parse.

Configure o nó de Valor de Análise Sintática

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

  2. Defina o tipo de dado como Dos dados de amostra.

  3. Defina a estrutura esperada de X-header selecionando Obter esquema a partir de JSON de exemplo.

    Captura de tela do nó de valores de análise, exibindo os valores de configuração.

Defina esquema JSON para X-headers

Na caixa de diálogo Obter esquema a partir do JSON de exemplo, forneça a estrutura JSON que inclua os nomes dos X-headers que você pretende receber. Por exemplo, se você espera cabeçalhos como X-CallID e X-AAI-Incoming em uma chamada recebida, adicione-os ao seu esquema JSON.

Captura de tela de uma caixa de diálogo de esquema JSON de exemplo.

Selecione Confirmar para aplicar o esquema.

Importante

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

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

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

Mesmo que o sistema externo use maiúsculas X-, 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": ""  
}

Salve os dados analisados

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

    Captura de tela da configuração de propriedades da variável para uso com um X-header SIP.

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

Acesse valores de X-header em seus tópicos

Uma vez configurado, você pode acessar valores individuais do X-header usando notação de pontos, semelhante aos exemplos a seguir:

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

  • IncomingSIPXHeaders.sipXHeader.'X-CallID'

Comportamento de tempo de execução

  • Copilot Studio recebe apenas os cinco primeiros cabeçalhos X enviados pelo sistema externo.

  • Copilot Studio preenche automaticamente o registro com valores de cabeçalho X quando os nomes correspondem ao esquema.

  • Cabeçalhos X ausentes têm valores vazios de string.

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

Configurar os X-headers de saída

Você pode passar dados personalizados ao transferir chamadas para números externos usando cabeçalhos X de saída. Configure esses cabeçalhos no nó Transferir conversa.

Requisitos de emissão do X-header

  • Contagem máxima: Cinco X-headers por transferência.

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

    Note

    No Copilot Studio, todos os cabeçalhos X de entrada devem começar com letras minúsculas x-, mesmo que o sistema externo que envia o cabeçalho X esteja usando uma letra maiúscula X-. O cabeçalho X de saída definido no Copilot Studio pode estar em letras minúsculas ou maiúsculas, dependendo de qual caso o sistema externo está esperando.

  • Comprimento do nome: Até 64 caracteres.

  • Valor de duração: Até 256 caracteres.

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

Configure o nó de conversa de transferência

  1. Adicione um nó Transferência de conversa ao fluxo do seu tópico.

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

Configure X-headers nas propriedades do nó de conversa Transfer

  1. Selecione o ícone Mais (…) do nó de Gatilho e selecione Propriedades.

  2. Selecione + Adicionar para adicionar pares chave-valor X-header.

    Captura de tela de um nó de conversa de transferência.

  3. Defina as entradas do X-header. Os nomes dos X-headers que saem são enviados exatamente como você os define no nó Conversa de Transferência. Escolha o caso apropriado com base no que o sistema receptor espera.

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

    Captura de tela das propriedades da conversa de transferência.

Práticas Recomendadas

Siga estas diretrizes para design de esquema, gerenciamento de variáveis, tratamento de erros e desempenho ao trabalhar com cabeçalhos SIP X em seus agentes habilitados para voz. Saiba mais em Ferramentas, conhecimento, MCP e API.

Design de esquema

  • Use nomes descritivos de cabeçalhos X que indiquem claramente 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 equipe e resolução de problemas.

Manejo de variáveis

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

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

  • Inicialize as variáveis cedo no fluxo da conversa.

Tratamento de erros

  • Sempre verifique a presença de X-header antes de usar valores na sua lógica.

  • Implemente comportamento de contingência para dados de X-header ausentes ou inválidos.

  • Teste cuidadosamente com vários cenários de X-headers.

Considerações sobre desempenho

  • Analise os X-headers logo no início da sua conversa.

  • Cache frequentemente usava valores em variáveis separadas, se necessário.

  • Evite analisar repetidamente os mesmos dados de canal.

Problemas comuns com X-headers entrantes

Se os cabeçalhos X de entrada não estiverem funcionando conforme o esperado, examine esses problemas comuns e as etapas de soluçã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.

  • Garanta que a variável esteja definida para escopo global se for acessada de múltiplos tópicos.

  • Certifique-se de que não sejam esperados mais de cinco X-headers, e que os cinco X-headers principais sejam enviados pelo sistema externo.

Valores vazios ou nulos de X-header

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

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

Problemas comuns com X-headers de saída

Se os cabeçalhos X de saída não estiverem funcionando conforme o esperado, examine esses problemas comuns e as etapas de solução de problemas.

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

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

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

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

Falhas na transferência com X-headers

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

  • Verifique se o sistema receptor é capaz de processar os X-headers enviados.

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

Gerenciamento de esquema

Mantenha seu esquema de cabeçalho X organizado e atualizado conforme seus requisitos são alterados.

Atualização do esquema do X-header

  • Para receber novos X-headers, atualize a amostra JSON no Define JSON schema para X-headers.

  • Confirme e salve o esquema atualizado.

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

  • Last updated on