Start

Use the /newbot command to create a new bot. The BotFather will ask you for a name and username, then generate an authorization token for your new bot.

The name of your bot is displayed in contact details and elsewhere.

The Username is a short name, to be used in mentions and cccc.tel links. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot's username must end in 'bot', e.g. 'test1_bot' or 'Test1Bot'.

Authorizing your bot

Each bot is given a unique authentication token when it is created. The token looks something like 12345678:1cvV9xN7DLzbgSSV4NFsYo3mqSg, but we'll use simply <token> in this document instead.

Making requests

We support GET and POST HTTP methods. We support four ways of passing parameters in Bot API requests:

  • URL query string
  • application/x-www-form-urlencoded
  • application/json (except for uploading files)
  • multipart/form-data (use to upload files)

getUpdates

Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is returned.

Request Method :Post

setWebhook

Use this method to specify a url and receive incoming updates via an outgoing webhook. Whenever there is an update for the bot, we will send an HTTPS POST request to the specified url, containing a JSON-serialized Update. In case of an unsuccessful request, we will give up after a reasonable amount of attempts. Returns True on success.

If you'd like to make sure that the Webhook request comes from CloudChat, we recommend using a secret path in the URL, e.g. https://www.example.com/<token>. Since nobody else knows your bot's token, you can be pretty sure it's us.

Request Method :Post
Parameter Type Required Description
url String Yes HTTPS url to send updates to. Use an empty string to remove webhook integration.Due to GFW restrictions, users in mainland China should use URL addresses outside mainland China.
certificate InputFile Yes Upload your public key certificate so that the root certificate in use can be checked. See our self-signed guide for details.
max_connections Integer Optional Maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery, 1-100. Defaults to 40. Use lower values to limit the load on your bot's server, and higher values to increase your bot's throughput.
drop_pending_updates Boolean Optional Pass True to drop all pending updates

Notes
1. You will not be able to receive updates using getUpdates for as long as an outgoing webhook is set up.
2. To use a self-signed certificate, you need to upload your public key certificate using certificate parameter. Please upload as InputFile, sending a String will not work.
3. Ports currently supported for Webhooks: 443, 80, 88, 8443.

Due to the GFW restrictions in mainland China, webhook cannot be pushed. If you need to receive webhook, please fill in the url address outside mainland China.

deleteWebhook

Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True on success.

Request Method :Post
Parameter Type Required Description
drop_pending_updates Boolean Optional Pass True to drop all pending updates

getWebhookInfo

Use this method to get current webhook status. Requires no parameters. On success, returns a WebhookInfo object. If the bot is using getUpdates, will return an object with the url field empty.

Request Method :Post

WebhookInfo

Contains information about the current status of a webhook.

Field Type Description
url String Webhook URL, may be empty if webhook is not set up
has_custom_certificate Boolean True, if a custom certificate was provided for webhook certificate checks
pending_update_count Integer Number of updates awaiting delivery
ip_address String Optional. Currently used webhook IP address
last_error_date Integer Optional. Unix time for the most recent error that happened when trying to deliver an update via webhook
last_error_message String Optional. Error message in human-readable format for the most recent error that happened when trying to deliver an update via webhook
last_synchronization_error_date Integer Optional. Unix time of the most recent error that happened when trying to synchronize available updates with Telegram datacenters
max_connections Integer Optional. Maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery
allowed_updates Array of String Optional. A list of update types the bot is subscribed to. Defaults to all update types except chat_member

getMe

A simple method for testing your bot's auth token. Requires no parameters. Returns basic information about the bot in form of a User object.

Request Method:Get 
Request Url:https://api.cloudchat.com/<bot_token>/getMe

sendTextMessage

Use this method to send text messages. On success, the sent Message is returned.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/sendTextMessage
Parameter Type Required Description
chat_id Integer Yes Unique identifier for the target chat
chat_type ChatType Yes Type for the target chat
text String Yes Text of the message to be sent, 1-4096 characters after entities parsing
parse_mode String Optional Mode for parsing entities in the message text. See Markdown style for more details.
reply_to_message_id Integer Optional If the message is a reply, ID of the original message

Markdown style

