Installation

Copy Markdown View Source

This guide covers installing ExGram and configuring its dependencies.

Basic Installation

Add ex_gram and jason to your mix.exs dependencies:

def deps do
  [
    {:ex_gram, "~> 0.64"},
    {:jason, ">= 1.0.0"},
    # HTTP Adapter (see below)
  ]
end

After adding dependencies, run:

mix deps.get

HTTP Adapter

ExGram requires an HTTP adapter to communicate with the Telegram Bot API. Choose one of the following options.

The Req adapter is the simplest to set up and is recommended for most use cases.

Add to deps:

{:req, "~> 0.5"}

Add to config:

config :ex_gram, adapter: ExGram.Adapter.Req

Tesla Adapter

Tesla provides more flexibility and supports multiple underlying HTTP clients.

Add to deps:

{:tesla, "~> 1.16"},
{:hackney, "~> 3.2"}  # Default client

Add to config:

config :ex_gram, adapter: ExGram.Adapter.Tesla

Tesla Underlying Adapters

Tesla supports several HTTP clients. The default is Hackney, but you can use:

  • Finch - Modern, efficient HTTP client
  • Gun - HTTP/1.1 and HTTP/2 client
  • Mint - Low-level HTTP client
  • Httpc - Built into Erlang
  • Ibrowse - Another Erlang HTTP client

Example using Gun:

# In deps
{:tesla, "~> 1.16"},
{:gun, "~> 2.0"}

# In config
config :tesla, adapter: Tesla.Adapter.Gun

Tesla Logger Configuration

By default, ExGram adds Tesla.Middleware.Logger with log level :info.

You can configure the log level and other options (Tesla Logger docs):

config :ex_gram, Tesla.Middleware.Logger, level: :debug

Tesla Middlewares

You can add custom Tesla middlewares to ExGram:

config :ex_gram, ExGram.Adapter.Tesla,
  middlewares: [
    {Tesla.Middleware.BaseUrl, "https://example.com/foo"}
  ]

For middlewares that require functions or complex configuration, define a function that returns the Tesla configuration:

# lib/tesla_middlewares.ex
defmodule TeslaMiddlewares do
  def retry() do
    {Tesla.Middleware.Retry,
     delay: 500,
     max_retries: 10,
     max_delay: 4_000,
     should_retry: fn
       {:ok, %{status: status}} when status in [400, 500] -> true
       {:ok, _} -> false
       {:error, _} -> true
     end}
  end
end

# config/config.exs
config :ex_gram, ExGram.Adapter.Tesla,
  middlewares: [
    {TeslaMiddlewares, :retry, []}
  ]

The function must return a two-tuple as Tesla requires.

Custom Adapter

You can implement your own HTTP adapter by implementing the ExGram.Adapter behaviour:

config :ex_gram, adapter: YourCustomAdapter

JSON Engine

By default, ExGram uses Jason for JSON encoding/decoding. You can change it to any engine that exposes encode/2, encode!/2, decode/2, and decode!/2:

config :ex_gram, json_engine: Poison

Next Steps