TamTam Bot API (0.3.0)

Download OpenAPI specification:Download

License: Apache 2.0

About

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.

Features

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.

Examples

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

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.

HTTP verbs

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

HTTP response codes

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

Resources format

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.

Error responses

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"
}

Receiving notifications

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:

  1. Sometimes webhook notification cannot be delivered in case when bot server or network is down.

    In such case we well 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.

    We also consider any non 200-response from server as failed delivery.

  2. 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

Message buttons

You can program buttons for users answering a bot. TamTam supports the following types of buttons:

callback — sends a notification with payload to a bot (via WebHook or long polling)

link — makes a user to follow a link

request_contact — requests the user permission to access contact information (phone number, short link, email)

request_geo_location — asks user to provide current geo location

chat — creates chat associated with message

To start create buttons send message with InlineKeyboardAttachment:

{
  "text": "It is message with inline keyboard",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "callback",
              "text": "Press me!",
              "payload": "button1 pressed"
            }
          ],
          [
            {
              "type": "chat",
              "text": "Discuss",
              "chat_title": "Message discussion"
            }
          ]
        ]
      }
    }
  ]
}

Chat button

Chat button is a button that starts chat assosiated with the current message. It will be private chat with a link, bot will be added as administrator by default.

Chat will be created as soon as the first user taps on button. Bot will receive message_chat_created update.

Bot can set title and description of new chat by setting chat_title and chat_description properties.

Whereas keyboard can contain several chat-buttons there is uuid property to distinct them between each other. In case you do not pass uuid we will generate it. If you edit message, pass uuid so we know that this button starts the same chat as before.

Chat button also can contain start_payload that will be sent to bot as part of message_chat_created update.

Deep linking

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.

Constructors

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: Constructor UI parts

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.

Versioning

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.

Libraries

We have developed the official Java client and SDK.

Also check out unofficial libraries, created by our enthusiasts:

Python:

Changelog

Version 0.3.0
  • Added methods to pin/unpin messages in chats/channels
  • Added is_bot flag to User model

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 to message_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 and user_id to message_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 to image. C is for consistency

To see changelog for older versions visit our GitHub.

Authentication

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 TypeAPI Key
Query parameter name:access_token

bots

Get current bot info

get /me
https://botapi.tamtam.chat/me

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

Users identifier

name
string

Users visible name

username
string Nullable

Unique public user name. Can be null if user is not accessible or it is not set

is_bot
boolean

true if user is bot

description
optional
string <= 16000 characters Nullable

User description. Can be null if user did not fill it out

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

patch /me
https://botapi.tamtam.chat/me

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

username
optional
string [ 4 .. 64 ] characters Nullable [a-zA-Z]+[a-zA-Z0-9-_]*

Bot unique identifier. It can be any string 4-64 characters long containing any digit, letter or special symbols: "-" or "_". It must starts with a letter

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

Users identifier

name
string

Users visible name

username
string Nullable

Unique public user name. Can be null if user is not accessible or it is not set

is_bot
boolean

true if user is bot

description
optional
string <= 16000 characters Nullable

User description. Can be null if user did not fill it out

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

chats

Get all chats

get /chats
https://botapi.tamtam.chat/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[ 1 .. 100 ]
Default: 50

Number of chats requested

marker
optional
integer(bigint)

Points to next data page. null for the first page

Response: application/json
chats
Array of objects (Chat)

List of requested chats

marker
integerNullable

Reference to the next page of requested chats

Get chat

get /chats/{chatId}
https://botapi.tamtam.chat/chats/{chatId}

Returns info about chat.

Authorizations:
path Parameters
chatId
integer\-?\d+

Requested chat identifier

Response: application/json
chat_id
integer

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:

  • active: bot is active member of chat
  • removed: bot was kicked
  • left: bot intentionally left chat
  • closed: chat was closed
  • suspended: bot was stopped by user. Only for dialogs
title
string Nullable

Visible title of chat. Can be null for dialogs

icon
object Nullable

Icon of chat

last_event_time
integer

Time of last event occurred in chat

participants_count
integer

Number of people in chat. Always 2 for dialog chat type

owner_id
optional
integerNullable

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 false for dialogs

link
optional
string Nullable

Link on chat if it is public

description
any Nullable

Chat description

dialog_with_user
optional
object Nullable

Another user in conversation. For dialog type chats only

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 chat button initialized chat

pinned_message
optional
object Nullable

Pinned message in chat or channel. Returned only when single chat is requested

Edit chat info

patch /chats/{chatId}
https://botapi.tamtam.chat/chats/{chatId}

Edits chat info: title, icon, etc…

Authorizations:
path Parameters
chatId
integer\-?\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

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:

  • active: bot is active member of chat
  • removed: bot was kicked
  • left: bot intentionally left chat
  • closed: chat was closed
  • suspended: bot was stopped by user. Only for dialogs
title
string Nullable

Visible title of chat. Can be null for dialogs

icon
object Nullable

Icon of chat

last_event_time
integer

Time of last event occurred in chat

participants_count
integer

Number of people in chat. Always 2 for dialog chat type

owner_id
optional
integerNullable

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 false for dialogs

