> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Alexa Devices

> Descubra e controle dispositivos Echo (Alexa) da sua conta Amazon

# Alexa Devices

A integração **Alexa Devices** conecta os dispositivos **Echo** da sua conta
Amazon ao Portal, expondo-os como `media_player`, `switch`, `notify` e sensores.
Permite tocar música por busca, falar via TTS, fazer anúncios, controlar volume,
não perturbe (DND) e mais.

<Info>
  Esta integração é **diferente** da *Alexa Smart Home Skill*. Aqui, os
  dispositivos Alexa aparecem como entidades **dentro** do Portal (Portal manda
  comando para a Echo). Na Skill, é o contrário: a Alexa controla dispositivos
  do Portal por comando de voz.
</Info>

## Como funciona

A integração usa a **API interna** do site `alexa.amazon.com` (a mesma que o app
oficial e o `aioamazondevices` do Home Assistant usam). Faz login OAuth com
PKCE, guarda os cookies de sessão + `session-token`, e dispara comandos como
*sequences* no endpoint `/api/behaviors/preview`.

## Configurar

<Steps>
  <Step title="Adicione a integração">
    Vá em **Configurações → Integrações → Adicionar → Alexa Devices**.
  </Step>

  <Step title="Autentique">
    Informe **e-mail**, **senha** e **país** da sua conta Amazon. O Portal envia
    OTP por e-mail/SMS — digite o código no formulário.
  </Step>

  <Step title="Descoberta">
    Todos os dispositivos Echo vinculados à conta aparecem como entidades. Cada
    Echo gera um conjunto: `media_player`, `switch` (DND), `notify` (Speak +
    Announce), `binary_sensor` (online, DND) e — para modelos com sensores
    embutidos — `sensor` (temperatura, umidade).
  </Step>
</Steps>

<Warning>
  Se a Amazon retornar CAPTCHA no login, aguarde alguns minutos e tente de
  novo. O CAPTCHA aparece quando há muitas tentativas seguidas ou login de IP
  novo — não é bloqueio permanente.
</Warning>

## Entidades criadas

Para cada Echo descoberto:

| Plataforma      | `entity_id` (exemplo)           | O que faz                                                            |
| --------------- | ------------------------------- | -------------------------------------------------------------------- |
| `media_player`  | `media_player.<serial>_player`  | Play/pause/next/prev, volume, seleção de fonte, **reproduzir mídia** |
| `switch`        | `switch.<serial>_dnd`           | Ativa/desativa o modo Não Perturbe                                   |
| `notify`        | `notify.<serial>_speak`         | Fala texto na Echo (TTS)                                             |
| `notify`        | `notify.<serial>_announce`      | Faz anúncio com "ding-dong"                                          |
| `binary_sensor` | `binary_sensor.<serial>_online` | Echo online/offline                                                  |
| `binary_sensor` | `binary_sensor.<serial>_dnd`    | Estado do DND                                                        |
| `sensor`        | `sensor.<serial>_temperature`   | Temperatura (Echo Plus, Echo 4ª gen, Echo Studio)                    |
| `sensor`        | `sensor.<serial>_humidity`      | Umidade (mesmos modelos)                                             |

## Serviços disponíveis

| Serviço                                      | O que faz                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| `media_player.play_media`                    | **Tocar música por busca** em um provider (Amazon Music, Spotify, TuneIn, etc.) |
| `media_player.play`                          | Retomar reprodução                                                              |
| `media_player.pause` / `stop`                | Pausar (Echo não tem *stop* verdadeiro — mapeado para pause)                    |
| `media_player.next_track` / `previous_track` | Próxima / anterior                                                              |
| `media_player.set_volume`                    | Volume `0.0`–`1.0`                                                              |
| `media_player.mute`                          | Muta (`volume_level = 0`)                                                       |
| `media_player.select_source`                 | Trocar provider padrão (sem tocar nada — use `play_media` para tocar)           |
| `media_player.turn_off`                      | Pausa a mídia atual (Echo não desliga; fica em standby)                         |
| `notify.send_message`                        | TTS ou anúncio, dependendo da entidade `notify.*` escolhida                     |
| `switch.turn_on` / `turn_off`                | Liga/desliga o modo Não Perturbe                                                |

