Alexa Speak API

Servidor HTTP para fazer a Alexa falar mensagens via requisições POST. Ideal para integrar notificações de sistemas externos (vendas, alertas, lembretes) com dispositivos Echo.

Funcionalidades

• Enviar mensagens de voz para dispositivos Alexa
• Sons de notificação por tipo (info, success, warning, error)
• Controle de volume da fala via SSML (sem alterar volume do dispositivo)
• Controle de volume do dispositivo com restauração automática
• Autenticação via API Key
• Suporte a múltiplos dispositivos

Instalação

# Clonar e instalar dependências
npm install

# Copiar e configurar variáveis de ambiente
cp .env.example .env
# Editar .env com suas configurações

Configuração

Variáveis de Ambiente (.env)

# API Key para autenticação (gere uma chave segura)
API_KEY=sua-chave-secreta-aqui

# Nome do dispositivo Alexa padrão
ALEXA_DEVICE=Echo Dot

# Porta do servidor
PORT=3000

# Caminho para salvar cookies de autenticação
COOKIE_PATH=./alexa-cookie.json

# Região Amazon
AMAZON_DOMAIN=amazon.com.br

Autenticação com Amazon

Na primeira execução, acesse http://localhost:3001 e faça login na sua conta Amazon. O cookie será salvo automaticamente.

Uso

Iniciar o servidor

npm start
# ou em modo desenvolvimento com hot reload
npm run dev

Endpoints

Método	Rota	Descrição
POST	/speak	Envia mensagem para Alexa falar
GET	/health	Health check (sem autenticação)
GET	/devices	Lista dispositivos disponíveis
POST	/set-cookie	Define cookie manualmente

POST /speak

Faz a Alexa falar uma mensagem.

Headers

Content-Type: application/json
x-api-key: sua-api-key

Body

Campo	Tipo	Padrão	Descrição
message	string	obrigatório	Mensagem a ser falada (max 500 chars)
device	string	ALEXA_DEVICE	Nome do dispositivo
beep	boolean	true	Tocar som antes da mensagem
type	string	"info"	Tipo: info, success, warning, error
sfx	string	-	Som customizado (sobrescreve type)
speechVolume	string	"medium"	Volume SSML da fala
alertVolume	number	-	Volume do dispositivo (0-100), restaura após
sfxRepeat	number	1	Quantas vezes repetir o som (1-10)
messageRepeat	number	1	Quantas vezes repetir a mensagem (1-10)
repeat	number	1	Quantas vezes repetir o conjunto som+mensagem (1-10)

speechVolume (SSML)

Controla o volume da fala sem alterar o volume do dispositivo (sem beeps de confirmação):

• silent - Silencioso
• x-soft - Muito baixo
• soft - Baixo
• medium - Médio (padrão)
• loud - Alto
• x-loud - Muito alto

alertVolume

Altera o volume do dispositivo temporariamente:

1. Obtém volume atual
2. Altera para alertVolume
3. Toca som + fala
4. Restaura volume anterior

Nota: Isso pode gerar beep de confirmação da Alexa.

Exemplos

Notificação básica

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{"message": "Nova venda realizada!"}'

Notificação de sucesso

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Parabéns! Você vendeu R$ 500",
    "type": "success"
  }'

Fala mais suave (SFX mais alto em comparação)

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Nova venda!",
    "type": "success",
    "speechVolume": "soft"
  }'

Alerta urgente com volume alto

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Atenção! Sistema fora do ar!",
    "type": "error",
    "alertVolume": 90
  }'

Combinado: volume alto + fala suave

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Nova venda de R$ 1000!",
    "type": "success",
    "alertVolume": 80,
    "speechVolume": "soft"
  }'

Mensagem sem som

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Lembrete silencioso",
    "beep": false
  }'

Dispositivo específico

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Mensagem para a cozinha",
    "device": "Echo da Cozinha"
  }'

Resposta

{
  "success": true,
  "message": "Mensagem enviada para Alexa",
  "device": "Echo Dot da sala de casa",
  "beep": true,
  "type": "success",
  "speechVolume": "soft",
  "alertVolume": 80,
  "previousVolume": 30
}

