Integratie van POST-berichten met MAX

POST-berichten gebruiken voor IFrame-integratie

Om geavanceerde desktop-integraties mogelijk te maken, ondersteunt de MAX-agentclient (My Agent eXperience) gebeurtenisabonnementen door middel van aangepaste ingesloten webpagina's. MAX kan (IFrame) webpagina's insluiten met behulp van Contactpanelen (die worden geopend en gesloten samen met het bijbehorende contact) of Aangepaste werkruimten (die altijd open en beschikbaar blijven, ongeacht de individuele contacten). Een veelvoorkomende toepassing voor Contactpanelen is het openen van een klantspecifieke CRM-webpagina in een schermpopup bij een telefoongesprek (die na afloop van het gesprek wordt gesloten). Een veelgebruikte toepassing voor Aangepaste werkruimten is een pagina van een kennisbank of een andere website die niet rechtstreeks is gekoppeld aan een contact of een klantinteractie.

In beide gevallen (Contactpaneel of Aangepaste werkruimte) kan de ingesloten 'onderliggende' webpagina een abonnement nemen op systeemgebeurtenissen die door het 'bovenliggende' MAX-venster worden ontvangen via POST-berichten. MAX ontvangt regelmatig informatie van het ACD-platform met gegevens over de agentstatus of over individuele contacten. Door een abonnement op deze 'gebeurtenissen' te nemen, kan de webpagina in het IFrame speciale logica implementeren die reageert op activiteiten in MAX. Als de status van een agent bijvoorbeeld van Beschikbaar wijzigt naar Aan het werk, en van Aan het werk naar Niet beschikbaar, kan de aangepaste webpagina hierop reageren op basis van bepaalde bedrijfsregels. En wanneer er een nieuwe oproep binnenkomt, kan de webpagina op de hoogte worden gebracht van de nieuwe oproep en daarop reageren. Zie voor meer informatie de aanvullende documentatie op https://developer.niceincontact.com/API, https://developer.niceincontact.com/Documentation/AgentSessionEvents en https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage.

Gegevensobjectvariabelen

MAX kan POST-berichten van de klant ontvangen in een gegevensobject met de onderstaande waarden. Alle sleutels van deze eigenschappen zijn hoofdlettergevoelig. Waar dit wordt vermeld, zijn ook de waarden hoofdlettergevoelig.

• contactCardData – Dit is het gegevensobject dat de naam van de klant en de afbeelding van het telefooncontact bevat. Dit object heeft twee sleutels: name en userImg. Deze vergelijking is hoofdlettergevoelig.
• contactId – Dit is een optioneel nummer. Als u de contact-ID kent, kunt u deze hier opgeven. Als u de contact-ID niet weet en het contact is geladen in een contactpaneel, dan vinden we de contact-ID van het bijbehorende paneel. Algemene aangepaste werkruimten hebben geen contact-ID's die op deze manier kunnen worden gevonden, dus ze moeten worden ingevuld als u een contact-specifiek item wilt verwerken.
• issuer – Dit is een optionele string. Deze string functioneert als identificatie voor de afzender, hoewel de waarde niet uniek hoeft te zijn. Deze string helpt bij de logboekregistratie om context toe te voegen aan consolelogboeken. Tijdens het testen merkt u misschien dat uw listener voor POST-berichten het registratiebericht ophaalt dat u stuurt. U kunt dit veld gebruiken om te controleren of het bericht van u afkomstig is. MAX stuurt antwoordgebeurtenissen met 'MAX' als issuer.
• messageType – Dit is een vereiste string. Deze vergelijking is hoofdlettergevoelig. Dit zijn de geldige waarden:

  Waarde	Resultaat
  "RegisterForClientEvents"	Hierdoor weet MAX dat u een client-gebeurtenisabonnement wilt configureren.
  "UnregisterFromClientEvents"	Hiermee ontkoppelt u de vensterreferentie van MAX en beëindigt u het verzenden van client-gebeurtenissen. Als u de abonnementstypen of de contactID wilt wijzigen, moet u dit aanroepen en daarna u een nieuwe registratie uitvoeren. Als u dit niet doet en hetzelfde venster met een nieuwe registratie gebruikt in het contactpaneel, zal dit tot fouten leiden.
  "ContactCardData"	Hierdoor weet MAX dat de naam en de afbeelding van het telefooncontact worden opgehaald.

