Snabbstart

Widgetöversikt

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

Widgeten är en lättviktsapplikation 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 bibehåller utmärkt prestanda och säkerhet.

1. Skapa en agent

Först, skapa en AI-agent för kundsupport i din panel:

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

1. Gå till din panel 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 panel
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>

Byt ut YOUR_WIDGET_KEY mot installationsnyckeln för din widget (wgt_…-värdet — kopiera det från Widget- eller installationssidan i instrumentpanelen). Parametern locale kan ställas in för att matcha din webbplats språk.

Avancerat: JavaScript-initiering

Den rekommenderade integrationsmetoden är att använda vår JavaScript-widgetladdare, som ger 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"  async></script>

Skriptattribut

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

• data-widget-key: Din widgets Widget-ID - Det enda värde de flesta installationer behöver. Det löser din klient, agent och konfigurationsserver på serversidan, så du behöver inte klistra in dem separat.

De tre attributerna nedan är ett avancerat alternativ till data-widget-key - använd dem för multi-instansinställningar 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 avgör 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 man bäddar in flera widgets på samma sida för att undvika kollisioner och möjliggöra per-instans API-mål.
• 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-dev: Ställ in på "true" för utvecklingsläge (localhost) - Använd detta när du testar lokalt. Ta bort eller ställ in på "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
• Starta ö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 start_open inställningen från din konfiguration
• All styling (färger, typsnitt, dimensioner) kontrolleras genom widgetkonfigurationen
• Widgeten använder postMessage kommunikation för responsivt beteende
• Utvecklingsläge kan aktiveras med data-dev="true" för localhost-testning
• 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) är inkluderat i OAuth tillåtna ursprung när du bäddar in widgeten i en iframe.