TamTam Bot API Java Client

This is Java client for TamTam Bot API. It gives you full access to API in your Java code.

Library has been built based on TamTam Bot API Schema that is OpenAPI-compliant.

Full documentation of API can be found here.

⚠️ This library provides just a thin client to invoke API methods. Take a look at tamtam-bot-sdk framework to build bots.

Requirements

Minimum required version of Java is 8.

To use TamTam Bot API you should obtain ACCESS_TOKEN for each bot you create.

Talk to @PrimeBot. It will helps you to create your first bot.

Dependencies

Usage

To start using this client add it as Maven dependency:

<dependency>
    <groupId>chat.tamtam</groupId>
    <artifactId>tamtam-bot-api</artifactId>
    <version>0.5.0</version>
</dependency>

Initialization

The easiest way to create it is to call:

TamTamBotAPI api = TamTamBotAPI.create("%ACCESS_TOKEN%);

It will create client with default Jackson-based serializer and OkHttp-based HTTP client. If you want to use your own implementation you can implement TamTamTransportClient and TamTamSerializer and initialize TamTamClient with it:

TamTamTransportClient transportClient = …;
TamTamSerializer serializer = …;
TamTamClient client = new TamTamClient("%ACCESS_TOKEN%", transportClient, serializer);
TamTamBotAPI botAPI = new TamTamBotAPI(client);

Making requests

TamTamBotAPI provides access to all methods supported by the API. All methods return TamTamQuery object that can be executed synchronous or asynchronous.

For example:

String fileToken = …;
Long userId = …;

AttachmentRequest fileAttachment = new FileAttachmentRequest(new UploadedInfo(fileToken));
List<AttachmentRequest> attachments = Collections.singletonList(fileAttachment);
NewMessageBody body = new NewMessageBody("hello world!", attachments, null);
SendMessageQuery sendMessageQuery = botAPI.sendMessage(body).userId(userId);

// Sync
SendMessageResult result = sendMessageQuery.execute();

// Async
Future<SendMessageResult> futureResult = sendMessageQuery.enqueue();

Uploading media

Your bot is able to attach some media content to messages. It could be image, video, audio or file.

To attach media to message you should follow two steps:

Obtain URL to upload:

UploadEndpoint endpoint = botAPI.getUploadUrl(UploadType.VIDEO).execute();
String uploadUrl = endpoint.getUrl();

Upload binary data to this url. You can manually execute HTTP-request to send binary data to this url, or use built-in TamTamUploadAPI:

TamTamUploadAPI uploadAPI = new TamTamUploadAPI(client);
UploadedInfo uploadedInfo = uploadAPI.uploadFile(uploadUrl, new File("%FILE_PATH%")).execute();

Important notice

It may take a time for server to process you file (audio/video or binary file). While file is not processed you can't attach it and will get AttachmentNotReadyException when calling sendMessage method. Try again until you'll get successful result.

Handling exceptions

All methods can throw two type of exceptions:

ClientException: general exception type wrapping all kinds of IO/serialization exceptions.
APIException: exception you will get if API was used incorrectly. For example, some arguments are missing or access to requested resource is denied.

Logging

No logging is performed by default. This project uses SLF4J, so you should bring adapter for logging framework you prefer. For example, add slf4j-log4j12 as dependency:

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-log4j12</artifactId>
    <version>1.7.25</version>
</dependency>

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

This project is licensed under the Apache 2.0.

tamtam-chat/tamtam-bot-api