To use this mode, pass Markdown in the parse_mode field. Use the following syntax in your message:
**bold**
*italic*
***bold and italic***
`your code`
```
your code block
```
[inline URL](http://www.example.com/)
[inline mention of a user](cc://user?id=123456789)

Please note:

  • Line Breaks
          To create a newline or line break (<br>), simply type a carriage return at the end of the line.
  • Bold
          To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.
  • Italic
          To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.
  • Bold and Italic
          To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces around the letters.
  • Code
          To denote a word or phrase as code, enclose it in backticks (`).
  • Code Blocks
          To create code blocks use three backticks (```)on the lines before and after the code block.
  • Links
          To create a link, enclose the link text in brackets (e.g., [Tree Not Three]) and then follow it immediately with the URL in parentheses (e.g., (https://treetnothree.com)).
  • Inline mention of a user
          Similar to creating a hyperlink, enclose the mentioned name in brackets and then follow it immediately with the cc URL in parentheses(e.g., (cc://user?id=12345)).
  • Escaping Characters
          To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (\) in front of the character.

forwardMessage

Use this method to forward messages of any kind. On success, the sent Message is returned.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/forwardMessage
Parameter Type Required Description
chat_id Integer Yes Unique identifier for the target chat
from_chat_id Integer Yes Unique identifier for the chat where the original message was sent
message_id Integer Yes Message identifier in the chat specified in from_chat_id

sendPhoto

Use this method to send photos. On success, the sent Message is returned.

Request Method:Post
Request Url:https://api.cloudchat.com/<bot_token>/sendPhoto
Parameter Type Required Description
chat_id Integer Yes Unique identifier for the target chat
chat_type ChatType Yes Type for the target chat
photo InputFile Yes This object represents the contents of a file to be uploaded. Must be posted using multipart/form-data in the usual way that files are uploaded via the browser.
caption String Optional Photo caption, 0-1024 characters after entities parsing
parse_mode String Optional Mode for parsing entities in the photo caption. See Markdown style for more details.
reply_to_message_id Integer Optional If the message is a reply, ID of the original message

sendDocument

Use this method to send general files. On success, the sent Message is returned. Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future.

Parameter Type Required Description
chat_id Integer Yes Unique username of the target channel (in the format @channelusername)
chat_type ChatType Yes Type for the target chat
document InputFile Yes This object represents the contents of a file to be uploaded. Must be posted using multipart/form-data in the usual way that files are uploaded via the browser.
caption String Optional Document caption , 0-1024 characters after entities parsing
parse_mode String Optional Mode for parsing entities in the document caption. See Markdown style for more details.
reply_to_message_id Integer Optional If the message is a reply, ID of the original message

kickChatMember

Use this method to kick a user from a supergroup or a channel.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/kickChatMember
Parameter Type Required Description
chat_id String Yes Unique username of the target channel
user_id Integer Yes Unique identifier of the target user

setChatTitle

Use this method to change the title of a chat. Titles can't be changed for private chats. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/setChatTitle
Parameter Type Required Description
chat_id String Yes Unique username of the target channel
title String Yes New chat title, 1-255 characters

setChatDescription

Use this method to change the description of a group, a supergroup or a channel. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Returns True on success.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/setDescription
Parameter Type Required Description
chat_id String Yes Unique username of the target channel
description String Optional New chat description, 0-255 characters

pinChatMessage

Use this method to pin a message in a group, a supergroup, or a channel. The bot must be an administrator in the chat for this to work and must have the 'can_pin_messages' admin right in the supergroup or 'can_edit_messages' admin right in the channel. Returns True on success.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/pinChatMessage
Parameter Type Required Description
chat_id String Yes Unique username of the target channel
message_id Integer Yes Identifier of a message to pin

unpinChatMessage

Use this method to unpin a message in a group, a supergroup, or a channel. The bot must be an administrator in the chat for this to work and must have the 'can_pin_messages' admin right in the supergroup or 'can_edit_messages' admin right in the channel. Returns True on success.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/unpinChatMessage
Parameter Type Required Description
chat_id String Yes Unique username of the target channel

leaveChat

Use this method for your bot to leave a group, supergroup or channel. Returns True on success.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/leaveChat
Parameter Type Required Description
chat_id String Yes Unique username of the target supergroup or channel.

getChat

Use this method to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.). Returns a Chat object on success.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/getChat
Parameter Type Required Description
chat_id Integer or String Yes Unique identifier for the target chat or username of the target supergroup or channel

getChatAdministrators

Use this method to get a list of administrators in a chat. On success, returns an Array of ChatMember objects that contains information about all chat administrators except other bots. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned.

Request Method:Post 
Request Url:https://api.cloudchat.com/<bot_token>/getChat
Parameter Type Required Description
chat_id Integer Yes Unique id of the target supergroup or channel

getChatMembersCount

Use this method to get the number of members in a chat. Returns Int on success.

Parameter Type Required Description
chat_id String Yes Unique username of the target supergroup or channel

getChatMember

Use this method to get information about a member of a chat. Returns a ChatMember object on success.

Parameter Type Required Description
chat_id String Yes Unique username of the target supergroup or channel
user_id Integer Yes Unique identifier of the target user

editMessageText

Use this method to edit text and game messages. On success, if edited message is sent by the bot, the edited Message is returned, otherwise True is returned.

Parameter Type Required Description
chat_id Integer Optional Unique identifier for the target chat,group or channel
message_id Integer Optional Identifier of the message to edit
text String Yes New text of the message, 1-4096 characters after entities parsing
reply_markup InlineKeyboardMarkup Optional A JSON-serialized object for an inline keyboard.

deleteMessage

Use this method to delete a message, including service messages

Parameter Type Required Description
chat_id Integer Yes Unique identifier for the target chat,group or channel
message_id Integer Yes Identifier of the message to delete
chat_type ChatType Yes Type for the target chat

ChatType

Used to define the type of chat dialog box, the following is the type of Chat object can be used.

Value Description
2 user to user chat
4 channel or group chat

User

This object represents a CC user or bot.

Field Type Description
id Integer Unique identifier for this user or bot
is_bot Boolean True, if this user is a bot
first_name String User's or bot's first name
last_name String Optional. User's or bot's last name
username String Optional. User's or bot's username

Chat

This object represents a chat.

Field Type Description
id Integer Unique identifier for this chat. This number may be greater than 32 bits and some programming languages may have difficulty/silent defects in interpreting it. But it is smaller than 52 bits, so a signed 64 bit integer or double-precision float type are safe for storing this identifier.
type String Type of chat, can be either “private”, “group”, “supergroup” or “channel”
title String Optional. Title, for supergroups, channels and group chats
username String Optional. Username, for private chats, supergroups and channels if available
first_name String Optional. First name of the other party in a private chat
last_name String Optional. Last name of the other party in a private chat
description String Optional. Description, for groups, supergroups and channel chats.

Message

This object represents a message.

Field Type Description
message_id Integer Unique message identifier inside this chat
from User Optional. Sender, empty for messages sent to channels
date Integer Date the message was sent in Unix time
chat Chat Conversation the message belongs to
forward_from User Optional. For forwarded messages, sender of the original message
forward_from_chat Chat Optional. For messages forwarded from channels, information about the original channel
forward_from_message_id Integer Optional. For messages forwarded from channels, identifier of the original message in the channel
forward_sender_name String Optional. Sender's name for messages forwarded from users who disallow adding a link to their account in forwarded messages
forward_date Integer Optional. For forwarded messages, date the original message was sent in Unix time
reply_to_message Message Optional. For replies, the original message. Note that the Message object in this field will not contain further reply_to_message fields even if it itself is a reply.
via_bot User Optional. Bot through which the message was sent
edit_date Integer Optional. Date the message was last edited in Unix time
media_group_id String Optional. The unique identifier of a media message group this message belongs to
text String Optional. For text messages, the actual UTF-8 text of the message, 0-4096 characters

InlineKeyboardMarkup

This object represents an inline keyboard that appears right next to the message it belongs to.
Field Type Description
inline_keyboard Array of Array of InlineKeyboardButton Array of button rows, each represented by an Array of InlineKeyboardButton objects

json e.g.
{
  "inline_keyboard":[
      [
        {"text":"test1", "url":"www.test.com"},
        {"text":"test2", "url":"www.test2.com","callback_data":"t2"}
      ]
    ]
}

InlineKeyboardButton

This object represents one button of an inline keyboard. You must use exactly one of the optional fields.
Field Type Description
text String Label text on the button
url String Optional. HTTP or cloudchat:// url to be opened when button is pressed
callback_data String Optional. Data to be sent in a callback query to the bot when button is pressed, 1-64 bytes

機器人用戶授權

要訪問CC用戶的個人資料、資產等數據，開發者需要向用戶申請授權。
機器人申請CC用戶授權流程：

  • 創建您的機器人 /newbot
  • 設置機器人應用網址 /setapplink
  • 要向CloudChat用戶請求授權，您的機器人需要生成一對加密密鑰。
    首先，使用控制台生成私鑰：openssl genrsa 2048 > private.key
    然後，使用控制台生成公鑰：openssl rsa -in private.key -pubout
  • 使用命令 /setpublickey 設置公鑰
  • 取得您的 botid，可透過 /mybot 得知
  • 在應用中創建登陸 CC 按鈕，透過按鈕呼叫 
    cloudchat://resolve?domain=cloudchatpassport&bot_id=[您的BotId]&callback_url=[取得資料的網址]&scope=PROFILE,PHONE,USERNAME

scope定義：

基本資訊（必填項）：PROFILE
電話：PHONE
CC號：USERNAME
scope為應用需要授權的選項參數，使用,分割


  • 完成用戶授權後伺服器會呼叫

    取得資料的網址?tg_passport=success&hash=[透過RSA公鑰加密的資料]
    [透過RSA公鑰加密的資料]使用Base64(URL Encode)傳輸數據，請先解開數據
    然後透過私鑰來解開[透過RSA公鑰加密的資料]，資料內容為標準 QueryString 組合

    資料解析範例：
    userid=10000777&first_name=EVAN&last_name=LU&username=@_4kzvbw3kE3j&photo_url=https://cccc.tel/avatar/-vYSnmLsU8xPA&authtime=1649741563

返回參數定義說明：

Field Type Description
userid Integer 授權使用者 ID
first_name String 授權使用者的名子
last_name String 授權使用者的姓
username String （Optional）使用者的 CC 帳號
photo_url String （Optional）頭像網址
authtime Integer 取得授權時間

建議開發者緩存返回的hash數據作為token使用，authtime為返回數據的時間戳，可以作為hash過期判斷。