> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Scheda widget

## Panoramica

Ospita una piccola pagina HTML che carica il [widget dell'agente](/docs/it/eleven-agents/customization/widget) 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](/docs/_fern-img/8fedd2110258c6751012619128601214cdfcd4a11aaa832f62050c00c52106e7.webp)

## 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.

![Un utente Teams apre una scheda la cui webview include tramite iframe una pagina ospitata che esegue il widget dell'agente ElevenLabs, il quale trasmette l'audio a ElevenLabs](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/c90698c01d5e874b3a3fa8a07af5ef64620e0fe8a602155aed31bd3f1ce06273/assets/images/conversational-ai/teams-widget-architecture.svg)

> **Note**
>
> 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

1. Un [agente ElevenLabs](/docs/it/eleven-agents/quickstart) **pubblico** con l'autenticazione disattivata (scheda Avanzate nelle impostazioni dell'agente). I widget lo richiedono.
2. Un host HTTPS per un singolo file HTML statico (Vercel, Netlify, Cloudflare Pages, Azure Static Web Apps ecc.).
3. L'autorizzazione nel tuo tenant per caricare un'app Teams personalizzata ([Centro di amministrazione Teams → Gestisci app](https://admin.teams.microsoft.com/policies/manage-apps) → caricamento di app personalizzate), se usi l'opzione della scheda personalizzata.

## Passaggio 1 — Crea la pagina del widget

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

**`agent-widget.html`**

```html title="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.

> **Note**
>
> Se il tuo workspace si trova in un ambiente di [residenza dei dati](/docs/it/overview/administration/data-residency),
> aggiungi l'attributo `server-location` del widget affinché si connetta alla tua regione. Consulta
> [personalizzazione del widget](/docs/it/eleven-agents/customization/widget) per i valori supportati.

> **Tip**
>
> 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.

> **Warning**
>
> 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`**

```json title="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:

```bash
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.

> **Tip**
>
> 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**:
>
> ```powershell
> 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](/docs/_fern-img/308d95d230864371f4ad2cd8b329c503e672878788a1fdcbc49ab2ce6aa8ce7d.webp)

## 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:

```http
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.

#### Il widget si carica ma il microfono non funziona

Si tratta del livello di autorizzazioni della webview di Teams. Usa l'**app con scheda personalizzata** con
`"devicePermissions": ["media"]` e concedi all'app l'autorizzazione per il microfono in Teams (menu a discesa della scheda
→ **Autorizzazioni app**). Teams sul web e Teams desktop si comportano diversamente: provali entrambi. Come
alternativa, offri un link "Apri nel browser".

#### Il widget non viene mai visualizzato

Verifica che l'agente sia **pubblico** con l'autenticazione disattivata (impostazioni **Avanzate** dell'agente) e
che `unpkg.com` e `*.elevenlabs.io` siano inclusi in `validDomains` del manifest.

## Link utili

* [Personalizzazione del widget](/docs/it/eleven-agents/customization/widget)
* [Requisiti delle schede Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/tab-requirements)
* [Creare una scheda personale](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/create-personal-tab)
* [Autorizzazioni dei dispositivi Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/device-capabilities/native-device-permissions)