nadam/tg-bot-api

Java library for Telegram's Bot API

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.nadam:tg-bot-api:v2.0.0'
	}
	dependencies {
		implementation("com.github.nadam:tg-bot-api:v2.0.0")
	}
	<dependency>
	    <groupId>com.github.nadam</groupId>
	    <artifactId>tg-bot-api</artifactId>
	    <version>v2.0.0</version>
	</dependency>

                            
    libraryDependencies += "com.github.nadam" % "tg-bot-api" % "v2.0.0"
        
        

                            
    :dependencies [[com.github.nadam/tg-bot-api "v2.0.0"]]

Readme

TgBotApi

This Java library implements all the methods and types in Telegram's Bot API including the new features in 4.1. Telegram is an instant messenger for various platforms.

If you find a bug or know some way to improve the library please report it to me as an issue or in private. Just don't ask me to add boiler plate stuff like getters and setters. There are lots of other Java libraries if you prefer that.

Technical scope and limitations

  • Uses GET methods with URL query string where possible (all methods except when sending files as multipart/form-data)
  • Supports getUpdates(), but I've only tested it with webhook so far
  • Making requests when getting updates is not supported

Features

  • Full implementation of the API and hopefully quickly updated when new features are released
  • Javadoc links to corresponding official documentation
  • All types implemented as simple POJO classes with constructors and helper methods where necessary
  • All methods implemented as Java methods with various parameter options
  • A setSilent() method for bots who want to use disable_notification instead of having to set it each time you send a message
  • Helper methods to make life easier, for instance TgBotApi.sendReply(), TgBotApi.downloadFile() and TgBotApi.debug()
  • Enums and constants for common values

Including in your project

Gradle

repositories {
    maven { url 'https://jitpack.io' }
}


dependencies {
    implementation 'com.github.nadam:tg-bot-api:2.0.0'
}

Dependencies

The project depends on GSON 2.8.2. I have currently only used it together with Google App Engine (which includes GSON), but it should be possible to use it with any platform.

Binary

Latest binaries available in the Releases section.

Building from source code

A pom.xml for Maven is included in the project. For other options just make sure you include GSON 2.8.2 or later.

Using the library

Telegram Bot API

If you are new to bots or bot development for Telegram check out the following links:

Preparation

  1. Setup your bot using @BotFather as described in the links above to get your bot username and token
  2. Use @userinfobot or similar to get your user id

Sample code for Google App Engine using webhooks

  1. For Google App Engine or similar, extend HttpServlet and implement the doPost() method.
  2. Optionally implement the ErrorListener interface.
  3. Create the TgBotApi object using your token and user id (it's good practice to put these values as constants in a separate file).
  4. Parse the requests using TgBotApi.parseFromWebhook() to get the Update object
  5. Optionally send a reply using TgBotApi.sendMessage() or TgBotApi.sendReply()
public class ExampleServlet extends HttpServlet implements ErrorListener {

    private TgBotApi api;

    public ExampleServlet() {
        super();
        api = new TgBotApi(TOKEN, OWNER, this);
    }

    @Override
    public void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {

        resp.setStatus(200);

        String messageText;
        long chatId = 0;

        try {
            Update update = api.parseFromWebhook(req.getReader());            
            
            // Do something interesting,
            // extract the chatId from the update object and
            // decide an appropriate messageText to send as reply.
            
        } catch (Exception e) {
            api.debug(e);
            return;
        }

        api.sendMessage(chatId, messageText);
    }

    @Override
    public void onError(int errorCode, String description) {
        api.debug(new Exception("ErrorCode " + errorCode + ", " + description));
    }
}

The code for other platforms will look quite similar.

More information

Bots using TgBotApi

Advanced Java for Telegram

If you think the Bot API is too limiting you can use the Telegram API instead which is what ordinary Telegram clients use. You use it with an ordinary Telegram account or with a Bot account (using auth.importBotAuthorization).

Other stuff

License

Apache License 2.0