Sons de Notificação

Sons Padrão por Tipo

Tipo	Som	Descrição
info	amzn_sfx_doorbell_chime_01	Campainha
success	amzn_sfx_trumpet_bugle_04	Fanfarra/Trompete
warning	amzn_sfx_church_bell_1x_02	Sino de igreja
error	amzn_sfx_scifi_alarm_04	Alarme sci-fi

Som Customizado (sfx)

Use o parâmetro sfx para tocar outros sons. Importante: apenas sons do tipo amzn_sfx_* funcionam via alexa-remote2 (os mesmos disponíveis nas Rotinas do app Alexa). Sons com formato soundbank:// NÃO funcionam - esses só funcionam em Alexa Skills.

Sons Disponíveis

Campainhas:

• amzn_sfx_doorbell_01
• amzn_sfx_doorbell_chime_01
• amzn_sfx_doorbell_chime_02

Alarmes/Alertas:

• amzn_sfx_scifi_alarm_01 - Sirene
• amzn_sfx_scifi_alarm_04 - Alerta vermelho
• amzn_sfx_scifi_engines_on_02
• amzn_sfx_scifi_sheilds_up_01

Celebração:

• amzn_sfx_trumpet_bugle_04 - Fanfarra
• amzn_sfx_large_crowd_cheer_01 - Torcida
• amzn_sfx_crowd_applause_01 - Aplausos

Sinos:

• amzn_sfx_church_bell_1x_02 - Sino de igreja
• bell_02

Animais:

• amzn_sfx_dog_med_bark_1x_02 - Cachorro
• amzn_sfx_cat_meow_1x_01 - Gato
• amzn_sfx_wolf_howl_02 - Lobo
• amzn_sfx_lion_roar_02 - Leão
• amzn_sfx_rooster_crow_01 - Galo

Outros:

• air_horn_03 - Buzina de ar (única buzina que funciona)
• boing_01, boing_03 - Boing
• buzzers_pistols_01 - Buzzer
• camera_01 - Câmera
• clock_01 - Relógio
• zap_01 - Zap

Casos de Uso Práticos

Nova venda com buzina

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Nova venda realizada!",
    "sfx": "air_horn_03",
    "alertVolume": 80
  }'

Notificação com torcida

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Parabéns pela meta atingida!",
    "sfx": "amzn_sfx_large_crowd_cheer_01"
  }'

Campainha - alguém na porta

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Tem alguém na porta",
    "sfx": "amzn_sfx_doorbell_chime_01",
    "alertVolume": 70
  }'

Buzina 3x + mensagem (sfxRepeat)

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Nova venda!",
    "sfx": "air_horn_03",
    "sfxRepeat": 3
  }'

Repetir conjunto completo 2x (repeat)

curl -X POST http://localhost:3000/speak \
  -H "Content-Type: application/json" \
  -H "x-api-key: sua-api-key" \
  -d '{
    "message": "Atenção!",
    "sfx": "air_horn_03",
    "repeat": 2
  }'

Docker

# Build
docker build -t alexa-speak .

# Run
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/alexa-cookie.json:/app/alexa-cookie.json \
  -e API_KEY=sua-api-key \
  -e ALEXA_DEVICE="Echo Dot" \
  -e AMAZON_DOMAIN=amazon.com.br \
  alexa-speak

Kubernetes

Arquivos de deploy disponíveis em k8s/.

Estrutura do Projeto

alexa-speak/
├── src/
│   ├── index.js      # Servidor Express e rotas
│   ├── alexa.js      # Integração com alexa-remote2
│   └── auth.js       # Middleware de autenticação
├── patches/          # Patches para dependências
├── k8s/              # Manifests Kubernetes
├── .env.example      # Exemplo de variáveis de ambiente
├── Dockerfile        # Build Docker
└── package.json

Referências

• alexa-remote2 - Biblioteca de integração
• Amazon SSML Reference
• Alexa Sound Library

Licença

MIT