SIP X-Header für sprachgesteuerte Agenten konfigurieren

In diesem Artikel wird erläutert, wie Sie X-Header (Session Initiation Protocol, SIP) für eingehende und ausgehende Anrufe in Copilot Studio-VoIP-fähigen Agents für die Verwendung in Dynamics 365 Contact Center konfigurieren.

SIP X-Header ermöglichen es Ihnen, benutzerdefinierte Metadaten zwischen Telefonsystemen und Ihren sprachgesteuerten Agenten zu übertragen. Dynamics 365 Contact Center sprachfähige Agenten unterstützen sowohl eingehende als auch ausgehende X-Header. Diese Konfiguration ermöglicht einen nahtlosen Datenaustausch während Gesprächsübertragungen und Routings.

Voraussetzungen

• Dynamics 365 Contact Center mit aktivierten sprachfähigen Agents

• Copilot Studio-Zugriff mit entsprechenden Berechtigungen

• Direktes Routing für die Telefoniekonfiguration

• Grundlegendes Verständnis von Copilot Studio topic Creation und variable Management

Eingehende X-Header konfigurieren

Eingehende X-Header enthalten Metadaten, die von externen Telefonsystemen an Ihren sprachgesteuerten Agenten übertragen werden. Um diese Daten zu empfangen und zu verwenden, müssen Sie einen Parse-Value-Knoten konfigurieren, um X-Header-Informationen aus der Conversation.SipXHeader Systemvariablen zu extrahieren.

Eingehende X-Header-Anforderungen

• Maximale Anzahl: Fünf X-Header pro eingehendem Anruf.

• Benennungsvoraussetzung: Alle X-Header-Namen müssen mit x-beginnen.

  Hinweis

  In Copilot Studio müssen alle eingehenden X-Header mit Kleinbuchstaben x- beginnen, auch wenn das externe System, das den X-Header sendet, einen Großbuchstaben X- verwendet. Der in Copilot Studio definierte ausgehende X-Header kann entweder in Klein- oder Großbuchstaben sein, je nach Anforderung des externen Systems.

• Namenslänge: Bis zu 64 Zeichen.

• Wertlänge: Bis zu 256 Zeichen.

• Für alle erwarteten X-Header ist ein JSON-Schema erforderlich.

• Aktualisieren Sie das JSON-Schema, wenn sich X-Header-Namen ändern.

• Kanaldatenabhängigkeit: X-Header müssen in Conversation.SipXHeadervorhanden sein.

Variablenverwaltung hinzufügen – Parse-Value-Knoten

1. Navigiere zum Thema deines sprachgesteuerten Agenten.

2. Fügen Sie einen neuen Themenknoten hinzu.

3. Wählen Sie die Option Variablenverwaltung und Wert analysieren.

   

Konfigurieren Sie den Wert-Analysierknoten

1. Im Systemmenü setzen Sie das Parse-Wertfeld auf Conversation.SipXHeader.

2. Setze den Datentyp auf Aus Beispieldaten.

3. Definiere die erwartete X-Header-Struktur, indem du Get-Schema aus Beispiel-JSON auswählst.

   

Definiere das JSON-Schema für X-Header

Im Dialog Schema aus Beispiel-JSON abrufen geben Sie die JSON-Struktur an, die die X-Header-Namen enthält, die Sie erwarten. Wenn du zum Beispiel Header wie X-CallID und X-AAI-Incoming in einem eingehenden Anruf erwartest, füge sie deinem JSON-Schema hinzu.

Wählen Sie Bestätigen, um das Schema anzuwenden.

Beispiel-JSON für X-Header

{

"x-CallID": "",

"x-AAI-Incoming": ""  
}

Speichere die geparsten Daten

1. Erstellen oder Auswählen Sie eine Variable im Feld 'Speichern als' (zum Beispiel IncomingSipXHeader).

   

2. Setze den Umfang der Variablen auf Global , um Zugriff auf mehrere Themen in deinem Agenten zu ermöglichen.

Zugriff auf X-Header-Werte in deinen Themen

Nach der Konfiguration können Sie einzelne X-Header-Werte mittels Punktnotation aufrufen, ähnlich wie in den folgenden Beispielen:

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

• IncomingSIPXHeaders.sipXHeader.'X-CallID'

Laufzeitverhalten

• Copilot Studio empfängt nur die ersten fünf X-Header, die vom externen System gesendet werden.

• Copilot Studio füllt den Datensatz automatisch mit X-Header-Werten auf, wenn Namen dem Schema entsprechen.

• Fehlende X-Header haben leere String-Werte.

• Schema-Updates sind erforderlich, wenn sich X-Header-Namen ändern oder wenn Sie zusätzliche Header erhalten möchten.

Konfigurieren Sie ausgehende X-Header

Sie können benutzerdefinierte Daten übergeben, wenn Sie Anrufe über ausgehende X-Header an externe Telefonnummern weiterleiten. Konfigurieren Sie diese Header im Transfer Conversation-Knoten.

Anforderungen an ausgehende X-Header

• Maximale Anzahl: Fünf X-Header pro Übertragung.

