# Nadia

[![Elixir CI](https://github.com/zhyu/nadia/actions/workflows/elixir.yml/badge.svg)](https://github.com/zhyu/nadia/actions/workflows/elixir.yml)
[![Module Version](https://img.shields.io/hexpm/v/nadia.svg)](https://hex.pm/packages/nadia)
[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/nadia/)
[![Total Download](https://img.shields.io/hexpm/dt/nadia.svg)](https://hex.pm/packages/nadia)
[![License](https://img.shields.io/hexpm/l/nadia.svg)](https://github.com/zhyu/nadia/blob/master/LICENSE)
[![Last Updated](https://img.shields.io/github/last-commit/zhyu/nadia.svg)](https://github.com/zhyu/nadia/commits/master)

Telegram Bot API Wrapper written in Elixir ([document](https://hexdocs.pm/nadia/))

## Installation

Nadia requires Elixir 1.20 or later and Erlang/OTP 27 or later.

Add `:nadia` to your `mix.exs` dependencies:

```elixir
def deps do
  [
    {:nadia, "~> 0.9.0"}
  ]
end
```

And run `$ mix deps.get`.

## Configuration

In `config/config.exs`, add your Telegram Bot token like [this](config/config.exs.example)

```elixir
config :nadia,
  token: "bot token"
```

You can also add an optional `recv_timeout` in seconds (defaults to 5s):

```elixir
config :nadia,
  recv_timeout: 10
```

You can also add a proxy support:

```elixir
config :nadia,
  proxy: "http://proxy_host:proxy_port",
  proxy_auth: {"user", "password"}
```

Nadia uses Req as its HTTP client. Proxy configuration supports HTTP and HTTPS
proxies accepted by Req/Mint; hackney-specific SOCKS options are no longer
supported.

You can also configure the the base url for the api if you need to for some
reason:

```elixir
config :nadia,
  # Telegram API. Default: https://api.telegram.org/bot
  base_url: "http://my-own-endpoint.com/whatever/",

  # Telegram Graph API. Default: https://api.telegra.ph
  graph_base_url: "http://my-own-endpoint.com/whatever/"
```

Environment variables may be used as well:

```elixir
config :nadia,
  token: {:system, "ENVVAR_WITH_MYAPP_TOKEN", "default_value_if_needed"}
```

For applications that need more than one bot, configure named bots and build
explicit clients from those names:

```elixir
config :nadia,
  bots: [
    support: [
      token: {:system, "SUPPORT_BOT_TOKEN"},
      recv_timeout: 10
    ],
    alerts: [
      token: {:system, "ALERTS_BOT_TOKEN"},
      proxy: "http://proxy_host:proxy_port"
    ]
  ]
```

```elixir
support_bot = Nadia.Client.from_config(:support)
alerts_bot = Nadia.Client.from_config(:alerts)

Nadia.send_message(support_bot, support_chat_id, "How can we help?")
Nadia.send_message(alerts_bot, alerts_chat_id, "Alert triggered")
```

The top-level `:token` configuration remains the default client for existing
calls such as `Nadia.get_me()` and `Nadia.send_message(chat_id, text)`.

## Usage

### `get_me`

```elixir
iex> Nadia.get_me
{:ok,
 %Nadia.Model.User{first_name: "Nadia", id: 666, last_name: nil,
  username: "nadia_bot"}}
```

### `get_updates`

```elixir
iex> Nadia.get_updates limit: 5
{:ok, []}

iex> {:ok,
 [%Nadia.Model.Update{callback_query: nil, chosen_inline_result: nil,
   edited_message: nil, inline_query: nil,
   message: %Nadia.Model.Message{audio: nil, caption: nil,
    channel_chat_created: nil,
    chat: %Nadia.Model.Chat{first_name: "Nadia", id: 123,
     last_name: "TheBot", title: nil, type: "private", username: "nadia_the_bot"},
    contact: nil, date: 1471208260, delete_chat_photo: nil, document: nil,
    edit_date: nil, entities: nil, forward_date: nil, forward_from: nil,
    forward_from_chat: nil,
    from: %Nadia.Model.User{first_name: "Nadia", id: 123,
     last_name: "TheBot", username: "nadia_the_bot"}, group_chat_created: nil,
    left_chat_member: nil, location: nil, message_id: 543,
    migrate_from_chat_id: nil, migrate_to_chat_id: nil, new_chat_member: nil,
    new_chat_photo: [], new_chat_title: nil, photo: [], pinned_message: nil,
    reply_to_message: nil, sticker: nil, supergroup_chat_created: nil,
    text: "rew", venue: nil, video: nil, voice: nil}, update_id: 98765}]}
```

### `send_message`

```elixir
iex> case Nadia.send_message(tlg_id, "The message text goes here") do
  {:ok, _result} ->
    :ok
  {:error, %Nadia.Model.Error{reason: "Please wait a little"}} ->
    :wait
  end

:ok
```

Refer to [Nadia document](https://hexdocs.pm/nadia/) and [Telegram Bot API document](https://core.telegram.org/bots/api) for more details.

## Testing

The default test suite is offline and credential-free:

```sh
mix test
```

Optional live Telegram smoke tests are tagged with `:telegram_live` and are not
run by default:

```sh
mix test --only telegram_live
```

Live tests require two bots with Bot-to-Bot Communication Mode enabled in
BotFather. Configure credentials by copying the committed seed file to the
ignored local env file, then edit the local file:

```sh
cp .env.live.local.example .env.live.local
chmod 600 .env.live.local
${EDITOR:-vi} .env.live.local
```

The local `.env.live.local` file should define:

```sh
export NADIA_LIVE_BOT_A_TOKEN="123:bot-a-token"
export NADIA_LIVE_BOT_A_USERNAME="bot_a_username"
export NADIA_LIVE_BOT_B_TOKEN="456:bot-b-token"
export NADIA_LIVE_BOT_B_USERNAME="bot_b_username"
```

Then source the local file and run the live suite from the same shell:

```sh
source .env.live.local
mix test --only telegram_live
```

Set `NADIA_LIVE_API_ENV=test` in `.env.live.local` to route live smoke tests
through Telegram's Bot API test environment.

## Copyright and License

Copyright (c) 2015 Yu Zhang

This library licensed under the [MIT license](./LICENSE.md).