Neben der einfachen Einbettung Ihrer Website in Lime Connect können Sie die Custom Add-on Frontend API nutzen, um die Kommunikation zwischen dem Message Center und Ihrer Anwendung zu ermöglichen. So können Sie beispielsweise Echtzeitdaten aus Lime Connect abrufen oder Kontaktinformationen in Lime Connect über Ihre Anwendung aktualisieren.
Erste Schritte
Um ein benutzerdefiniertes Add-on zu erstellen, gehen Sie zu Settings > Add-ons > Custom Add-ons und klicken Sie auf die Schaltfläche Add.
Anschließend können Sie den Namen des Add-ons, die URL, unter der es gehostet wird, und die URL des Symbols angeben, das in der Seitenleiste mit den Konversationsdetails angezeigt wird.
Für optimale Ergebnisse wird ein Symbol mit einem Seitenverhältnis von 1:1, transparentem Hintergrund und ohne Innenabstand empfohlen.
Inhaltsrichtlinie
Um die ursprungsübergreifende Nutzung Ihres Add-ons zu ermöglichen, legen Sie eine
frame-ancestors-Direktive in der Content-Policy fest.
Weitere Informationen finden Sie unter: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestorsBeispiel:
plain textContent-Security-Policy: frame-ancestors https://app.lime-connect.com;
Lokale Entwicklung
Wenn die Inhaltsrichtlinie korrekt eingerichtet ist, können Sie Ihr Add-on auf einem lokalen Server entwickeln und dessen URL verwenden, beispielsweise 127.0.0.1.
Lebenszyklus
Benutzerdefinierte Add-ons werden geladen, sobald der Operator eine Konversation öffnet.
Wenn der Operator die Konversation verlässt oder zu einer anderen Konversation wechselt, wird das Add-on entfernt und sein Zustand geht verloren.
Message-Center-Ereignisse empfangen
Die Kommunikation mit Ihrem Add-on erfolgt über die JavaScript-postMessage API.
Beim Laden Ihres Add-ons stellen wir Ihnen initiale Ereignisse zur Verfügung, darunter Kontaktinformationen, Konversationsinformationen, Operatorinformationen und das Transkript.
Überwachen Sie eingehende Ereignisse weiterhin über die postMessage API, um Echtzeitdaten zu erhalten.
Ab Version 2 senden wir Ereignisse erst, nachdem wir eine „ready“-Aktion empfangen haben.
Beispiel:
javascript// Eingehende Ereignisse überwachen window.addEventListener("message", (message) => { if (message.origin !== "https://app.lime-connect.com") return; switch (message.data.name) { case "contact_information": setContactInfo(message.data.payload); break; } }); // Für Version 2 und höher erforderlich window.parent.postMessage({ name: "ready", payload: {} }, "https://app.lime-connect.com");
Message-Center-Aktionen auslösen
Ihr Add-on kann Aktionen im Message Center auslösen, beispielsweise den Text im Chat-Eingabefeld ersetzen oder eine Toast-Benachrichtigung anzeigen.
Beispiel:
javascriptwindow.parent.postMessage( { name: "toast", payload: { message: "Hello from the add-on!", status: "warning", }, }, "https://app.lime-connect.com" );
Ereignisse
Transkript
Dieses Ereignis wird einmal ausgelöst, wenn das Add-on aktiv wird, und jedes Mal, wenn der Konversation eine neue Textnachricht hinzugefügt wird.
Es enthält alle Nachrichten, die der Operator sehen kann, abhängig davon, wie weit er im Konversationsverlauf zurückgescrollt hat.
typescripttype Sender = { type: "contact" | "operator"; }; type TextMessage = { type: "message"; body: string; textFormat: "markdown_v1" | "plain_text"; sender: Sender; }; type TranscriptEvent = { name: "transcript"; payload: { transcript: TextMessage[]; }; }; const example: TranscriptEvent = { name: "transcript", payload: { transcript: [ { sender: { type: "contact" }, body: "Hello, I have a question about your product.", textFormat: "plain_text", type: "message", }, { sender: { type: "operator" }, body: "Hello, how can I help you?", textFormat: "plain_text", type: "message", }, ], }, };
Kontaktinformationen
Dieses Ereignis wird einmal ausgelöst, wenn das Add-on aktiv wird, und jedes Mal, wenn die Kontaktinformationen aktualisiert werden.
Beachten Sie, dass die Kontaktinformationen null sein können, wenn sie weder vom Operator noch vom Kontakt angegeben wurden.
typescripttype ContactEvent = { name: "contact_information"; payload: { id: string; name: string | null; email: string | null; locale: string | null; mobileNumber: string | null; phoneNumber: string | null; salutation: "mr" | "ms" | "pr" | "prof" | null; street: string | null; city: string | null; country: string | null; company: string | null; gender: "m" | "f" | "d" | null; customFieldData: Record<string, string | string[] | null>; }; }; const example: ContactEvent = { name: "contact_information", payload: { id: "1111", name: "Jane Doe", email: "jane@example.com", locale: "en_US", mobileNumber: "+325920392947", phoneNumber: "+325920392947", salutation: "ms", street: "Im Mediapark 8", city: "Köln", country: "DE", company: "Lime Connect", gender: null, custom_field_data: null, }, };
Konversation
Dieses Ereignis wird einmal ausgelöst, wenn das Add-on aktiv wird, und jedes Mal, wenn die Konversationsinformationen aktualisiert werden.
Es enthält Metainformationen zur aktuellen Konversation.
Beachten Sie, dass einige Angaben null sein können.
typescripttype ConversationEvent = { name: "conversation_information"; payload: { id: string | null; topics: { text: string }[]; locale: string | null; subject: string | null; customFieldData: Record<string, string | string[] | null>; widget: { id: string; name: string; }; }; }; const example: ConversationEvent = { name: "conversation_information", payload: { id: "1111", topics: [{ text: "Support" }, { text: "Support" }], locale: "en_US", subject: "IT Support", customFieldData: null, widget: { id: "111", name: "My widget", }, }, };
Operator
Dieses Ereignis wird einmal ausgelöst, wenn das Add-on aktiv wird, und jedes Mal, wenn die Operatorinformationen aktualisiert werden.
typescripttype OperatorEvent = { name: "operator_information"; payload: { id: string; name: string; email: string; locale: string; }; }; const example: OperatorEvent = { name: "operator_information", payload: { id: "1111", name: "Jane Doe", email: "jane@example.com", locale: "en_US", }, };
JWT-Token
Dieses Ereignis wird als Antwort auf die Aktion
generate_jwt_token ausgegeben und stellt ein JWT-Token zur Authentifizierung bereit.typescripttype JwtTokenEvent = { name: "jwt_token"; payload: { type: 'success', token: string } | { type: 'error', error: string }; }; const example: JwtTokenEvent = { name: "jwt_token", payload: { type: "success", token: "xxxxxxxxx...", }, };
Aktionen
Aktionen sind Ereignisse, die das Add-on auslösen kann, um bestimmte Aufgaben im Message Center auszuführen.
JWT-Token erzeugen
Fordern Sie ein neues JWT-Token vom Message Center an. Bei Erfolg wird ein neues
jwt_token-Ereignis mit dem neuen Token ausgegeben.typescripttype GenerateJwtTokenAction = { name: "generate_jwt_token"; payload: {}; }; const example: GenerateJwtTokenAction = { name: "generate_jwt_token", payload: {}, };
Chat-Eingabe ersetzen
Senden Sie Text an das Chat-Eingabefeld des Operators.
typescripttype ReplaceChatInputAction = { name: "replace_chat_input"; payload: { textFormat: "plain_text" | "markdown_v1"; message: string; }; }; const example: ReplaceChatInputAction = { name: "replace_chat_input", payload: { textFormat: "markdown_v1", message: "For more information [check out Lime Connect](https://app.lime-connect.com).", }, };
Toast
Zeigen Sie eine Toast-Benachrichtigung an.
typescripttype ToastAction = { name: "toast"; payload: { status: "info" | "error" | "success" | "warning"; message: string; }; }; const example: ToastAction = { name: "toast", payload: { status: "error", message: "An unexpected error has occurred.", }, };
Kontaktinformationen aktualisieren
Aktualisieren Sie Kontaktinformationen teilweise.
typescripttype UpdateContactAction = { name: "update_contact_information"; payload: Partial<{ name: string | null; email: string | null; locale: string | null; mobileNumber: string | null; phoneNumber: string | null; salutation: "mr" | "ms" | "pr" | "prof" | null; street: string | null; city: string | null; country: string | null; company: string | null; gender: "m" | "f" | "d" | null; customFieldData: Record<string, string | string[] | null>; }>; }; const example: UpdateContactAction = { name: "update_contact_information", payload: { name: "Jane Doe", customFieldData: { "dd23-4dfd-f23f-s3rf": "Hello world!" }, }, };
Konversationsinformationen aktualisieren
Aktualisieren Sie Konversationsinformationen.
typescripttype UpdateConversationAction = { name: "update_conversation_information"; payload: { customFieldData: Record<string, string | string[] | null>; }; }; const example: UpdateConversationAction = { name: "update_conversation_information", payload: { customFieldData: { "dd23-4dfd-f23f-s3rf": "Hello world!" }, }, };