Hedwig Telegram Adapter

A Telegram Adapter for Hedwig

Getting started

Let's generate a new Elixir application with a supervision tree:

λ mix new alfred --sup
* creating README.md
* creating .gitignore
* creating mix.exs
* creating config
* creating config/config.exs
* creating lib
* creating lib/alfred.ex
* creating test
* creating test/test_helper.exs
* creating test/alfred_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd alfred
    mix test

Run "mix help" for more commands.

Change into our new application directory:

λ cd alfred

Add hedwig_telegram to your list of dependencies in mix.exs:

def deps do
  [{:hedwig_telegram, "~> 0.1.0"}]
end

Ensure hedwig_telegram is started before your application:

def application do
  [applications: [:hedwig_telegram]]
end

Generate our robot

λ mix hedwig.gen.robot

Welcome to the Hedwig Robot Generator!

Let's get started.

What would you like to name your bot?: alfred

Available adapters

1. Hedwig.Adapters.Telegram
2. Hedwig.Adapters.Console
3. Hedwig.Adapters.Test

Please select an adapter: 1

* creating lib/alfred
* creating lib/alfred/robot.ex
* updating config/config.exs

Don't forget to add your new robot to your supervision tree
(typically in lib/alfred.ex):

    worker(Alfred.Robot, [])

Supervise our robot

We'll want Alfred to be supervised and started when we start our application. Let's add it to our supervision tree. Open up lib/alfred.ex and add the following to the children list:

worker(Alfred.Robot, [])

Configuration

The next thing we need to do is configure our bot. Open up config/config.exs and let's take a look at what was generated for us:

use Mix.Config

config :alfred, Alfred.Robot,
  adapter: Hedwig.Adapters.Telegram,
  name: "alfred",
  aka: "/",
  responders: [
    {Hedwig.Responders.Help, []},
    {Hedwig.Responders.Ping, []}
  ]

So we have the adapter, name, aka, and responders set. The adapter is the module responsible for handling all of the Telegram details like connecting and sending and receiving messages over the network. The name is the name that our bot will respond to. The aka (also known as) field is optional, but it allows us to address our bot with an alias. By default, this alias is set to /.

Finally we have responders. Responders are modules that provide functions that match on the messages that get sent to our bot. We'll discuss this further in a bit.

We'll need to provide a few more things in order for us to connect to our Telegram server. We'll need to provide our bot's API key like:

use Mix.Config

config :alfred, Alfred.Robot,
  adapter: Hedwig.Adapters.Telegram,
  name: "alfred",
  aka: "/",
  # fill in the appropriate API token for your bot
  token: "some api token",
  responders: [
    {Hedwig.Responders.Help, []},
    {Hedwig.Responders.Ping, []}
  ]

Great! We're ready to start our bot. From the root of our application, let's run the following:

λ mix run --no-halt

This will start our application along with our bot.

Since we have the Help responder installed, we can say alfred help and we should see a list of usage for all of the installed responders.

Telegram Webhook

Messages are received from Telegram using an HTTP webhook. You can use the included Hedwig.Adapters.Telegram.Webhook module or define one yourself as long as it calls Hedwig.Adapters.Messenger.handle_in/2 to send the message to the robot.

Using the included server

To use the included webhook with your robot, update your dependencies by including plug and cowboy:

  defp deps do
    [
      {:cowboy, "~> 1.0"},
      {:plug, "~> 1.1"}
    ]
  end

add Hedwig.Adapters.Telegram.Webhook to your supervision tree alongside your robot

    children = [
      worker(Alfred.Robot, []),
      worker(Hedwig.Adapters.Telegram.Webhook, [])
    ]

The parameters are:

• cowboy_options - a keyword list of options to pass to cowboy (optional)

Finally, you have to register your webhook with telegram. It's possibile in this way:

 curl -d '{"url":"https://<botaddress>/get/<robotname>"}' -H "Content-Type: application/json" -X POST https://api.telegram.org/bot<YourToken>/setWebhook

Defining your own webhook

If you are defining your own webhook (for instance in a phoenix app), just make sure to call Hedwig.Adapters.Telegram.handle_in/2

    def my_messenger_callback(conn, params) do
        case Hedwig.Adapters.Telegram.handle_in(robot_name, params) do
            {:error, reason} ->
                # Handle robot not found
            :ok ->
                # Message sent to robot.
       end
    end

What's next?

Well, that's it for now. Make sure to read the Hedwig Documentation for more details on writing responders and other exciting things!

LICENSE

Hedwig Telegram source code is licensed under the MIT License.