Bot API allows bots to interact with TamTam. Methods are called by sending HTTPS requests to botapi.tamtam.chat domain. Bots are third-party applications that use TamTam features. A bot can legitimately take part in a conversation. It can be achieved through HTTP requests to the TamTam Bot API.
TamTam bots of the current version are able to:
- Communicate with users and respond to requests
- Recommend users complete actions via programmed buttons
- Request personal data from users (name, short reference, phone number) We'll keep working on expanding bot capabilities in the future.
Bots can be used for the following purposes:
- Providing support, answering frequently asked questions
- Sending typical information
- Voting
- Likes/dislikes
- Following external links
- Forwarding a user to a chat/channel
PrimeBot is the main bot in TamTam, all bots creator. Use PrimeBot to create and edit your bots. Feel free to contact us for any questions, @support or team@tamtam.chat.
GET
— getting resources, parameters are transmitted via URL
POST
— creation of resources (for example, sending new messages)
PUT
— editing resources
DELETE
— deleting resources
PATCH
— patching resources
200
— successful operation
400
— invalid request
401
— authentication error
404
— resource not found
405
— method is not allowed
429
— the number of requests is exceeded
503
— service unavailable
For content requests (PUT and POST) and responses, the API uses the JSON format. All strings are UTF-8 encoded. Date/time fields are represented as the number of milliseconds that have elapsed since 00:00 January 1, 1970 in the long format. To get it, you can simply multiply the UNIX timestamp by 1000. All date/time fields have a UTC timezone.
In case of an error, the API returns a response with the corresponding HTTP code and JSON with the following fields:
code
- the string with the error key
message
- a string describing the error
For example:
> http https://botapi.tamtam.chat/chats?access_token={EXAMPLE_TOKEN}
HTTP / 1.1 403 Forbidden
Cache-Control: no-cache
Connection: Keep-Alive
Content-Length: 57
Content-Type: application / json; charset = utf-8
Set-Cookie: web_ui_lang = ru; Path = /; Domain = .tamtam.chat; Expires = 2019-03-24T11: 45: 36.500Z
{
"code": "verify.token",
"message": "Invalid access_token"
}
TamTam Bot API supports 2 options of receiving notifications on new events for bots:
- Push notifications via WebHook. To receive data via WebHook, you'll have to add subscription;
- Notifications upon request via long polling API. All data can be received via long polling by default after creating the bot.
Both methods cannot be used simultaneously. Refer to the response schema of /updates method to check all available types of updates.
Webhook
There is some notes about how we handle webhook subscription:
Sometimes webhook notification cannot be delivered in case when bot server or network is down.
In such case we will retry delivery in a short period of time (from 30 to 60 seconds) and will do this until get
200 OK
status code from your server, but not longer than 8 hours (may change over time) since update happened. Subscription can be cancelled if bot doesn't response to webhook notification.We also consider any non
200
response from server as failed delivery.To protect your bot from unexpected high load we send no more than 100 notifications per second by default. If you want increase this limit, contact us at @support.
It should be from one of the following subnets:
185.16.150.0/30
185.16.150.84/30
185.16.150.152/30
185.16.150.192/30
TamTam supports deep linking mechanism for bots. It allows passing additional payload to the bot on startup. Deep link can contain any data encoded into string up to 128 characters long. Longer strings will be omitted and not passed to the bot.
Each bot has start link that looks like:
https://tt.me/%BOT_USERNAME%/start/%PAYLOAD%
As soon as user clicks on such link we open dialog with bot and send this payload to bot as part of bot_started
update:
{
"update_type": "bot_started",
"timestamp": 1573226679188,
"chat_id": 1234567890,
"user": {
"user_id": 1234567890,
"name": "Boris",
"username": "borisd84"
},
"payload": "any data meaningful to bot"
}
Deep linking mechanism is supported for iOS version 2.7.0 and Android 2.9.0 and higher.
Constructor is a bot that can create a message for user: add buttons, attach some media, insert text.
You can enable constructor mode for your bot via @PrimeBot sending /constructor_mode command.
For bot developers, it looks like request-response interaction where TamTam application sends message_construction_request
on behalf of user. Bot responds to it with messages
ready to go or keyboard
in case it requires further action from user.
Bot also can set up UI parts such as hint
or placeholder
, allow or not user's input:
As soon as user finishes composing a message, they can post it. Bot will receive message_constructed_update
with posted message.
Constructors are supported for iOS version 2.7.0 and Android 2.9.0 and higher.
Message text can be improved with basic formatting such as: strong, emphasis, strikethough, underline, code
or link. You can use either markdown-like or HTML formatting.
To enable text formatting set the format
property of NewMessageBody.
TamTam flavored Markdown
To enable Markdown parsing, set the format
property of NewMessageBody to markdown
.
We currently support only the following syntax:
*empasized*
or _empasized_
for italic text
**strong**
or __strong__
for bold text
~~strikethough~~
for strikethough text
++underline++
for underlined text
`code`
for inline monospaced
text (line endings inside this block are treated like spaces)
```code```
for monospaced
text block
^^important^^
for highlighted text (colored in red, by default)
[Inline URL](https://dev.tamtam.chat/)
for inline URLs
[User mention](tamtam://user/%user_id%)
for user mentions without username
# Header
for header
HTML support
To enable HTML parsing, set the format
property of NewMessageBody to html
.
Only the following HTML tags are supported. All others will be stripped:
Emphasized: <i>
or <em>
Strong: <b>
or <strong>
Strikethrough: <del>
or <s>
Underlined: <ins>
or <u>
Link: <a href="https://dev.tamtam.chat">Docs</a>
Monospaced text: <pre>
or <code>
Highlighted text: <mark>
Header: <h1>
Text formatting is supported for iOS since version 3.1 and Android since 2.20.0.
API models and interface may change over time. To make sure your bot will get the right info, we strongly recommend adding API version number to each request. You can add it as v
parameter to each HTTP-request. For instance, v=0.1.2
. To specify the data model version you are getting through WebHook subscription, use the version
property in the request body of the subscribe request.
We have developed the official Java client and SDK.
Also check out unofficial libraries, created by our enthusiasts:
Python:
Version 0.3.0
Check out the complete diff for this release.
Version 0.2.1
- Added method to get chat by its
@link
- Added
description
for users in some cases - Added
user_locale
tomessage_created
update in dialogs
Check out the complete diff for this release.
Version 0.2.0
- Added new type of button to start new chat
- Added Constructors API that allows bots to create message on behalf of a user
- Added support for deep-links
- Added ability to block users in chats
- Added
chat_id
anduser_id
tomessage_removed
update - Added meta information for video attachments
- Other minor improvements and fixes. Check out complete diff for this version
Version 0.1.10
- Added
disable_link_preview
parameter to POST:/messages method to disable links parsing in text - Added
sending_file
action - Removed several deprecated properties
photo
upload type renamed toimage
. C is for consistency
To see changelog for older versions visit our GitHub.
access_token
A token is given to you by PrimeBot after you have created a bot. In all subsequent requests to the Bot API, you must pass the received token as an access_token
parameter to the HTTP request.
If Terms and Conditions of TamTam usage have been violated, the TamTam administration may withdraw tokens by aborting user sessions. If your token has been compromised, you can request a new one by sending a /revoke
command to PrimeBot.
Security Scheme Type | API Key |
---|---|
Query parameter name: | access_token |
Get current bot info
Returns info about current bot. Current bot can be identified by access token. Method returns bot identifier, name and avatar (if any)
Authorizations:
Response: application/json
user_id | integer <int64> Users identifier |
name | string Users visible name |
username | string Nullable Unique public user name. Can be |
is_bot | boolean
|
last_activity_time | integer <int64> Time of last user activity in TamTam (Unix timestamp in milliseconds). Can be outdated if user disabled its "online" status in settings |
description optional | string <= 16000 characters Nullable User description. Can be |
avatar_url optional | string URL of avatar |
full_avatar_url optional | string URL of avatar of a bigger size |
commands optional | Array of objects (BotCommand) <= 32 items Nullable Commands supported by bot |
Edit current bot info
Edits current bot info. Fill only the fields you want to update. All remaining fields will stay untouched
Authorizations:
Request Body schema: application/json
name optional | string [ 1 .. 64 ] characters Nullable Visible name of bot |
description optional | string [ 1 .. 16000 ] characters Nullable Bot description up to 16k characters long |
commands optional | Array of objects (BotCommand) <= 32 items Nullable Commands supported by bot. Pass empty list if you want to remove commands |
photo optional | object Nullable Request to set bot photo |
Response: application/json
user_id | integer <int64> Users identifier |
name | string Users visible name |
username | string Nullable Unique public user name. Can be |
is_bot | boolean
|
last_activity_time | integer <int64> Time of last user activity in TamTam (Unix timestamp in milliseconds). Can be outdated if user disabled its "online" status in settings |
description optional | string <= 16000 characters Nullable User description. Can be |
avatar_url optional | string URL of avatar |
full_avatar_url optional | string URL of avatar of a bigger size |
commands optional | Array of objects (BotCommand) <= 32 items Nullable Commands supported by bot |
Get all chats
Returns information about chats that bot participated in: a result list and marker points to the next page
Authorizations:
query Parameters
count optional | integer <int32> [ 1 .. 100 ] Default: 50 Number of chats requested |
marker optional | integer <int64> (bigint) Points to next data page. |
Response: application/json
chats | Array of objects (Chat) List of requested chats |
marker | integer <int64> Nullable Reference to the next page of requested chats |
Get chat by link
Returns chat/channel information by its public link or dialog with user by username
Authorizations:
path Parameters
chatLink | string @?[a-zA-Z]+[a-zA-Z0-9-_]* Public chat link or username |
Response: application/json
chat_id | integer <int64> Chats identifier |
type | any Enum: "dialog" "chat" "channel" Type of chat. One of: dialog, chat, channel |
status | any Enum: "active" "removed" "left" "closed" "suspended" Chat status. One of:
|
title | string Nullable Visible title of chat. Can be null for dialogs |
icon | object Nullable Icon of chat |
last_event_time | integer <int64> Time of last event occurred in chat |
participants_count | integer <int32> Number of people in chat. Always 2 for |
owner_id optional | integer <int64> Nullable Identifier of chat owner. Visible only for chat admins |
participants optional | object Nullable Participants in chat with time of last activity. Can be null when you request list of chats. Visible for chat admins only |
is_public | boolean Is current chat publicly available. Always |
link optional | string Nullable Link on chat |
description | string Nullable Chat description |
dialog_with_user optional | object Nullable Another user in conversation. For |
messages_count optional | integer Nullable Messages count in chat. Only for group chats and channels. Not available for dialogs |
chat_message_id optional | string Nullable Identifier of message that contains |
pinned_message optional | object Nullable Pinned message in chat or channel. Returned only when single chat is requested |
Get chat
Returns info about chat.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Requested chat identifier |
Response: application/json
chat_id | integer <int64> Chats identifier |
type | any Enum: "dialog" "chat" "channel" Type of chat. One of: dialog, chat, channel |
status | any Enum: "active" "removed" "left" "closed" "suspended" Chat status. One of:
|
title | string Nullable Visible title of chat. Can be null for dialogs |
icon | object Nullable Icon of chat |
last_event_time | integer <int64> Time of last event occurred in chat |
participants_count | integer <int32> Number of people in chat. Always 2 for |
owner_id optional | integer <int64> Nullable Identifier of chat owner. Visible only for chat admins |
participants optional | object Nullable Participants in chat with time of last activity. Can be null when you request list of chats. Visible for chat admins only |
is_public | boolean Is current chat publicly available. Always |
link optional | string Nullable Link on chat |
description | string Nullable Chat description |
dialog_with_user optional | object Nullable Another user in conversation. For |
messages_count optional | integer Nullable Messages count in chat. Only for group chats and channels. Not available for dialogs |
chat_message_id optional | string Nullable Identifier of message that contains |
pinned_message optional | object Nullable Pinned message in chat or channel. Returned only when single chat is requested |
Edit chat info
Edits chat info: title, icon, etc…
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
Request Body schema: application/json
icon optional | object Nullable Request to attach image. All fields are mutually exclusive |
title optional | string [ 1 .. 200 ] characters Nullable |
pin optional | string Nullable Identifier of message to be pinned in chat. In case you want to remove pin, use unpin method |
notify optional | boolean Nullable Default: true By default, participants will be notified about change with system message in chat/channel |
Response: application/json
chat_id | integer <int64> Chats identifier |
type | any Enum: "dialog" "chat" "channel" Type of chat. One of: dialog, chat, channel |
status | any Enum: "active" "removed" "left" "closed" "suspended" Chat status. One of:
|
title | string Nullable Visible title of chat. Can be null for dialogs |
icon | object Nullable Icon of chat |
last_event_time | integer <int64> Time of last event occurred in chat |
participants_count | integer <int32> Number of people in chat. Always 2 for |
owner_id optional | integer <int64> Nullable Identifier of chat owner. Visible only for chat admins |
participants optional | object Nullable Participants in chat with time of last activity. Can be null when you request list of chats. Visible for chat admins only |
is_public | boolean Is current chat publicly available. Always |
link optional | string Nullable Link on chat |
description | string Nullable Chat description |
dialog_with_user optional | object Nullable Another user in conversation. For |
messages_count optional | integer Nullable Messages count in chat. Only for group chats and channels. Not available for dialogs |
chat_message_id optional | string Nullable Identifier of message that contains |
pinned_message optional | object Nullable Pinned message in chat or channel. Returned only when single chat is requested |
Send action
Send bot action to chat.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
Request Body schema: application/json
action | any (SenderAction) Enum: "typing_on" "sending_photo" "sending_video" "sending_audio" "sending_file" "mark_seen" Different actions to send to chat members |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Get pinned message
Get pinned message in chat or channel.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier to get its pinned message |
Response: application/json
message optional | object Nullable Pinned message. Can be |
Pin message
Pins message in chat or channel.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier where message should be pinned |
Request Body schema: application/json
message_id | string Identifier of message to be pinned in chat |
notify optional | boolean Nullable Default: true If |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Unpin message
Unpins message in chat or channel.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier to remove pinned message |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Get chat membership
Returns chat membership info for current bot
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
Response: application/json
user_id | integer <int64> Users identifier |
name | string Users visible name |
username | string Nullable Unique public user name. Can be |
is_bot | boolean
|
last_activity_time | integer <int64> Time of last user activity in TamTam (Unix timestamp in milliseconds). Can be outdated if user disabled its "online" status in settings |
description optional | string <= 16000 characters Nullable User description. Can be |
avatar_url optional | string URL of avatar |
full_avatar_url optional | string URL of avatar of a bigger size |
last_access_time | integer <int64> User last activity time in chat. Can be outdated for super chats and channels (equals to |
is_owner | boolean |
is_admin | boolean |
join_time | integer <int64> |
permissions | Array of strings Nullable Items Enum: "read_all_messages" "add_remove_members" "add_admins" "change_chat_info" "pin_message" "write" Permissions in chat if member is admin. |
Leave chat
Removes bot from chat members.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Get chat admins
Returns all chat administrators. Bot must be administrator in requested chat.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
Response: application/json
members | Array of objects (ChatMember) Participants in chat with time of last activity. Visible only for chat admins |
marker optional | integer <int64> Nullable Pointer to the next data page |
Get members
Returns users participated in chat.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
query Parameters
user_ids optional | Array of integers <int64> Nullable Since version 0.1.4. Comma-separated list of users identifiers to get their membership. When this parameter is passed, both |
marker optional | integer <int64> Marker |
count optional | integer [ 1 .. 100 ] Default: 20 Count |
Response: application/json
members | Array of objects (ChatMember) Participants in chat with time of last activity. Visible only for chat admins |
marker optional | integer <int64> Nullable Pointer to the next data page |
Add members
Adds members to chat. Additional permissions may require.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
Request Body schema: application/json
user_ids | Array of integers <int64> |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Remove member
Removes member from chat. Additional permissions may require.
Authorizations:
path Parameters
chatId | integer <int64> \-?\d+ Chat identifier |
query Parameters
user_id | integer <int64> User id to remove from chat |
block optional | boolean Default: false Set to |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Get messages
Returns messages in chat: result page and marker referencing to the next page. Messages traversed in reverse direction so the latest message in chat will be first in result array. Therefore if you use from
and to
parameters, to
must be less than from
Authorizations:
query Parameters
chat_id optional | integer <int64> (bigint) Chat identifier to get messages in chat |
message_ids optional | Array of strings Nullable Comma-separated list of message ids to get |
from optional | integer <int64> (bigint) Start time for requested messages |
to optional | integer <int64> (bigint) End time for requested messages |
count optional | integer <int32> [ 1 .. 100 ] Default: 50 Maximum amount of messages in response |
Response: application/json
messages | Array of objects (Message) List of messages |
Send message
Sends a message to a chat. As a result for this method new message identifier returns.
Attaching media
Attaching media to messages is a three-step process.
At first step, you should obtain a URL to upload your media files.
At the second, you should upload binary of appropriate format to URL you obtained at the previous step. See upload section for details.
Finally, if the upload process was successful, you will receive JSON-object in a response body. Use this object to create attachment. Construct an object with two properties:
type
with the value set to appropriate media type- and
payload
filled with the JSON you've got.
For example, you can attach a video to message this way:
Get URL to upload. Execute following:
curl -X POST 'https://botapi.tamtam.chat/uploads?access_token=%access_token%&type=video'
As the result it will return URL for the next step.
{ "url": "https://vu.mycdn.me/upload.do…" }
Use this url to upload your binary:
curl -i -X POST -H "Content-Type: multipart/form-data" -F "data=@movie.mp4" "https://vu.mycdn.me/upload.do…"
As the result it will return JSON you can attach to message:
{ "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4" }
Send message with attach:
{ "text": "Message with video", "attachments": [ { "type": "video", "payload": { "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4" } } ] }
Important notice:
It may take time for the server to process your file (audio/video or any binary). While a file is not processed you can't attach it. It means the last step will fail with 400
error. Try to send a message again until you'll get a successful result.
Authorizations:
query Parameters
user_id optional | integer <int64> Fill this parameter if you want to send message to user |
chat_id optional | integer <int64> Fill this if you send message to chat |
disable_link_preview optional | boolean Default: false If |
Request Body schema: application/json
text | string <= 4000 characters Nullable Message text |
attachments | Array of objects (AttachmentRequest) Nullable Message attachments. See |
link | object Nullable Link to Message |
notify optional | boolean Default: true If false, chat participants would not be notified |
format optional | string Nullable Enum: "markdown" "html" If set, message text will be formatted according to given markup |
Response: application/json
message | object (Message) Message in chat |
Edit message
Updated message should be sent as NewMessageBody
in a request body. In case attachments
field is null
, the current message attachments won’t be changed. In case of sending an empty list in this field, all attachments will be deleted.
Authorizations:
query Parameters
message_id | string non-empty Editing message identifier |
Request Body schema: application/json
text | string <= 4000 characters Nullable Message text |
attachments | Array of objects (AttachmentRequest) Nullable Message attachments. See |
link | object Nullable Link to Message |
notify optional | boolean Default: true If false, chat participants would not be notified |
format optional | string Nullable Enum: "markdown" "html" If set, message text will be formatted according to given markup |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Delete message
Deletes message in a dialog or in a chat if bot has permission to delete messages.
Authorizations:
query Parameters
message_id | string non-empty Deleting message identifier |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Get message
Returns single message by its identifier.
Authorizations:
path Parameters
messageId | string [a-zA-Z0-9_\-]+ Message identifier ( |
Response: application/json
sender optional | object User who sent this message. Can be |
recipient | object Message recipient. Could be user or chat |
timestamp | integer <int64> Unix-time when message was created |
link optional | object Nullable Forwarded or replied message |
body | object Body of created message. Text + attachments. Could be null if message contains only forwarded message |
stat optional | object Nullable Message statistics. Available only for channels in GET:/messages context |
url optional | string Nullable Message public URL. Can be |
constructor optional | object Nullable Default: Bot-constructor created this message |
Answer on callback
This method should be called to send an answer after a user has clicked the button. The answer may be an updated message or/and a one-time user notification.
Authorizations:
query Parameters
callback_id | string non-empty ^(?!\s*$).+ Identifies a button clicked by user. Bot receives this identifier after user pressed button as part of |
Request Body schema: application/json
message optional | object Nullable Fill this if you want to modify current message |
notification optional | string Nullable Fill this if you just want to send one-time notification to user |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Construct message
Sends answer on construction request. Answer can contain any prepared message and/or keyboard to help user interact with bot.
Authorizations:
query Parameters
session_id | string Constructor session identifier |
Request Body schema: application/json
messages optional | Array of objects (ConstructedMessageBody) Array of prepared messages. This messages will be sent as user taps on "Send" button |
allow_user_input optional | boolean If |
hint optional | string Nullable Hint to user. Will be shown on top of keyboard |
data optional | string <= 8192 characters In this property you can store any additional data up to 8KB. We send this data back to bot within the next construction request. It is handy to store here any state of construction session |
keyboard optional | object Nullable Keyboard to show to user in constructor mode |
placeholder optional | string Nullable Text to show over the text field |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Subscribe
Subscribes bot to receive updates via WebHook. After calling this method, the bot will receive notifications about new events in chat rooms at the specified URL.
Your server must be listening on one of the following ports: 80, 8080, 443, 8443, 16384-32383
Authorizations:
Request Body schema: application/json
url | string URL of HTTP(S)-endpoint of your bot. Must starts with http(s):// |
update_types optional | Array of strings List of update types your bot want to receive. See |
version optional | string Version of API. Affects model representation |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Unsubscribe
Unsubscribes bot from receiving updates via WebHook. After calling the method, the bot stops receiving notifications about new events. Notification via the long-poll API becomes available for the bot
Authorizations:
query Parameters
url | string URL to remove from WebHook subscriptions |
Response: application/json
success | boolean
|
message optional | string Explanatory message if the result is not successful |
Get updates
You can use this method for getting updates in case your bot is not subscribed to WebHook. The method is based on long polling.
Every update has its own sequence number. marker
property in response points to the next upcoming update.
All previous updates are considered as committed after passing marker
parameter. If marker
parameter is not passed, your bot will get all updates happened after the last commitment.
Authorizations:
query Parameters
limit optional | integer [ 1 .. 1000 ] Default: 100 Maximum number of updates to be retrieved |
timeout optional | integer [ 0 .. 90 ] Default: 30 Timeout in seconds for long polling |
marker optional | integer <int64> Nullable Pass |
types optional | Array of strings Nullable Example: Comma separated list of update types your bot want to receive |
Response: application/json
updates | Array of objects (Update) Page of updates |
marker | integer <int64> Nullable Pointer to the next data page |
Get upload URL
Returns the URL for the subsequent file upload.
For example, you can upload it via curl:
curl -i -X POST -H "Content-Type: multipart/form-data" -F "data=@movie.mp4" "%UPLOAD_URL%"
Two types of an upload are supported:
- single request upload (multipart request)
- and resumable upload.
Multipart upload
This type of upload is a simpler one but it is less reliable and agile. If a Content-Type
: multipart/form-data header is passed in a request our service indicates upload type as a simple single request upload.
This type of an upload has some restrictions:
- Max. file size - 2 Gb
- Only one file per request can be uploaded
- No possibility to restart stopped / failed upload
Resumable upload
If Content-Type
header value is not equal to multipart/form-data
our service indicated upload type as a resumable upload. With a Content-Range
header current file chunk range and complete file size can be passed. If a network error has happened or upload was stopped you can continue to upload a file from the last successfully uploaded file chunk. You can request the last known byte of uploaded file from server and continue to upload a file.
Get upload status
To GET an upload status you simply need to perform HTTP-GET request to a file upload URL. Our service will respond with current upload status, complete file size and last known uploaded byte. This data can be used to complete stopped upload if something went wrong. If REQUESTED_RANGE_NOT_SATISFIABLE
or INTERNAL_SERVER_ERROR
status was returned it is a good point to try to restart an upload
Authorizations:
query Parameters
type | any (UploadType) Enum: "image" "video" "audio" "file" Uploaded file type: photo, audio, video, file |
Response: application/json
url | string URL to upload |
user_id | integer <int64> Users identifier |
name | string Users visible name |
username | string Nullable Unique public user name. Can be |
is_bot | boolean
|
last_activity_time | integer <int64> Time of last user activity in TamTam (Unix timestamp in milliseconds). Can be outdated if user disabled its "online" status in settings |
{- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}
chat_id | integer <int64> Chats identifier |
type | any Enum: "dialog" "chat" "channel" Type of chat. One of: dialog, chat, channel |
status | any Enum: "active" "removed" "left" "closed" "suspended" Chat status. One of:
|
title | string Nullable Visible title of chat. Can be null for dialogs |
icon | object Nullable Icon of chat |
last_event_time | integer <int64> Time of last event occurred in chat |
participants_count | integer <int32> Number of people in chat. Always 2 for |
owner_id optional | integer <int64> Nullable Identifier of chat owner. Visible only for chat admins |
participants optional | object Nullable Participants in chat with time of last activity. Can be null when you request list of chats. Visible for chat admins only |
is_public | boolean Is current chat publicly available. Always |
link optional | string Nullable Link on chat |
description | string Nullable Chat description |
dialog_with_user optional | object Nullable Another user in conversation. For |
messages_count optional | integer Nullable Messages count in chat. Only for group chats and channels. Not available for dialogs |
chat_message_id optional | string Nullable Identifier of message that contains |
pinned_message optional | object Nullable Pinned message in chat or channel. Returned only when single chat is requested |
{- "chat_id": 0,
- "type": "dialog",
- "status": "active",
- "title": "string",
- "icon":{
- "url": "string"
}, - "last_event_time": 0,
- "participants_count": 0,
- "owner_id": 0,
- "participants":{
- "property1": 0,
- "property2": 0
}, - "is_public": true,
- "link": "string",
- "description": "string",
- "dialog_with_user":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0,
- "description": "string",
- "avatar_url": "string",
- "full_avatar_url": "string"
}, - "messages_count": 0,
- "chat_message_id": "string",
- "pinned_message":{
- "sender":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}, - "recipient":{
- "chat_id": 0,
- "chat_type": "dialog",
- "user_id": 0
}, - "timestamp": 0,
- "link":{
- "type": "forward",
- "sender":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}, - "chat_id": 0,
- "message":{
- "mid": "string",
- "seq": 0,
- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "markup":[
- {
- "type": "string",
- "from": 0,
- "length": 0
}
]
}
}, - "body":{
- "mid": "string",
- "seq": 0,
- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "markup":[
- {
- "type": "string",
- "from": 0,
- "length": 0
}
]
}, - "stat":{
- "views": 0
}, - "url": "string",
- "constructor":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}
}
}
sender optional | object User who sent this message. Can be |
recipient | object Message recipient. Could be user or chat |
timestamp | integer <int64> Unix-time when message was created |
link optional | object Nullable Forwarded or replied message |
body | object Body of created message. Text + attachments. Could be null if message contains only forwarded message |
stat optional | object Nullable Message statistics. Available only for channels in GET:/messages context |
url optional | string Nullable Message public URL. Can be |
constructor optional | object Nullable Default: Bot-constructor created this message |
{- "sender":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}, - "recipient":{
- "chat_id": 0,
- "chat_type": "dialog",
- "user_id": 0
}, - "timestamp": 0,
- "link":{
- "type": "forward",
- "sender":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}, - "chat_id": 0,
- "message":{
- "mid": "string",
- "seq": 0,
- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "markup":[
- {
- "type": "string",
- "from": 0,
- "length": 0
}
]
}
}, - "body":{
- "mid": "string",
- "seq": 0,
- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "markup":[
- {
- "type": "string",
- "from": 0,
- "length": 0
}
]
}, - "stat":{
- "views": 0
}, - "url": "string",
- "constructor":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}
}
text | string <= 4000 characters Nullable Message text |
attachments | Array of objects (AttachmentRequest) Nullable Message attachments. See |
link | object Nullable Link to Message |
notify optional | boolean Default: true If false, chat participants would not be notified |
format optional | string Nullable Enum: "markdown" "html" If set, message text will be formatted according to given markup |
{- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "link":{
- "type": "forward",
- "mid": "string"
}, - "notify": true,
- "format": "markdown"
}
update_type | string message_callback |
timestamp | integer <int64> Unix-time when event has occurred |
callback | object |
message | object Nullable Original message containing inline keyboard. Can be |
user_locale optional | string Nullable Current user locale in IETF BCP 47 format |
{- "update_type": "message_callback",
- "timestamp": 0,
- "callback":{
- "timestamp": 0,
- "callback_id": "string",
- "payload": "string",
- "user":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}
}, - "message":{
- "sender":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}, - "recipient":{
- "chat_id": 0,
- "chat_type": "dialog",
- "user_id": 0
}, - "timestamp": 0,
- "link":{
- "type": "forward",
- "sender":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}, - "chat_id": 0,
- "message":{
- "mid": "string",
- "seq": 0,
- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "markup":[
- {
- "type": "string",
- "from": 0,
- "length": 0
}
]
}
}, - "body":{
- "mid": "string",
- "seq": 0,
- "text": "string",
- "attachments":[
- {
- "type": "string"
}
], - "markup":[
- {
- "type": "string",
- "from": 0,
- "length": 0
}
]
}, - "stat":{
- "views": 0
}, - "url": "string",
- "constructor":{
- "user_id": 0,
- "name": "string",
- "username": "string",
- "is_bot": true,
- "last_activity_time": 0
}
}, - "user_locale": "string"
}