link
optional
string Nullable

Link on chat if it is public

description
any Nullable

Chat description

dialog_with_user
optional
object Nullable

Another user in conversation. For dialog type chats only

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 chat button initialized chat

pinned_message
optional
object Nullable

Pinned message in chat or channel. Returned only when single chat is requested

Send action

post /chats/{chatId}/actions
https://botapi.tamtam.chat/chats/{chatId}/actions

Send bot action to chat

Authorizations:
path Parameters
chatId
integer\-?\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

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Get pinned message

get /chats/{chatId}/pin
https://botapi.tamtam.chat/chats/{chatId}/pin

Get pinned message in chat or channel.

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier to get its pinned message

Response: application/json
message
optional
object Nullable

Pinned message. Can be null if no message pinned in chat

Pin message

put /chats/{chatId}/pin
https://botapi.tamtam.chat/chats/{chatId}/pin

Pins message in chat or channel.

Authorizations:
path Parameters
chatId
integer\-?\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 true, participants will be notified with system message in chat/channel

Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Unpin message

delete /chats/{chatId}/pin
https://botapi.tamtam.chat/chats/{chatId}/pin

Unpins message in chat or channel.

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier to remove pinned message

Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Get chat membership

get /chats/{chatId}/members/me
https://botapi.tamtam.chat/chats/{chatId}/members/me

Returns chat membership info for current bot

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier

Response: application/json
user_id
integer

Users identifier

name
string

Users visible name

username
string Nullable

Unique public user name. Can be null if user is not accessible or it is not set

is_bot
boolean

true if user is bot

description
optional
string <= 16000 characters Nullable

User description. Can be null if user did not fill it out

avatar_url
optional
string

URL of avatar

full_avatar_url
optional
string

URL of avatar of a bigger size

last_access_time
integer
is_owner
boolean
is_admin
boolean
join_time
integer
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. null otherwise

Leave chat

delete /chats/{chatId}/members/me
https://botapi.tamtam.chat/chats/{chatId}/members/me

Removes bot from chat members.

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier

Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Get chat admins

get /chats/{chatId}/members/admins
https://botapi.tamtam.chat/chats/{chatId}/members/admins

Returns all chat administrators. Bot must be administrator in requested chat.

Authorizations:
path Parameters
chatId
integer\-?\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
integerNullable

Pointer to the next data page

Get members

get /chats/{chatId}/members
https://botapi.tamtam.chat/chats/{chatId}/members

Returns users participated in chat.

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier

query Parameters
user_ids
optional
Array of integersNullable

Since version 0.1.4.

Comma-separated list of users identifiers to get their membership. When this parameter is passed, both count and marker are ignored

marker
optional
integer

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
integerNullable

Pointer to the next data page

Add members

post /chats/{chatId}/members
https://botapi.tamtam.chat/chats/{chatId}/members

Adds members to chat. Additional permissions may require.

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier

Request Body schema: application/json
user_ids
Array of integers
Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Remove member

delete /chats/{chatId}/members
https://botapi.tamtam.chat/chats/{chatId}/members

Removes member from chat. Additional permissions may require.

Authorizations:
path Parameters
chatId
integer\-?\d+

Chat identifier

query Parameters
user_id
integer

User id to remove from chat

block
optional
boolean
Default: false

Set to true if user should be blocked in chat. Applicable only for chats that have public or private link. Ignored otherwise

Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

messages

Get messages

get /messages
https://botapi.tamtam.chat/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(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(bigint)

Start time for requested messages

to
optional
integer(bigint)

End time for requested messages

count
optional
integer[ 1 .. 100 ]
Default: 50

Maximum amount of messages in response

Response: application/json
messages
Array of objects (Message)

List of messages

Send message

post /messages
https://botapi.tamtam.chat/messages

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:

  1. 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": "http://vu.mycdn.me/upload.do…"
    }
  2. Use this url to upload your binary:

    curl -i -X POST
    -H "Content-Type: multipart/form-data"
    -F "data=@movie.mp4" "http://vu.mycdn.me/upload.do…"

    As the result it will return JSON you can attach to message:

    {
     "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
    }
  3. 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

Fill this parameter if you want to send message to user

chat_id
optional
integer

Fill this if you send message to chat

disable_link_preview
optional
boolean
Default: false

If false, server will not generate media preview for links in text

Request Body schema: application/json
text
string <= 4000 characters Nullable

Message text

attachments
Array of objects (AttachmentRequest) Nullable

Message attachments. See AttachmentRequest and it's inheritors for full information

link
object Nullable

Link to Message

notify
optional
boolean
Default: true

If false, chat participants would not be notified

Response: application/json
message
object (Message)

Message in chat

Edit message

put /messages
https://botapi.tamtam.chat/messages

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 AttachmentRequest and it's inheritors for full information

link
object Nullable

Link to Message

notify
optional
boolean
Default: true

If false, chat participants would not be notified

Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Delete message

delete /messages
https://botapi.tamtam.chat/messages

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

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Get message

get /messages/{messageId}
https://botapi.tamtam.chat/messages/{messageId}

Returns single message by its identifier.

