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

# Guia com widget

## Visão geral

Hospede uma pequena página HTML que carregue o [widget do agente](/docs/pt/eleven-agents/customization/widget) e exiba-a como uma **guia do Teams**. Os usuários abrem a guia e falam com o agente no cliente do Teams — sem número de telefone ou telefonia. Esta é a abordagem mais simples; use-a para assistentes internos de autoatendimento e demonstrações.

![O widget do agente da ElevenLabs aberto em uma guia do Microsoft Teams](/docs/_fern-img/8fedd2110258c6751012619128601214cdfcd4a11aaa832f62050c00c52106e7.webp)

## Como funciona

O widget é um componente web. O Teams renderiza o `contentUrl` de uma guia dentro de um webview (iframe), então o widget funciona exatamente como em um site — incluindo a captura do microfone, desde que a página possa ser incorporada ao Teams e receba permissão de mídia.

![Usuário do Teams abre uma guia cujo webview incorpora uma página hospedada que executa o widget do agente da ElevenLabs, que transmite áudio para a ElevenLabs](/docs/_fern-files/elevenlabs.docs.buildwithfern.com/c90698c01d5e874b3a3fa8a07af5ef64620e0fe8a602155aed31bd3f1ce06273/assets/images/conversational-ai/teams-widget-architecture.svg)

> **Note**
>
> O Teams **não** executará uma tag `<script>` bruta colada em um chat, mensagem ou página do Loop. O script do widget
> precisa estar em uma página **hospedada por você**, que o Teams então incorpora como uma guia.

## Requisitos

1. Um [agente da ElevenLabs](/docs/pt/eleven-agents/quickstart) **público** com a autenticação desativada (guia Avançado das configurações do agente). Os widgets exigem isso.
2. Um host HTTPS para um único arquivo HTML estático (Vercel, Netlify, Cloudflare Pages, Azure Static Web Apps etc.).
3. Permissão no seu locatário para fazer upload de um aplicativo personalizado do Teams ([centro de administração do Teams → Gerenciar aplicativos](https://admin.teams.microsoft.com/policies/manage-apps) → upload de aplicativo personalizado), caso use a opção de guia personalizada.

## Etapa 1 — Criar a página do widget

Crie `agent-widget.html` com a incorporação do widget e o ID do seu 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>
```

Implante-o no seu host HTTPS e confirme primeiro que ele carrega e que o microfone funciona em um navegador comum.

> **Note**
>
> Se seu workspace estiver em um ambiente de [residência de dados](/docs/pt/overview/administration/data-residency),
> adicione o atributo `server-location` do widget para que ele se conecte à sua região — consulte a
> [personalização do widget](/docs/pt/eleven-agents/customization/widget) para ver os valores compatíveis.

> **Tip**
>
> Teste a página isoladamente em um navegador antes de mexer no Teams. Se o microfone não funcionar nela,
> também não funcionará no webview do Teams.

## Etapa 2 — Adicionar ao Teams

Você tem duas opções, em ordem crescente de confiabilidade para voz.

### Opção A — Guia de site (mais rápida, pode abrir apenas como link)

Em um chat ou canal, **+ Adicionar uma guia → Site**, cole seu URL HTTPS e salve.

> **Warning**
>
> Às vezes, a guia integrada **Site** abre a página como um link externo em vez de incorporá-la
> — e, mesmo quando incorporada, o acesso ao microfone no webview do Teams para desktop pode ser bloqueado. Se a voz
> falhar, use a Opção B.

### Opção B — Aplicativo de guia personalizado (recomendado para voz)

Um pequeno aplicativo personalizado do Teams declara a página como uma guia estática **e** solicita permissão de mídia, o que faz o microfone funcionar de forma confiável dentro do Teams.

#### Criar o manifesto

Crie `manifest.json`. Substitua `your-domain.com` pelo seu host e defina um GUID único para `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"]
}
```

Os campos essenciais para voz são **`devicePermissions: ["media"]`** (microfone) e listar todos os domínios que a página acessa em **`validDomains`** (`unpkg.com` para o script do widget, `*.elevenlabs.io` para o agente).

#### Empacotar o aplicativo

Adicione um `color.png` (192×192) e um `outline.png` (32×32, transparente) ao lado do manifesto e compacte o manifesto e os dois ícones na **raiz** do arquivo:

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

#### Fazer upload e abrir

No Teams: **Aplicativos → Gerenciar seus aplicativos → Carregar um aplicativo → Carregar um aplicativo personalizado**, selecione `voice-agent.zip`, abra a guia **Voice Agent** e conceda acesso ao microfone quando solicitado.

> **Tip**
>
> Os administradores do Teams podem ignorar a interface do cliente e publicar o aplicativo para toda a organização pelo PowerShell — ele aparecerá para todos em **Aplicativos → Criados para sua organização**:
>
> ```powershell
> Connect-MicrosoftTeams
> New-TeamsApp -DistributionMethod organization -Path ./voice-agent.zip
> ```

Se não aparecer nenhum aviso, abra o menu suspenso da guia e escolha **Permissões do aplicativo** para conceder acesso ao microfone manualmente:

![O menu suspenso da guia do Teams com Permissões do aplicativo destacadas](/docs/_fern-img/308d95d230864371f4ad2cd8b329c503e672878788a1fdcbc49ab2ce6aa8ce7d.webp)

## Etapa 3 — Permitir que o Teams incorpore a página

Seu host deve permitir que o Teams incorpore a página em um iframe. Se você controla os cabeçalhos de resposta, defina:

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

Se o Teams continuar abrindo a página em um navegador em vez de incorporá-la, a incorporação em iframe está sendo bloqueada — corrija a CSP / `X-Frame-Options` no seu host.

## Solução de problemas

#### A guia abre a página em um navegador em vez de incorporá-la

A página está bloqueada para incorporação em iframe. Remova qualquer `X-Frame-Options: DENY/SAMEORIGIN` e defina
a CSP `frame-ancestors` mostrada acima para permitir os domínios do Teams. O aplicativo de guia personalizado (Opção B)
também é mais confiável que a guia integrada de Site.

#### O widget carrega, mas o microfone não funciona

Isso ocorre na camada de permissões do webview do Teams. Use o **aplicativo de guia personalizado** com
`"devicePermissions": ["media"]` e conceda ao aplicativo permissão para usar o microfone no Teams (menu suspenso da guia
→ **Permissões do aplicativo**). O Teams na web e o Teams para desktop se comportam de forma diferente — teste ambos. Como
alternativa, ofereça um link "Abrir no navegador".

#### O widget nunca aparece

Confirme que o agente é **público** com a autenticação desativada (configurações **Avançado** do agente) e
que `unpkg.com` e `*.elevenlabs.io` estão no `validDomains` do manifesto.

## Links úteis

* [Personalização do widget](/docs/pt/eleven-agents/customization/widget)
* [Requisitos de guias do Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/tab-requirements)
* [Criar uma guia pessoal](https://learn.microsoft.com/en-us/microsoftteams/platform/tabs/how-to/create-personal-tab)
* [Permissões de dispositivo do Teams](https://learn.microsoft.com/en-us/microsoftteams/platform/concepts/device-capabilities/native-device-permissions)