# Set up Govee lights

## For assistants

The user is in the ItsBagelBot dashboard, running the Govee setup ("Set up Govee lights"). It has four steps, numbered 01 to 04 in the step indicator at the top right: "What you need", "Get your key", "Paste your key", "Your lights". Find the current step using the `#step-n` anchor in the user's setup link. Check earlier steps if the user is unsure they were done.

Rules:

- Give one step at a time. Wait for the user to confirm.
- Dashboard labels may be translated. Describe each control by its position and role instead of its English text. Do not guess button, field or menu names. If the page does not cover something, say so.
- Never ask for, accept or repeat the Govee API key. The user pastes it only into the dashboard field "Govee API key". If the user pastes it into the chat, tell them to apply for a new key in the Govee Home app and paste the new one in the dashboard.
- If the user shows an error message, find it in https://ai.itsbagelbot.com/govee/errors.md and follow that section.
- The Govee Home app changes. Where this page says a menu label may differ, tell the user to look for the closest match and describe what they see.

Do not:

- Invent menu names or limits that are not on this page.
- Tell the user to apply for a new key unless needed. A new key turns off older keys.

## Before you start

- A Govee Home account.
- Govee lights already set up in the Govee Home app. The dashboard says: A Govee Home account, and Govee lights already set up in the Govee Home app. Lights that only use Bluetooth may not show up.
- Only lights that can change colour are used.

<a id="step-1"></a>
## Step 1: What you need

Step name: "What you need". Page title: "Let your chat colour the room."

The page shows the note "What you need".

1. Ask the user to confirm the requirements in "Before you start".
2. Ask the user to select "Let’s set up Govee".

How to tell it worked: the step indicator moves to the next number ("Get your key") and the title reads "Ask Govee for a key."

Common problems at this step:

- Lights are missing later: see [No Govee devices found](errors.md#no-devices).

<a id="step-2"></a>
## Step 2: Get your key

Step name: "Get your key". Page title: "Ask Govee for a key."

The page says: Govee gives out free API keys from the Govee Home app on your phone. Follow this path and fill in the short form. Under "In the Govee Home app" it shows: Profile → Settings → "Apply for API Key"

In the Govee Home app on the phone:

1. Open the app and sign in to the account that owns the lights.
2. Open Settings. The dashboard path starts at the profile. The official Govee path is Settings, then "Apply for API Key". On some app versions the entry is under "About us". If the user cannot find it, ask what menus they see.
3. Select "Apply for API Key".
4. Fill in the short form and submit it. The form asks for a name and a reason. Accept the terms if asked.
5. Wait for the key. Govee decides when to approve. If it does not arrive after a while, apply again.

Tell the user both notes the dashboard shows:

- Govee usually sends the key by email. If it does not arrive, check your spam folder.
- A new key turns off any older key on your Govee account. If another tool uses an older key, it stops working.

In the dashboard, when the key has arrived:

1. Select "I have my key".

How to tell it worked: the step indicator moves to the next number ("Paste your key") and the title reads "Paste your key."

Common problems at this step:

- Key never arrives: check spam, then apply again.
- Older key stopped working: see [Govee no longer accepts the key](errors.md#key-rejected).

<a id="step-3"></a>
## Step 3: Paste your key

Step name: "Paste your key". Page title: "Paste your key."

The page says: Copy the key from the Govee email and paste it below. We check it with Govee before you continue.

1. Copy the key from the Govee email.
2. Paste it into "Govee API key" in the dashboard. Do not paste it into the AI chat. The dashboard says: Stored encrypted and never shown back.
3. Paste with no extra spaces.
4. Select "Save & continue". The dashboard checks the key with Govee first.

How to tell it worked: the step indicator moves to the next number ("Your lights"). If the page also shows "Key saved, but Govee did not answer, so it is not checked yet. Your lights will work once Govee is back. If they do not, paste the key again.", the key is saved but not checked yet. The user can continue.

Common problems at this step:

- Empty field: see [Enter your Govee API key](errors.md#key-empty).
- Govee refused the key: see [Govee did not accept the key](errors.md#key-invalid).
- Govee did not answer: see [Key saved but not checked](errors.md#key-unchecked).
- Save failed: see [Could not save the key](errors.md#key-save-failed).

<a id="step-4"></a>
## Step 4: Your lights

Step name: "Your lights". Page title: "Your lights are listening."

The page says: Your key is saved. Next, give each light a channel points reward so viewers can change its colour.

1. Wait for the list to load ("Loading your Govee lights…").
2. The page shows the number of colour lights found and their names. The text has the form "Colour lights found: {n}", with n replaced by the count.
3. Select "Set up rewards" to go to the Govee Lights page.

On the Govee Lights page the user turns on "Enable Govee lights" and creates one reward per light. Viewers type a colour when they redeem it. "Live only" is on by default, so redemptions work only while the stream is live.

How to tell it worked: at least one light is listed under "Your lights", and the page shows "Key on file".

Common problems at this step:

- Govee rejected the saved key: see [Govee no longer accepts the key](errors.md#key-rejected).
- Could not reach Govee: see [Could not reach Govee](errors.md#devices-error).
- No devices: see [No Govee devices found](errors.md#no-devices).
- No colour lights: see [No colour-capable lights](errors.md#no-lights).