Build Your First Bot

View Source

This guide shows the shortest OTP path from a new supervised Mix app to a Nadia bot. It uses long polling, so no web framework or webhook endpoint is required.

Start with an OTP application:

mix new my_app --sup
cd my_app

1. Add Nadia

Add Nadia to your dependencies and fetch it:

def deps do
  [
    {:nadia, "~> 1.4"}
  ]
end
mix deps.get

2. Generate a bot handler

Run the generator with the module name you want for your bot:

mix nadia.gen.bot MyApp.Bot --polling

The task creates a handler module and an offline test that uses a fake Nadia HTTP client. It also prints the config and supervision snippets to paste into your application.

3. Configure the bot token

Store the token outside source control and read it at runtime in config/runtime.exs:

config :nadia,
  token: {:system, "TELEGRAM_BOT_TOKEN"}

For applications with more than one bot, use a named client instead in the same runtime config:

config :nadia,
  bots: [
    support: [
      token: {:system, "SUPPORT_BOT_TOKEN"}
    ]
  ]

Then pass client: Nadia.Client.from_config(:support) in the polling child spec.

4. Supervise polling

Add the polling worker to the children list in lib/my_app/application.ex:

children = [
  {Nadia.Polling,
   handler: MyApp.Bot,
   allowed_updates: ["message"],
   timeout: 30}
]

Nadia.Polling calls getUpdates, dispatches each update through your handler, and stores the next offset in memory. It acknowledges an update after the handler returns :ok, :ignore, or {:ok, value}. Handler errors and API errors are retried with bounded backoff without acknowledging the failed update.

5. Run locally

Run the generated test first:

mix test

Then start the app with your bot token:

TELEGRAM_BOT_TOKEN=123:token mix run --no-halt

Send /start to the bot in Telegram. The generated handler replies with Ready and echoes plain text messages.