TamTam Bot API (0.1.10)

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.

PrimeBot commands:

/start — start a dialog with a bot

/create — create a bot, assign the unique short name to it (from 4 to 64 characters)

/set_name [name] — assign a short or full name to the bot (up to 200 characters)

/set_description [description] — enter the description for the bot profile (up to 400 characters)

/set_picture [URL] — enter the URL of bot's picture

/delete [username] — delete the bot

/list — show the list of all bots

/get_token — obtain a token for a bot

/revoke — request a new token

/help — help

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

Message buttons

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

callback — sends a notification 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)

You may also send a message with an InlineKeyboard type attachment to start creating buttons. When the user presses a button, the bot receives the answer with filled callback field. It is recommended to edit that message so the user can receive updated buttons.

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 created Java library to make using API easier.

Changelog

Version 0.1.9
  • Added method to get chat administrators
  • For type: dialog chats added dialog_with_user
  • Added url for messages in public chats/channels
  • Removed callback_id of InlineKeyboardAttachment
  • Removed user_id of CallbackAnswer. It is no longer required. Just use callback_id of Callback
  • Several minor improvements: check diff for all changes
Version 0.1.8
Version 0.1.7
  • It is now required to pass marker parameter in /updates requests, except initial
  • Added full User object to update types: bot_started, bot_added, bot_removed, user_added, user_removed, chat_title_changed
  • Added size and filename to FileAttachment
  • Added token property to video/audio/file attachments allows you to reuse attachments uploaded by another user
Version 0.1.6
  • Added method to edit bot info
  • Added statistics for messages in channel
  • Message.sender and UserWithPhoto.avatar_url/full_avatar_url removed from required properties

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 type:API 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

avatar_url
optional
string

URL of avatar

full_avatar_url
optional
string

URL of avatar of a bigger size

commands
optional
Array of object (BotCommand) <= 32 items Nullable

Commands supported by bot

description
optional
string <= 16000 characters Nullable

Bot description

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 object (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

avatar_url
optional
string

URL of avatar

full_avatar_url
optional
string

URL of avatar of a bigger size

commands
optional
Array of object (BotCommand) <= 32 items Nullable

Commands supported by bot

description
optional
string <= 16000 characters Nullable

Bot description

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 object (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
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 (UserWithPhoto) Nullable

Another user in conversation. For dialog type chats only

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
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
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 (UserWithPhoto) Nullable

Another user in conversation. For dialog type chats only

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

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 string 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 adminstrator in requested chat.

Authorizations:
path Parameters
chatId
integer\-\d+

Chat identifier

Response: application/json
members
Array of object (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 integerNullable

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 object (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 integer
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

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 string 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 object (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

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

Message text

attachment
optional
object Nullable
Deprecated

Use attachments property instead. Will be removed in the next major release.

Single message attachment

attachments
Array of object (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 wouldn't 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

attachment
optional
object Nullable
Deprecated

Use attachments property instead. Will be removed in the next major release.

Single message attachment

attachments
Array of object (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 wouldn't 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

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

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 object (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 string

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 string Nullable
Example: "types=message_created,message_callback"

Comma separated list of update types your bot want to receive

Response: application/json
updates
Array of object (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:"photo" "video" "audio" "file"

Uploaded file type: photo, audio, video, file

Response: application/json
url
string

URL to upload