Snabbstart

Widgetöversikt

Widgetappen är värd på widget.companin.tech och erbjuder ett enkelt sätt att bädda in en kundsupport AI-agent på din webbplats. För att komma igång måste du skapa en agent och en OAuth-applikation.

Widgeten är en lättvikts, självständig applikation som körs i en isolerad iframe på din webbplats. Denna arkitektur säkerställer att widgeten inte kommer i konflikt med din befintliga CSS eller JavaScript, samtidigt som den upprätthåller utmärkt prestanda och säkerhet.

1. Skapa en agent

Först, skapa en kundsupport AI-agent i din instrumentpanel:

Din agent är AI-hjärnan bakom widgeten. Den bearbetar användarmedelanden, upprätthåller konversationskontext och genererar intelligenta svar. Varje agent kan anpassas med specifika instruktioner, personlighetsdrag och kunskapsbaser för att matcha ditt användningsfall.

1. Gå till din instrumentpanel och navigera till sidan "Datakällor"
2. Klicka på knappen "Lägg till" i avsnittet för agenter
3. Fyll i agentens detaljer (namn, beskrivning, ton, etc.)
4. Spara agenten och notera dess ID

Tips: Ge din agent tydliga, specifika instruktioner om dess roll och begränsningar. Till exempel: "Du är en hjälpsam kundsupportagent för en SaaS-produkt. Du kan svara på frågor om funktioner, prissättning och kontohantering. För tekniska problem, dirigera användare att skapa en supportbiljett."

2. Skapa en OAuth-applikation

Skapa en OAuth-applikation för att autentisera din widget:

1. Gå till sidan "OAuth" i din instrumentpanel
2. Klicka på "Skapa applikation"
3. Fyll i applikationens namn och beskrivning
4. Kopiera client_id från den skapade applikationen

3. Bädda in widgeten via Iframe

Det enklaste sättet att integrera widgeten är att bädda in den direkt med en iframe. Denna metod kräver ingen JavaScript-initiering och fungerar direkt. För flera iframes på en sida, håll varje inbäddning avgränsad till sin egen behållare och parametrar.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

Ersätt YOUR_WIDGET_KEY med din widgets installationsnyckel (värdet wgt_… — kopiera det från widget-sidan eller installationssidan i instrumentpanelen). Parametern locale kan ställas in för att matcha ditt sidas språk.

Avancerat: JavaScript-initiering

Den rekommenderade integrationsmetoden är att använda vår JavaScript-widgetladdare, som erbjuder automatisk storleksanpassning, konfigurationshantering och responsivt beteende.

Skriptintegration

Lägg till följande skript-tagg till din HTML-sida:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="support-widget"  data-locale="en"  data-theme="system"  async></script>

Skriptattribut

Varje attribut har ett specifikt syfte i konfigurationen av din widget:

• data-widget-key: Din widgets Widget-ID - Det enda värdet som de flesta installationer behöver. Det löser din klient, agent och konfigurerar server-sidan, så att du inte klistrar in dem separat.

De tre attributen nedan är ett avancerat alternativ till data-widget-key - använd dem för multi-instansuppsättningar där du behöver rikta in dig på en specifik klient, agent eller konfiguration uttryckligen:

• data-client-id: Ditt OAuth-klient-ID - Detta autentiserar din applikation med vårt API. Tänk på det som ditt apps lösenord.
• data-agent-id: UUID för din agent - Detta identifierar vilken kundsupport AI-agent som hanterar konversationerna.
• data-config-id: UUID för din widgetkonfiguration - Detta bestämmer hur din widget ser ut och beter sig (färger, storlek, position, etc.).
• data-instance-id: Unik per-widget instans-ID - Krävs när du bäddar in flera widgets på samma sida för att undvika kollisioner och möjliggöra per-instans API-riktning.
• data-custom-css: Avvecklad. Att ställa in detta attribut loggar en konsolvarning och har ingen effekt. Ställ in custom_css på din widgetkonfiguration i instrumentpanelen istället — det laddas från konfigurationen och injiceras automatiskt i iframen.
• data-locale: Språk kod (t.ex. "en", "es", "fr") - Ställer in widgetens visningsspråk. Agenten kommer fortfarande att svara på vilket språk användarna skriver på.
• data-theme: Temaläge - light, dark, eller system (följ besökarens enhet). Väljer vilken färgpalett (konfigurerad i din instrumentpanel) widgeten visar. Utelämna det för att använda din sparade standard.
• data-dev: Sätt till "true" för utvecklingsläge (localhost) - Använd detta när du testar lokalt. Ta bort eller sätt till "false" för produktion.

Widgeten kommer automatiskt:

• Hämta konfigurationen från konfigurations-ID:t
• Storleksanpassa sig enligt widgetens dimensioner i konfigurationen
• Positionera den kollapsade knappen baserat på konfigurationsinställningarna
• Börja öppen eller stängd baserat på konfigurationens start_open inställning

Anteckningar

• Widgeten hanterar automatiskt sin egen storlek baserat på dina konfigurationsinställningar
• Den kollapsade knappens position kan anpassas genom widgetkonfigurationen
• Widgeten respekterar inställningen start_open från din konfiguration
• All styling (färger, typsnitt, dimensioner) styrs genom widgetkonfigurationen
• Widgeten använder postMessage-kommunikation för responsivt beteende
• Utvecklingsläge kan aktiveras med data-dev="true" för testning på localhost
• För server-sidan tokenutbyte, använd /api/v1/auth/widget-token och behåll klienthemligheten på din server endast.
• Se till att ditt värdursprung (till exempel http://localhost:3000) ingår i OAuth allowed_origins när du bäddar in widgeten i en iframe.