Custom Addon Builder

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-ancestors
Beispiel:
plain text
Content-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:
javascript
window.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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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.
typescript
type 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!" }, }, };