API

Met onze Messenger API kunt u de gedragingen en integratie van de Website Messenger bepalen buiten de opties die we bieden in onze Messenger-instellingen. Klik hier om direct naar de volledige documentatie van de API op GitHub te gaan.

De Messenger API stelt u in staat om het begin en de voortgang van uw chatcommunicatie te definiëren op basis van het gedrag, de gebeurtenissen en de functies van uw website. Hier zijn enkele potentiële gebruiksscenario's om u een beter idee te geven:

Het laden van de Website Messenger pas na toestemming voor cookies

Het triggeren van de chat in bepaalde situaties, zoals een winkelwagentje dat een bepaalde waarde overschrijdt

Het laden en verwijderen van de Website Messenger op grotere single page applications

Wanneer u de JavaScript Widget-code gebruikt om uw Website Messenger te laden, wordt deze wereldwijd geladen zodra het script-tag wordt uitgevoerd. De Messenger API geeft u meer controle over het laadproces door u in staat te stellen Messengers toe te voegen of te verwijderen op het document.

💡

De installatie van de Messenger API is gericht op ontwikkelaars. Deze tutorial is bedoeld om minder technisch onderlegde gebruikers ook een overzicht te geven van de Messenger API en de mogelijkheden ervan. De referentie voor de Messenger API is deze GitHub repository, waarin de code staat.

De voorbeelden in dit document gebruiken gewone JavaScript. U kunt overwegen hulpprogramma's te gebruiken die u helpen bij het gemakkelijker behandelen van beloftes.

Het gebruik van de API

Om opdrachten met de API te gebruiken, moet u een messengerobject maken, dat kan worden gedaan met behulp van de createMessenger functie uit het @userlike/messenger npm-pakket. Hier is een eenvoudige manier om het te doen, maar we raden aan om foutafhandeling toe te voegen aan uw functie voor het geval er iets misgaat of voor het geval de API-versie die u gebruikt het einde van zijn levensduur heeft bereikt. Zorg er eerst voor dat u het vereiste component importeert uit het npm-pakket bovenaan uw bestand: import { createMessenger } from '@userlike/messenger';

U kunt nu createMessenger gebruiken in uw code:

javascript
async function createApi() {
    const result = await createMessenger({
        version: 1,
        widgetKey: "WIDGET_KEY",
    });
    const { api } = result.value;
    return api;
};

Wijs deze functie nu toe aan een variabele die een promise teruggeeft. Je kunt die variabele dan gebruiken om de messenger op de DOM te monteren, bijvoorbeeld:

javascript
const userlike = createApi();

userlike.then(messenger => messenger.mount());

Het bovenstaande is een goed voorbeeld van hoe je het maken en monteren van de messenger kunt koppelen aan de cookie-toestemmingskeuzes van een gebruiker door alleen createApi() te bellen nadat de gebruiker de relevante optie heeft geselecteerd.

💡

Er kan slechts één messenger tegelijk aan de DOM worden gemonteerd, dus zorg ervoor dat je hiermee rekening houdt in je logica, vooral als je wilt schakelen tussen verschillende widgets. Als je probeert een tweede widget te monteren terwijl er al een andere is gemonteerd, zal dit resulteren in een foutmelding.

Gebruik van uw eigen element om de chat te activeren

In bepaalde situaties wilt u mogelijk een aangepast element op uw pagina gebruiken om het openen van de messenger te activeren in plaats van de knop van de widget. In dat geval wilt u waarschijnlijk de setVisibility -functie van de messenger API gebruiken. Met setVisibility kunt u de zichtbaarheid van main (het hoofdvenster van de chatwidget), button (de knop zelf) en notifications (meldingsbellen zoals de welkomstbel of de proactieve bel) definiëren.

In combinatie met de maximize-functie kunt u uw eigen element definiëren en definiëren dat het onClick-evenement de messenger moet maximaliseren. Als u bijvoorbeeld een HTML-element met de ID myBtn gebruikt, kunt u zoiets doen:

javascript
const userlike = createApi();

userlike.then(
    messenger => messenger.mount()
        .then(() => messenger.setVisibility({
            main: true,
            button: false,
            notifications: false,
        }))
);

const startChat = () => {
    userlike.then(m => m.maximize());
}

document.getElementById('myBtn').addEventListener(
    "click", () => startChat()
)

