Skip to content

Alexa Custom Skill -> Forge Bots, Setup Handoff

URL: https://mkdocs.justinsforge.com/memory/handoffs/alexa-forge-skill-setup-2026-05-20/

What this does

Lets you say (to any Echo): - "Alexa, tell Forge send turn off the printer to coordinator" - "Alexa, ask Forge to ping remote with check the deploy"

Free-text after "send" or "ping ... with" is captured (AMAZON.SearchQuery slot) and POSTed to Home Assistant, which calls a local webhook on Console, which delivers the text to the bot's chat (visible) and runs the bot's brain on it.

What's already done on the server side

  • forge_alexa_to_bot.py + forge_alexa_webhook.py on Console:7360 (systemd forge-alexa-webhook.service)
  • HA alexa: intent: + intent_script: SendCoordinatorIntent / SendRemoteIntent + two rest_command entries
  • HA restarted, end-to-end smoke tested (HA -> webhook -> brain -> Telegram chat works)

The only thing left is the Amazon Developer Console skill, which has to be created interactively from a logged-in Amazon account.

Amazon Developer Console steps

1. Create the skill

  1. Go to https://developer.amazon.com/alexa/console/ask (log in with the same Amazon account your Echo uses)
  2. Click Create Skill
  3. Skill name: Forge
  4. Primary locale: English (US)
  5. Choose a model: Custom
  6. Choose hosting: Provision your own
  7. Click Create skill, then on the next screen pick Start from Scratch -> Continue

2. Set invocation name

  1. Left sidebar -> Invocation -> Skill Invocation Name
  2. Set to: forge
  3. Save

3. Add the two intents

In the left sidebar -> Interaction Model -> JSON Editor, paste this and click Save Model:

{
  "interactionModel": {
    "languageModel": {
      "invocationName": "forge",
      "intents": [
        { "name": "AMAZON.CancelIntent", "samples": [] },
        { "name": "AMAZON.HelpIntent", "samples": [] },
        { "name": "AMAZON.StopIntent", "samples": [] },
        {
          "name": "SendCoordinatorIntent",
          "slots": [
            { "name": "Message", "type": "AMAZON.SearchQuery" }
          ],
          "samples": [
            "send {Message} to coordinator",
            "tell coordinator {Message}",
            "coordinator {Message}",
            "to coordinator {Message}"
          ]
        },
        {
          "name": "SendRemoteIntent",
          "slots": [
            { "name": "Message", "type": "AMAZON.SearchQuery" }
          ],
          "samples": [
            "ping remote with {Message}",
            "tell remote {Message}",
            "remote {Message}",
            "to remote {Message}"
          ]
        }
      ],
      "types": []
    }
  }
}

Then click Build Model (top of page). Wait ~30 sec for green checkmark.

4. Configure the endpoint

  1. Left sidebar -> Endpoint
  2. Service Endpoint Type: HTTPS
  3. Default Region URL: https://homeassistant.justinkrystal.com/api/alexa
  4. SSL certificate type for Default Region:
  5. Pick My development endpoint has a certificate from a trusted certificate authority (your Cloudflare tunnel cert is trusted)
  6. Click Save Endpoints

5. Account Linking (REQUIRED)

  1. Left sidebar -> Account Linking
  2. Toggle Do you allow users to create an account or link to an existing account with you? -> ON
  3. Allow users to enable skill without account linking: OFF (leave default)
  4. Security Provider Information -> Auth Code Grant
  5. Fill in exactly:
Field Value
Your Web Authorization URI https://homeassistant.justinkrystal.com/auth/authorize
Access Token URI https://homeassistant.justinkrystal.com/auth/token
Your Client ID https://pitangui.amazon.com/ (this is literally Amazon's US redirect URL; HA accepts it as client id)
Your Secret notused (HA ignores this)
Your Authentication Scheme Credentials in request body
Scope leave blank
  1. Domain List (bottom): add homeassistant.justinkrystal.com
  2. Default Access Token Expiration Time -> leave blank
  3. At the very bottom note the three Redirect URLs Amazon shows (e.g. https://pitangui.amazon.com/api/skill/link/...). You don't need to paste them anywhere, but verify they exist.
  4. Click Save

6. Enable testing

  1. Left sidebar -> Test (top tab)
  2. Skill testing is enabled in: change to Development
  3. The web simulator now works for typed tests, but you want the real Echo.
  1. Open the Alexa app on your phone
  2. Settings -> Skills & Games -> Your Skills -> Dev tab
  3. Tap "Forge"
  4. Tap Enable to Use
  5. It opens HA's login page, log in
  6. Approve the link
  7. Done

8. Test

Say to your Echo: - "Alexa, tell forge to send turn off the printer to coordinator" - "Alexa, ask forge to ping remote with check on Plex"

Alexa replies "Sent to coordinator." / "Sent to remote." and ~1-3 sec later the message appears in your Telegram chat with the bot, with the brain's reply right after.

Troubleshooting

  • Alexa says "Forge isn't responding right now" -> check journalctl -u forge-alexa-webhook -n 50 on Console
  • "Account not linked" voice error -> redo step 7
  • Alexa transcribes but nothing happens -> check HA log at Settings -> System -> Logs for intent_script errors
  • Brain reply never arrives -> the brain ran fine in smoke test; if voice path skips it, check /home/justinwieb/forge/logs/forge-alexa-webhook.log

Files created/modified this session

Path Purpose
/home/justinwieb/forge/scripts/forge_alexa_to_bot.py Coordinator/remote dispatcher (visible msg + brain)
/home/justinwieb/forge/scripts/forge_alexa_webhook.py HTTP receiver on Console:7360
/home/justinwieb/.forge-secrets/forge-alexa-webhook.env WEBHOOK_SECRET
/etc/systemd/system/forge-alexa-webhook.service Auto-start the webhook
/config/configuration.yaml (HA) alexa: + intent_script: + two rest_command entries

Webhook secret is also embedded in HA's rest_command payloads. Rotate by editing both files and restarting both services.