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'.
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.
We support GET and POST HTTP methods. We support four ways of passing parameters in Bot API requests:
Use this method to receive incoming updates using long polling (wiki). An Array of Update objects is returned.
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.
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.
Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True on success.
Parameter | Type | Required | Description |
---|---|---|---|
drop_pending_updates | Boolean | Optional | Pass True to drop all pending updates |
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.
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 |
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
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
**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:
<br>
), simply type a carriage return at the end of the line.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 |
Use this method to send photos. On success, the sent Message is returned.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
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 |
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 |
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 |
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. |
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 |
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 |
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 |
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. |
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 |
Field | Type | Description |
---|---|---|
inline_keyboard | Array of Array of InlineKeyboardButton | Array of button rows, each represented by an Array of InlineKeyboardButton objects |
{ "inline_keyboard":[ [ {"text":"test1", "url":"www.test.com"}, {"text":"test2", "url":"www.test2.com","callback_data":"t2"} ] ] }
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用戶授權流程:
首先,使用控制台生成私鑰:openssl genrsa 2048 > private.key
然後,使用控制台生成公鑰:openssl rsa -in private.key -pubout
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過期判斷。