• subscriptionTypes – Dit is een vereiste array van strings. Dit is niet hoofdlettergevoelig, omdat alles in de array wordt genormaliseerd naar kleine letters. De waarden in de array zijn additief. Elke optie specificeert een type bericht dat u zult ontvangen. Dit zijn de geldige waarden:

  Waarde	Resultaat
  "all"	Retourneert alles.
  "agent"	Retourneert alles wat geen contact-ID heeft.
  "contact"	Retourneert gebeurtenissen met betrekking tot de opgegeven contact-ID, of met betrekking tot de contact-ID voor het bijbehorende paneel als het IFrame is gekoppeld aan een skill of een contact.
  "contacts"	Retourneert alle gebeurtenissen die een contact-ID hebben. Als u zich in een contactpanel bevindt en aanvullende informatie wilt opvragen over het contact van het paneel, voegt u dit veld toe.
  "sessioninfo"	Retourneert het sessietoken van een agent. Als u specifieke API-aanroepen voor een agentsessie wilt uitvoeren, registreert u zich voor deze gebeurtenis.

Wanneer MAX het abonnement ontvangt, samen met het bevestigingsbericht, verzenden we de huidige statussen van de gevraagde abonnementstypen om te helpen de werkruimte op de juiste manier in te stellen. Deze gebeurtenissen zijn gegarandeerd bij aanvang.

Waarde	Huidige statussen
"all"	Retourneert de huidige AgentState en alle huidige contacten binnen de scope van MAX.
"agent"	Retourneert de huidige AgentState. Dit omvat niet het sessietoken van de agent.
"contact"	Retourneert de huidige contactstatus als het contact bestaat binnen de scope van MAX.
"contacts"	Retourneert alle huidige contacten binnen de scope van MAX.

Het kan zijn dat de registratie af en toe meer ontvangt dan de basis AgentState en contacten bij de initialisatie. Deze geldt mogelijk voor de gebeurtenissen AgentLegEvent, AgentSessionStart en MchAgentSettingsChangeEvent. U ziet deze extra gebeurtenissen als uw abonnementsaanvraag binnenkomt voordat we onze lokale verwijzingen naar deze gegevens hebben bepaald. Als dit gebeurt, zullen we alle gebeurtenissen opslaan en doorsturen die naar MAX worden gestuurd tijdens de get-next-event, zoals u tijdens normaal gebruik zou ontvangen. Het enige verschil is dat we niet in staat zijn om de geselecteerde kerngebeurtenissen te selecteren voor een basisinitialisatie. Dezelfde filters zijn van toepassing op de gegevens waarvoor u bent geregistreerd, dus er zouden geen afwijkende resultaten moeten zijn.

Oproepopdrachten

Als MAX in een geldige status is om de gegeven opdracht te accepteren, zal de betreffende actie in de applicatie worden aangeroepen. Deze opdrachten sluiten nauw aan bij de primaire knoppen voor contactafhandeling. Ze sturen geen berichten terug.

Waarde	Resultaat
AnswerEvent, RefuseEvent	Vindt plaats wanneer er een inbound oproep is met het dialoogvenster Accepteren/weigeren.
HoldEvent, MuteEvent, MaskEvent	Werken als aan/uit-schakelaars. Roep bijvoorbeeld Hold één keer aan om de oproep in de wachtstand te zetten, en nog een keer om de oproep weer te herstellen.
RecordEvent	Dit is een eenmalige actie. Nadat bijvoorbeeld Record is aangeroepen, kan dit niet worden gestopt.
HangupEvent	De oproep wordt onmiddellijk beëindigd, zonder bevestigingsvenster.

Voorbeeldgesprek (alleen meldingstype nodig)

