Scheda widget

Panoramica

Ospita una piccola pagina HTML che carica il widget dell’agente e visualizzala come scheda di Teams. Gli utenti aprono la scheda e parlano con l’agente nel client Teams, senza numero di telefono né telefonia. È l’approccio più leggero; usalo per assistenti self-service interni e demo.

Il widget dell'agente ElevenLabs aperto in una scheda di Microsoft Teams — Il widget dell'agente in esecuzione in una scheda di Teams

Come funziona

Il widget è un componente web. Teams esegue il rendering di contentUrl di una scheda all’interno di una webview (iframe), quindi il widget funziona esattamente come su un sito web, inclusa l’acquisizione dal microfono, a condizione che la pagina possa essere incorporata in Teams e riceva l’autorizzazione per i contenuti multimediali.

Widget incorporato in una scheda di Teams

Teams non esegue un <script> non elaborato incollato in una chat, un messaggio o una pagina Loop. Lo script del widget deve trovarsi in una pagina che ospiti tu, che Teams incorpora poi come scheda.

Requisiti

Un agente ElevenLabs pubblico con l’autenticazione disattivata (scheda Avanzate nelle impostazioni dell’agente). I widget lo richiedono.
Un host HTTPS per un singolo file HTML statico (Vercel, Netlify, Cloudflare Pages, Azure Static Web Apps ecc.).
L’autorizzazione nel tuo tenant per caricare un’app Teams personalizzata (Centro di amministrazione Teams → Gestisci app → caricamento di app personalizzate), se usi l’opzione della scheda personalizzata.

Crea agent-widget.html con l’incorporamento del widget e l’ID del tuo agente:

agent-widget.html

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Voice Agent</title>
  </head>
  <body style="margin:0">
    <elevenlabs-convai
      agent-id="<replace-with-agent_7101k5zvyjhmfg983brhmhkd98n6>"
    ></elevenlabs-convai>
    <script
      src="https://unpkg.com/@elevenlabs/convai-widget-embed"
      async
      type="text/javascript"
    ></script>
  </body>
</html>

Distribuiscila sul tuo host HTTPS e verifica prima che si carichi e che il microfono funzioni in un browser normale.

Se il tuo workspace si trova in un ambiente di residenza dei dati, aggiungi l’attributo server-location del widget affinché si connetta alla tua regione. Consulta personalizzazione del widget per i valori supportati.

Prova la pagina autonomamente in un browser prima di passare a Teams. Se il microfono non funziona lì, non funzionerà nemmeno nella webview di Teams.

Passaggio 2 — Aggiungila a Teams

Hai due opzioni, in ordine crescente di affidabilità per la voce.

Opzione A — Scheda Sito Web (più rapida, potrebbe aprire solo un link)

In una chat o in un canale, seleziona + Aggiungi una scheda → Sito Web, incolla il tuo URL HTTPS e salva.

La scheda integrata Sito Web a volte apre la pagina come link esterno anziché incorporarla e, anche quando è incorporata, l’accesso al microfono nella webview desktop di Teams può essere bloccato. Se la voce non funziona, usa l’Opzione B.

Opzione B — App con scheda personalizzata (consigliata per la voce)

Una piccola app Teams personalizzata dichiara la pagina come scheda statica e richiede l’autorizzazione per i contenuti multimediali, rendendo affidabile il funzionamento del microfono all’interno di Teams.

Crea il manifest

Crea manifest.json. Sostituisci your-domain.com con il tuo host e imposta un GUID univoco per id:

manifest.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
  "manifestVersion": "1.19",
  "version": "1.0.0",
  "id": "11111111-1111-1111-1111-111111111111",
  "developer": {
    "name": "ElevenLabs",
    "websiteUrl": "https://your-domain.com",
    "privacyUrl": "https://your-domain.com/privacy",
    "termsOfUseUrl": "https://your-domain.com/terms"
  },
  "name": { "short": "Voice Agent", "full": "ElevenLabs Voice Agent" },
  "description": {
    "short": "ElevenLabs voice agent",
    "full": "Embedded ElevenLabs voice agent"
  },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#000000",
  "staticTabs": [
    {
      "entityId": "voice-agent",
      "name": "Voice Agent",
      "contentUrl": "https://your-domain.com/agent-widget.html",
      "websiteUrl": "https://your-domain.com/agent-widget.html",
      "scopes": ["personal"]
    }
  ],
  "devicePermissions": ["media"],
  "validDomains": ["your-domain.com", "unpkg.com", "elevenlabs.io", "*.elevenlabs.io"]
}

I campi chiave per la voce sono devicePermissions: ["media"] (microfono) e l’inserimento di ogni dominio usato dalla pagina in validDomains (unpkg.com per lo script del widget, *.elevenlabs.io per l’agente).

Crea il pacchetto dell'app

Aggiungi un file color.png (192×192) e outline.png (32×32, trasparente) accanto al manifest, quindi comprimi il manifest e le due icone nella directory root dell’archivio:

zip -j voice-agent.zip manifest.json color.png outline.png

Carica e apri

In Teams: App → Gestisci le tue app → Carica un’app → Carica un’app personalizzata, seleziona voice-agent.zip, quindi apri la scheda Voice Agent e concedi l’accesso al microfono quando richiesto.

Gli amministratori di Teams possono evitare l’interfaccia client e pubblicare l’app nell’intera organizzazione da PowerShell: apparirà quindi per tutti in App → Create per la tua organizzazione:

Connect-MicrosoftTeams
New-TeamsApp -DistributionMethod organization -Path ./voice-agent.zip

Se non viene visualizzata alcuna richiesta, apri il menu a discesa della scheda e seleziona Autorizzazioni app per concedere manualmente l’accesso al microfono:

Il menu a discesa della scheda Teams con Autorizzazioni app evidenziato — Menu a discesa della scheda → Autorizzazioni app

Passaggio 3 — Consenti a Teams di incorporare la pagina

Il tuo host deve consentire a Teams di includere la pagina in un iframe. Se controlli gli header della risposta, imposta:

Content-Security-Policy: frame-ancestors 'self' https://teams.microsoft.com https://*.teams.microsoft.com https://*.cloud.microsoft;

Se Teams continua ad aprire la pagina in un browser anziché incorporarla, l’incorporamento tramite iframe della pagina è bloccato: correggi CSP / X-Frame-Options sul tuo host.

Risoluzione dei problemi

La scheda apre la pagina in un browser anziché incorporarla

L’inserimento della pagina in un iframe è bloccato. Rimuovi eventuali X-Frame-Options: DENY/SAMEORIGIN e imposta la CSP frame-ancestors indicata sopra per consentire i domini Teams. Anche l’app con scheda personalizzata (Opzione B) è più affidabile della scheda Sito Web integrata.