Skip to main content
This guide takes you through the whole setup: create your account, connect Home Assistant, link Telegram, add credits, and send your first message.

​
Before you begin

You’ll need:
  • A running Home Assistant instance (2024.12 or newer) with HACS installed.
  • A Telegram account.
  • About ten minutes.
You don’t need to open ports, have a public IP, or configure DNS or a VPN.

​
1. Create your account

1

Open the sign-in page

Go to homiagent.app/login.
2

Enter your email

We’ll email you a temporary access code.
3

Enter the code

You’re signed in.
There’s no password and no separate sign-up step. Your account is created the first time you sign in with a new email.
Access codes expire after 15 minutes. If yours expires, just request a new one.

​
2. Install the integration in Home Assistant

HomiAgent connects to your home through the HomiAgent Bridge integration.

HomiAgent Bridge on GitHub

https://github.com/homiagent/homiagent-bridge
Shortcut: open the repository directly in your Home Assistant’s HACS. It fills in step 1 for you, so you can go straight to Download.
1

Add the custom repository

In Home Assistant, open HACS, open the ⋮ menu (top right), and choose Custom repositories. Paste https://github.com/homiagent/homiagent-bridge, set the type to Integration, and click Add.
2

Download the integration

Search for HomiAgent Bridge in HACS and click Download.
3

Restart Home Assistant

The integration only shows up after a restart.

​
3. Connect your home

1

Generate a pairing key

In the HomiAgent dashboard, click Generate pairing key and copy the key that appears.
2

Add the integration

In Home Assistant, go to Settings → Devices & Services → Add Integration, search for HomiAgent Bridge, and select it.
3

Paste the key

Paste the pairing key and submit.
4

Check the dashboard

Refresh the HomiAgent dashboard. Your home should show up under Connected homes as online.
Pairing keys expire after 10 minutes and work only once. If Home Assistant says the key is invalid, expired, or already used, generate a new one in the dashboard and try again.
Once it’s connected, HomiAgent syncs your rooms, devices, and services automatically. In Home Assistant, a connectivity sensor on the integration shows whether the link is up. If the connection drops, the integration reconnects on its own.
1

Get a link code

In the HomiAgent dashboard, open Telegram and click Link account. Copy the message shown. It looks like /connect ABC123.
2

Message the bot

In Telegram, search for the HomiAgent bot and send it that message.
3

Confirm

The bot confirms the link. Refresh the dashboard and your Telegram account appears under Linked accounts.
Link codes expire after 10 minutes. You can link more than one Telegram account, for example one for each person in your household.

​
5. Add credits

HomiAgent runs on prepaid credits, and you’ll need some before the assistant can answer.
1

Send /buy

In the HomiAgent chat on Telegram, send /buy.
2

Pick an amount

The menu shows your current balance and the minimum top-up.
3

Pay

Finish the payment on the checkout page that opens. You’ll be sent back to Telegram afterwards.
Credits show up in your balance as soon as the payment is confirmed. Your balance is also shown on the dashboard home page.

​
6. Send your first message

Try something simple in the HomiAgent chat:
Which lights are on right now?
Then try an action:
Turn off the kitchen lights.
You can also hold the microphone button and say it out loud. If HomiAgent isn’t sure which device you mean, it asks before acting.

​
Bot commands

​
Troubleshooting

Check that Home Assistant is running and has internet access. Under Settings → Devices & Services → HomiAgent Bridge, look at the connectivity sensor. If the key expired before pairing finished, generate a new key in the dashboard and use Reconfigure on the integration to paste it.
Send /buy to top up. It works even when your balance is zero.
Generate a new link code from Telegram → Link account and send the /connect message again.

​
Next step

Context matters

Name your entities, assign areas, and use HomiAgent labels so the assistant gets it right the first time.