opener.postMessage({ messageType: 'MuteEvent' }, '');*

Voorbeeld van implementatie

// Vind het bovenliggende venster (MAX) om te registreren voor gebeurtenissen

var opener = window.opener || window.parent;

// Stel de abonnementen in

var subscriptionTypes = ['agent', 'contacts'];

 

// Begin te luisteren naar antwoordberichten

var doSomething = function (events) {

spacevar event = null;

space var eventIndex = null;

space for(eventIndex in events){

spacespace if (events.hasOwnProperty(eventIndex)){

spacespacespaceevent = events[eventIndex];

spacespace }

space }

};

var listenForPostMessage = function (event) {

if (event.data && event.data.events && event.data.issuer === 'MAX') {

logToConsole('=== received a post message with [' + event.data.events.length + '] events ===');

doSomething(event.data.events);

}

};

// Voeg de listener toe voor MAX-clientgebeurtenissen.

window.addEventListener('message', listenForPostMessage);

// Stuur het registratiebericht naar MAX

opener.postMessage({ contactId: contactId, issuer: 'MyTestSite', messageType: 'Register-ForClientEvents', subscriptionTypes: subscriptionTypes }, '*');

Het antwoordobject

Het antwoordobject

{

issuer: 'MAX',

contactId: int (Nullable) – De contact-ID die als permanent paneel is gevonden of die is doorgegeven. Dit is null als er geen contact-ID is gevonden of doorgegeven.

events: [ object, object, object ... ] – Alle gebeurtenissen die zijn geretourneerd in deze set gebeurtenissen die overeenkomen met de abonnementstypen of het contactfilter.

}

Antwoord voor berichtvorm van "SessionInfo"-abonnement:

{

messageType: "SessionInfo"

sessionToken: "mysessiontoken=="

}

De bevestigingsgebeurtenis voor het abonnement

Als er minimaal één subscriptionType is, wordt het abonnement toegestaan. Als er geen geldig subscriptionType is, wordt een consolewaarschuwing gelogd met informatie over het ongeldige type. De eerste gebeurtenis in de reeks geretourneerde gebeurtenissen is een gebeurtenis met het meldingstype ClientEventSubscriptionAcknowledge. Deze gebeurtenis heeft de volgende structuur:

{

contactId: (int) – Als dit null is, betekent dit dat er geen contactId is gekoppeld aan het abonnement. Zo kan de klant zien of het "contact"-abonnement werkt.

messageType: ClientEventSubscriptionAcknowledge (string) – Dit is het specifieke bevestigingsmeldingstype.

reason: "Success" | "Invalid Contact Id" | "Invalid Subscription Types" – Bij een antwoord met de reden voor de ERROR-statuscode. Deze informatie is niet erg gedetailleerd, om niet te veel complexiteit toe te voegen. Er wordt maar één reden voor de mislukking geretourneerd. We controleren eerst de contact-ID op geldigheid (een string die een integer ongelijk aan 0 bevat) Als dit mislukt terwijl er ook ongeldige abonnementstypen zijn, dan laten we de onderliggende fouten pas zien wanneer de gebruiker de contact-ID heeft gecorrigeerd en het opnieuw probeert. Dat betekent dat we geen verwijzing naar het venster hebben bewaard, dus het abonnement is mislukt.

status: "OK" | "ERROR" – Als dit ERROR is, dan hebben we de abonnementsverbinding voor POST-berichten niet kunnen maken. De gebruiker moet de fouten oplossen en het opnieuw proberen.

}

In sommige gevallen wordt er geen abonnementsbevestiging verzonden. Wanneer hetzelfde venster een tweede abonnement aanvraagt zonder eerst het bestaande abonnement te verwijderen, wordt er geen antwoord gestuurd en geen extra abonnement herkend. We geven een consolewaarschuwing weer zoals hieronder aangegeven:

{

console.warn('Fout bij verwerking van client-gebeurtenisabonnement. Issuer: [' + subscriberObject.data.issuer + '] heeft al een abonnement.')

}