Authorizations:
path Parameters
messageId
string [a-zA-Z0-9_\-]+

Message identifier (mid) to get single message in chat

Response: application/json
sender
optional
object

User who sent this message. Can be null if message has been posted on behalf of a channel

recipient
object

Message recipient. Could be user or chat

timestamp
integer

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 null for dialogs or non-public chats/channels

constructor
optional
object Nullable
Default:

Bot-constructor created this message

Answer on callback

post /answers
https://botapi.tamtam.chat/answers

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

Identifies a button clicked by user. Bot receives this identifier after user pressed button as part of MessageCallbackUpdate

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

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Construct message

post /answers/constructor
https://botapi.tamtam.chat/answers/constructor

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 (NewMessageBody)

Array of prepared messages. This messages will be sent as user taps on "Send" button

allow_user_input
optional
boolean

If true user can send any input manually. Otherwise, only keyboard will be shown

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

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

subscriptions

Get subscriptions

get /subscriptions
https://botapi.tamtam.chat/subscriptions

In case your bot gets data via WebHook, the method returns list of all subscriptions

Authorizations:
Response: application/json
subscriptions
Array of objects (Subscription)

Current subscriptions

Subscribe

post /subscriptions
https://botapi.tamtam.chat/subscriptions

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 Update object for a complete list of types

version
optional
string

Version of API. Affects model representation

Response: application/json
success
boolean

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Unsubscribe

delete /subscriptions
https://botapi.tamtam.chat/subscriptions

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

true if request was successful. false otherwise

message
optional
string

Explanatory message if the result is not successful

Get updates

get /updates
https://botapi.tamtam.chat/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
integerNullable

Pass null to get updates you didn't get yet

types
optional
Array of strings Nullable
Example: types=types=message_created,message_callback

Comma separated list of update types your bot want to receive

Response: application/json
updates
Array of objects (Update)

Page of updates

marker
integerNullable

Pointer to the next data page

upload

Get upload URL

post /uploads
https://botapi.tamtam.chat/uploads

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

user_id
integer

Users identifier

name
string

Users visible name

username
string Nullable

Unique public user name. Can be null if user is not accessible or it is not set

is_bot
boolean

true if user is bot

Copy
Expand all Collapse all
{
  • "user_id": 0,
  • "name": "string",
  • "username": "string",
  • "is_bot": true
}

Chat

chat_id
integer

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:

  • active: bot is active member of chat
  • removed: bot was kicked
  • left: bot intentionally left chat
  • closed: chat was closed
  • suspended: bot was stopped by user. Only for dialogs
title
string Nullable

Visible title of chat. Can be null for dialogs

icon
object Nullable

Icon of chat

last_event_time
integer

Time of last event occurred in chat

participants_count
integer

Number of people in chat. Always 2 for dialog chat type

owner_id
optional
integerNullable

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 false for dialogs

link
optional
string Nullable

Link on chat if it is public

description
any Nullable

Chat description

dialog_with_user
optional
object Nullable

Another user in conversation. For dialog type chats only

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 chat button initialized chat

pinned_message
optional
object Nullable

Pinned message in chat or channel. Returned only when single chat is requested

Copy
Expand all Collapse all
{
  • "chat_id": 0,
  • "type": "dialog",
  • "status": "active",
  • "title": "string",
  • "icon":
    {
    },
  • "last_event_time": 0,
  • "participants_count": 0,
  • "owner_id": 0,
  • "participants":
    {
    },
  • "is_public": true,
  • "link": "string",
  • "description": null,
  • "dialog_with_user":
    {
    },
  • "messages_count": 0,
  • "chat_message_id": "string",
  • "pinned_message":
    {
    }
}

Message

sender
optional
object

User who sent this message. Can be null if message has been posted on behalf of a channel

recipient
object

Message recipient. Could be user or chat

timestamp
integer

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 null for dialogs or non-public chats/channels

constructor
optional
object Nullable
Default:

Bot-constructor created this message

Copy
Expand all Collapse all
{
  • "sender":
    {
    },
  • "recipient":
    {
    },
  • "timestamp": 0,
  • "link":
    {
    },
  • "body":
    {
    },
  • "stat":
    {
    },
  • "url": "string",
  • "constructor":
    {
    }
}

New message

text
string <= 4000 characters Nullable

Message text

attachments
Array of objects (AttachmentRequest) Nullable

Message attachments. See AttachmentRequest and it's inheritors for full information

link
object Nullable

Link to Message

notify
optional
boolean
Default: true

If false, chat participants would not be notified

Copy
Expand all Collapse all
{
  • "text": "string",
  • "attachments":
    [
    ],
  • "link":
    {
    },
  • "notify": true
}

Update

update_type
string
timestamp
integer

Unix-time when event has occurred

callback
object
message
object Nullable

Original message containing inline keyboard. Can be null in case it had been deleted by the moment a bot got this update

user_locale
optional
string Nullable

Current user locale in IETF BCP 47 format

Example
Copy
Expand all Collapse all
{
  • "update_type": "message_callback",
  • "timestamp": 0,
  • "callback":
    {
    },
  • "message":
    {
    },
  • "user_locale": "string"
}