## Reproduzir mídia (`media_player.play_media`)

Diferente de Chromecast/Roku, a **Echo não aceita URL arbitrária**. Ela toca
**buscando** uma frase em um provider de música vinculado à conta Amazon. O
serviço traduz `media_content_type` → `musicProviderId` e envia a busca via a
sequence `Alexa.Music.PlaySearchPhrase`.

### Uso básico

```yaml theme={null}
service: media_player.play_media
target:
  entity_id: media_player.echo_sala_player
data:
  media_content_type: spotify
  media_content_id: "forró chico caceres"
```

### Providers suportados

O valor de `media_content_type` é convertido para o ID interno da Amazon:

| `media_content_type`                  | Provider Amazon (`musicProviderId`) | Requer                                      |
| ------------------------------------- | ----------------------------------- | ------------------------------------------- |
| *(qualquer coisa, incluindo `music`)* | `AMAZON_MUSIC`                      | Assinatura Amazon Music (Free ou Unlimited) |
| `spotify`                             | `SPOTIFY`                           | Spotify vinculado no app Alexa              |
| `apple_music`                         | `APPLE_MUSIC`                       | Apple Music vinculado                       |
| `tunein` / `tune_in` / `radio`        | `TUNEIN`                            | — (grátis)                                  |
| `pandora`                             | `PANDORA`                           | Conta Pandora (só EUA/AU/NZ)                |
| `iheart` / `i_heart_radio`            | `I_HEART_RADIO`                     | — (grátis)                                  |
| `siriusxm` / `sirius_xm`              | `SIRIUSXM`                          | Assinatura SiriusXM                         |

<Info>
  O provider precisa estar **vinculado à sua conta Amazon** e configurado no app
  oficial Alexa (em *Configurações → Música e Podcasts*). Se você tentar tocar
  no Spotify sem ter vinculado, a Echo responde com voz *"Não encontrei essa
  música no seu provedor padrão."*
</Info>

### Sobrescrever o provider via `extra`

Se você quiser usar `media_content_type` para outra finalidade (ex.: manter
`music` como tipo genérico) e escolher o provider dinamicamente:

```yaml theme={null}
service: media_player.play_media
target:
  entity_id: media_player.echo_cozinha_player
data:
  media_content_type: music
  media_content_id: "Rádio 89 FM"
  extra:
    provider: TUNEIN
```

Aceita `extra.provider`, `extra.providerId` ou `extra.music_provider_id`
(qualquer um funciona). Sempre normalizado para maiúsculas.

### Exemplos práticos

**Tocar uma música no Amazon Music (default):**

```yaml theme={null}
data:
  media_content_type: music
  media_content_id: "Aquarela do Brasil"
```

**Tocar uma playlist do Spotify:**

```yaml theme={null}
data:
  media_content_type: spotify
  media_content_id: "playlist descobertas da semana"
```

**Tocar uma estação de rádio no TuneIn:**

```yaml theme={null}
data:
  media_content_type: tunein
  media_content_id: "Jovem Pan São Paulo"
```

**Tocar um podcast específico:**

```yaml theme={null}
data:
  media_content_type: music
  media_content_id: "podcast Flow"
```

<Info>
  A Echo **sanitiza a frase** antes de tocar (chama
  `POST /api/behaviors/operation/validate` internamente). Se a Amazon achar a
  frase inválida ou censurável, retorna a versão saneada — o Portal usa a
  saneada mas mantém a original visível para você.
</Info>

## Falar e anunciar (`notify.send_message`)

Cada Echo cria duas entidades `notify`:

