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.

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.

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

Adicione a integração

Vá em Configurações → Integrações → Adicionar → Alexa Devices.

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.

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

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.

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

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

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

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:

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

data:
  media_content_type: music
  media_content_id: "Aquarela do Brasil"

Tocar uma playlist do Spotify:

data:
  media_content_type: spotify
  media_content_id: "playlist descobertas da semana"

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

data:
  media_content_type: tunein
  media_content_id: "Jovem Pan São Paulo"

Tocar um podcast específico:

data:
  media_content_type: music
  media_content_id: "podcast Flow"

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

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)

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.

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:

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:

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:

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
Integração alternativa (referência mais ampla): alexa_media_player
Sequence types em uso: Alexa.Speak, AlexaAnnouncement, Alexa.Music.PlaySearchPhrase, Alexa.DeviceControls.Volume, Alexa.DeviceControls.LocalMediaControls

​Alexa Devices

​Como funciona

​Configurar

​Entidades criadas

​Serviços disponíveis

​Reproduzir mídia (media_player.play_media)

​Uso básico

​Providers suportados

​Sobrescrever o provider via extra

​Exemplos práticos

​Falar e anunciar (notify.send_message)

​Modo Não Perturbe (DND)

​Automações típicas

​Solução de problemas

​Referências técnicas

Alexa Devices

Como funciona

Configurar

Entidades criadas

Serviços disponíveis

Reproduzir mídia (`media_player.play_media`)

Uso básico

Providers suportados

Sobrescrever o provider via `extra`

Exemplos práticos

Falar e anunciar (`notify.send_message`)

Modo Não Perturbe (DND)

Automações típicas

Solução de problemas

Referências técnicas