Je kunt verder bouwen op dit startpunt door de bovenstaande 'startChat()' functie te wijzigen om de zichtbaarheid van de messenger te schakelen tussen gemaximaliseerd en geminimaliseerd, of alleen je eigen aangepaste knop weergeven als de messenger is geminimaliseerd. De huidige status van de messenger kan worden opgehaald met behulp van de API-functie 'getState()', waar we verder op ingaan in deze tutorial. Voor meer informatie over het bijhouden van de status, verwijzen we ook naar het codevoorbeeld in het Github repository.

Weergeven van de messenger op basis van bepaalde voorwaarden

Het concept van het wijzigen van de zichtbaarheid of het monteren van de messenger zoals hierboven te zien is, kan worden toegepast op verschillende scenario's waarbij je eigen logica bepaalt wanneer de knop aan de bezoeker moet worden getoond.

Bijvoorbeeld, stel dat je de knop alleen wilt weergeven nadat de bezoeker een bepaald punt op je pagina heeft bereikt, dan roep je gewoon de 'setVisibility()' functie aan met de relevante argumenten:

javascript
/*
Assuming you hid the messenger button when mounting the messenger
and that you have a function 'scrollDepth' that returns the current
scroll position on the page:
*/

window.addEventListener("scroll", function () {
    if (scrollDepth() > 50) {
        userlike.then(messenger => messenger.setVisibility(
            {
                main: true,
                button: true,
                notifications: true,
            }
        ))
    }
}, false)

Dezelfde idee kan worden toegepast op verschillende scenario's, zoals het updaten van de zichtbaarheid van de knop zodra een klant een bepaalde winkelwagenwaarde heeft bereikt. Op een verstandige manier gebruikt, kunt u verschillende scenario's creëren om de chatbetrokkenheid te stimuleren door de chat op het juiste moment aan te bieden.

Data verzenden naar de messenger

De API biedt twee functies waarmee u gegevens naar de messenger kunt verzenden.

setContactInfo maakt het mogelijk om de naam en het e-mailadres van de contactpersoon in te stellen. Dit is handig als u de chat aanbiedt voor gebruikers die zijn ingelogd op uw webapplicatie en u deze informatie rechtstreeks aan Userlike wilt doorgeven.

De gegevens moeten als een JavaScript-object aan de functie worden doorgegeven, met de sleutels name en email met de bijbehorende waarden als strings.

Als u de widget in registratiemodus gebruikt en u de naam en het e-mailadres van de contactpersoon doorgeeft aan de messenger, wordt de registratiestap bij het starten van een conversatie overgeslagen.

Dezelfde logica kan worden gebruikt met de aangepaste datafunctie. Uw aangepaste gegevens worden weergegeven in het Berichtencentrum. Het kan worden bijgewerkt door de functie setCustomData opnieuw aan te roepen met een bijgewerkte set gegevens. De gegevens die u naar de messenger stuurt, moeten een JavaScript-object zijn dat sleutel-waarde paren bevat met de informatie die u wilt opnemen.

Het onderstaande voorbeeld implementeert de messenger, stelt de naam van de contactpersoon in en geeft wat aangepaste gegevens door aan de conversatie.

javascript
let customData = {
    example: 1,
    test: "custom data",
    foo: "bar",
    id: 123456789,
    loggedIn: true,
}

userlike.then((messenger) =>
    messenger
        .mount()
        .then(() =>
            messenger.setContactInfo({
                name: "Test Contact",
                email: "test@example.com"
            })
            .then(() => messenger.setCustomData(customData))
        )
);

Het ophalen van de huidige staat van de widget

Om de huidige staat van de Messenger op te halen, gebruik je de functie getState() van de API. Deze kan drie verschillende waarden retourneren:

hidden: wanneer de Messenger niet is gemonteerd op de DOM, of wanneer het is gemonteerd maar verborgen is door de configuratie van de Messenger. Dit is het geval als je de Messenger hebt ingesteld om verborgen te zijn wanneer er geen operator beschikbaar is in het Berichtencentrum. Je kunt deze informatie gebruiken om te bepalen of je bepaalde elementen op de pagina wilt weergeven of verbergen op basis van de beschikbaarheid van je operators.

minimized: de Messenger is gemonteerd maar geminimaliseerd (het hoofdvenster van de Messenger wordt niet weergegeven).

maximized: de Messenger is gemonteerd en gemaximaliseerd (het hoofdvenster van de Messenger wordt weergegeven, net als na het klikken op de Messenger-knop).

In plaats van de status handmatig op te vragen, kun je hier ook op abonneren. Voor meer informatie, zie de GitHub repository.

👉🏻

read this article in English: https://docs.userlike.com/setup/integration/api