* **`notify.<serial>_speak`** — TTS puro (a Echo simplesmente fala o texto)
* **`notify.<serial>_announce`** — Anúncio com o "ding-dong" prefixado, formato
  "modo intercom" (aparece no display quando é Echo Show)

```yaml theme={null}
service: notify.send_message
target:
  entity_id: notify.echo_sala_speak
data:
  message: "A porta da frente foi aberta"
  title: "Portal"       # opcional; usado só no announce
```

## Modo Não Perturbe (DND)

O `switch.<serial>_dnd` liga/desliga o DND. Enquanto ativo, a Echo não faz sons
de notificação (Drop In, mensagens, timers com som suave). Alarmes ainda tocam.

```yaml theme={null}
service: switch.turn_on
target:
  entity_id: switch.echo_quarto_dnd
```

## Automações típicas

**"Boa noite" — ativa DND em todas as Echos às 22h:**

```yaml theme={null}
trigger:
  - platform: time
    at: "22:00:00"
action:
  - service: switch.turn_on
    target:
      entity_id:
        - switch.echo_quarto_dnd
        - switch.echo_sala_dnd
        - switch.echo_cozinha_dnd
```

**Tocar rádio ao chegar em casa:**

```yaml theme={null}
trigger:
  - platform: state
    entity_id: person.usuario
    to: "home"
action:
  - service: media_player.play_media
    target:
      entity_id: media_player.echo_sala_player
    data:
      media_content_type: tunein
      media_content_id: "Rádio Sulamérica Trânsito"
```

**Anúncio de campainha ao detectar movimento na câmera da porta:**

```yaml theme={null}
trigger:
  - platform: state
    entity_id: binary_sensor.camera_porta_motion
    to: "on"
action:
  - service: notify.send_message
    target:
      entity_id: notify.echo_sala_announce
    data:
      message: "Movimento detectado na porta da frente"
```

## Solução de problemas

* **`CAPTCHA_REQUIRED` no login** — Amazon detectou muitas tentativas. Aguarde
  10-15 minutos e tente novamente. Se persistir, use uma janela anônima do
  navegador para forçar novo IP/cookie no login.

* **`INVALID_CREDENTIALS: Código de autorização não encontrado`** — o OTP foi
  digitado errado ou expirou. Reinicie o fluxo — cada OTP é válido por poucos
  minutos.

* **`play_media` responde OK mas a Echo não toca nada** — provider não vinculado
  à conta. Abra o app oficial Alexa → *Configurações → Música e Podcasts* e
  confirme que o provider aparece como conectado. Também garanta que a Echo
  está online (`binary_sensor.<serial>_online = ON`).

* **`play_media` toca a música errada** — a Echo entende a frase como comando
  de voz. Seja específico: em vez de `"forró"`, use `"playlist forró pé de
  serra"` ou `"artista Falamansa"`.

* **Volume não atualiza no dashboard** — o `state` só sincroniza no polling
  (a cada 30 s). Após ajustar, aguarde um ciclo para o card refletir. O comando
  em si é aplicado imediatamente na Echo.

* **Media Player mostra "off" com a Echo ligada** — a Echo está online, mas sem
  mídia tocando (`state = idle`). O card exibe como `off` porque `turn_off`
  mapeia para "sem áudio". Não é bug — é o padrão do HA para speakers que ficam
  sempre em standby.

* **TTS/announce sem áudio** — verifique se o DND está ativo. Announces podem
  passar pelo DND, mas dependem do tipo do Echo. Se estiver, desligue via
  `switch.turn_off` antes.

## Referências técnicas

* Lib base (Python, HA): [aioamazondevices](https://github.com/chemelli74/aioamazondevices)
* Integração alternativa (referência mais ampla): [alexa\_media\_player](https://github.com/alandtse/alexa_media_player)
* Sequence types em uso: `Alexa.Speak`, `AlexaAnnouncement`,
  `Alexa.Music.PlaySearchPhrase`, `Alexa.DeviceControls.Volume`,
  `Alexa.DeviceControls.LocalMediaControls`