• Benennungsanforderung: Alle X-Header-Namen können je nach erwartetem Fall mit X- oder x- beginnen.

  Hinweis

  In Copilot Studio müssen alle eingehenden X-Header mit Kleinbuchstaben x- beginnen, auch wenn das externe System, das den X-Header sendet, einen Großbuchstaben X- verwendet. Der in Copilot Studio definierte ausgehende X-Header kann entweder in Klein- oder Großbuchstaben sein, je nach Anforderung des externen Systems.

• Namenslänge: Bis zu 64 Zeichen.

• Wertlänge: Bis zu 256 Zeichen.

• Übertragungsart: Nur für die Übertragung externer Telefonnummern verfügbar.

Richte den Transfer-Konversationsknoten ein

1. Füge einen Übertragungsgesprächsknoten in deinen Themenfluss ein.

2. Wählen Sie unter Weiterleitungsart die Option Externe Rufnummernweiterleitung aus und geben Sie die Weiterleitungsnummer ein. Zum Beispiel +18005551212.

Konfigurieren Sie X-Header in den Eigenschaften des Transfer-Gesprächsknotens

1. Symbol Mehr im (…) des Knotens auswählen und dann Eigenschaften auswählen.

2. Wählen + Hinzufügen , um Schlüssel-Wert-Paare im X-Header hinzuzufügen.

   

3. Definiere die X-Header-Einträge. Ausgehende X-Header-Namen werden genau so gesendet, wie du sie im Übertragungs-Konversationsknoten definiert hast. Wählen Sie den passenden Fall basierend auf den Erwartungen des empfangenden Systems.

   • Schlüsselname: Muss mit X- oder x- beginnen (zum Beispiel X-AAI-Outgoing oder X-CallID)
   • Wert: Geben Sie einen statischen Wert ein oder weisen Sie eine Variable zu

   

Bewährte Methoden

Schemaentwurf

• Verwenden Sie beschreibende X-Header-Namen, die ihren Zweck klar angeben.

• Halte das JSON-Schema aktuell, wenn sich die Anforderungen des X-Headers ändern.

• Dokumentiere dein X-Header-Schema für Teamreferenz und Fehlersuche.

Variablenmanagement

• Verwenden Sie globale Variablen für X-Header-Daten, die themenübergreifend abgerufen werden müssen.

• Wähle sinnvolle Variablennamen (zum Beispiel IncomingSIPXHeaders oder CustomerXHeaders).

• Initialisieren Sie Variablen früh in Ihrem Gesprächsfluss.

Fehlerbehandlung

• Überprüfe immer die Präsenz eines X-Headers, bevor du Werte in deiner Logik verwendest.

• Implementiere Rückfallverhalten für fehlende oder ungültige X-Header-Daten.

• Teste gründlich mit verschiedenen X-Header-Szenarien.

Leistungsüberlegungen

• Analysiere X-Header früh in deinem Gesprächsfluss.

• Cache verwendete bei Bedarf häufig Werte in separaten Variablen.

• Vermeiden Sie wiederholtes Parsen derselben Kanaldaten.

Häufige Probleme mit eingehenden X-Headern

X-Header-Werte nicht empfangen

• Überprüfen Sie, ob das JSON-Schema exakt mit den erwarteten X-Header-Namen übereinstimmt.

• Überprüfen Sie, ob der Parse-Value-Knoten mit Conversation.SipXHeader konfiguriert ist.

• Stelle sicher, dass die Variable auf globalen Umfang gesetzt ist, wenn sie von mehreren Themen aus abgerufen wird.

• Stellen Sie sicher, dass nicht mehr als fünf X-Header erwartet werden und dass dies die fünf am häufigsten vom externen System gesendeten X-Header sind.

Leere oder nulle X-Header-Werte

• Bestätigen Sie, dass das externe System X-Header mit den erwarteten Namen sendet.

• Überprüfen Sie, dass das JSON-Schema alle erforderlichen X-Header-Namen mit einem kleinen x- Präfix enthält.

Häufige Probleme mit ausgehenden X-Headern

Nicht gesendete X-Header während der Übertragung

• Überprüfen Sie, dass alle X-Header-Namen mit X- oder x-beginnen.

• Stellen Sie sicher, dass der Übertragungstyp auf Externe Telefonnummernübertragung gesetzt ist.

• Stellen Sie sicher, dass X-Header-Werte vor dem Übertragungs-Konversationsknoten korrekt zugewiesen sind.

Übertragung scheitert mit X-Headern

• Bestätigen Sie, dass die Namen und Werte der X-Header die Längenbegrenzungen nicht überschreiten.

• Überprüfen Sie, ob das empfangende System die gesendeten X-Header verarbeiten kann.

• Prüfe auf Spezialzeichen, die Parsing-Probleme verursachen könnten.

Schemaverwaltung

Aktualisierung des X-Header-Schemas

• Um neue X-Header zu erhalten, aktualisieren Sie die JSON-Probe in Define JSON schema for X-headers.

• Bestätigen und speichern Sie das aktualisierte Schema.

• Teste das Schema mit der neuen X-Header-Konfiguration.