https://github.com/tamtam-chat/tamtam-bot-api
Java Client for TamTam Bot API
https://github.com/tamtam-chat/tamtam-bot-api
api bots client java tamtam
Last synced: 5 months ago
JSON representation
Java Client for TamTam Bot API
- Host: GitHub
- URL: https://github.com/tamtam-chat/tamtam-bot-api
- Owner: tamtam-chat
- License: apache-2.0
- Created: 2019-01-09T13:16:57.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-02-10T15:56:28.000Z (over 3 years ago)
- Last Synced: 2025-07-22T16:43:00.714Z (11 months ago)
- Topics: api, bots, client, java, tamtam
- Language: Java
- Homepage: https://dev.tamtam.chat
- Size: 32.5 MB
- Stars: 22
- Watchers: 6
- Forks: 9
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://maven-badges.herokuapp.com/maven-central/chat.tamtam/tamtam-bot-api) 
[](https://coveralls.io/github/tamtam-chat/tamtam-bot-api?branch=master) [](http://www.javadoc.io/doc/chat.tamtam/tamtam-bot-api)
# 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](https://github.com/tamtam-chat/tamtam-bot-api-schema) that is OpenAPI-compliant.
Full documentation of API can be found [here](https://dev.tamtam.chat).
⚠️ This library provides just a thin client to invoke API methods. Take a look at [tamtam-bot-sdk](https://github.com/tamtam-chat/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](http://tt.me/primebot). It will helps you to create your first bot.
## Dependencies
- [Jackson 2.9.8](https://github.com/FasterXML/jackson)
- [OkHttp 3.12.0](https://github.com/square/okhttp)
- [SLF4J](https://github.com/qos-ch/slf4j)
## Usage
To start using this client add it as Maven dependency:
```xml
chat.tamtam
tamtam-bot-api
0.5.0
```
### Initialization
The easiest way to create it is to call:
```java
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:
```java
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:
```java
String fileToken = …;
Long userId = …;
AttachmentRequest fileAttachment = new FileAttachmentRequest(new UploadedInfo(fileToken));
List 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 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:
1. Obtain URL to upload:
```java
UploadEndpoint endpoint = botAPI.getUploadUrl(UploadType.VIDEO).execute();
String uploadUrl = endpoint.getUrl();
```
2. Upload binary data to this url. You can manually execute HTTP-request to send binary data to this url, or use built-in `TamTamUploadAPI`:
```java
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:
1. ClientException: general exception type wrapping all kinds of IO/serialization exceptions.
2. 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:
```xml
org.slf4j
slf4j-log4j12
1.7.25
```
## 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](https://www.apache.org/licenses/LICENSE-2.0).