QQ

დაუკავშირეთ PRX QQ-ს ოფიციალური Bot API-ის გამოყენებით პირადი შეტყობინებების, ჯგუფური ჩატების, გილდიებისა და მედია დანართების მხარდაჭერით.

წინაპირობები

• QQ ანგარიში (პირადი ან საწარმოო)
• ბოტის აპლიკაცია რეგისტრირებული QQ Open Platform-ზე
• App ID და App Secret დეველოპერ კონსოლიდან
• ბოტი უნდა იყოს დამტკიცებული და გამოქვეყნებული (sandbox რეჟიმი ხელმისაწვდომია ტესტირებისთვის)

სწრაფი დაყენება

1. QQ ბოტის შექმნა

1. გადადით QQ Open Platform-ზე და შედით QQ ანგარიშით
2. გადადით "Applications"-ში და შექმენით ახალი ბოტის აპლიკაცია
3. შეავსეთ ბოტის სახელი, აღწერა და ავატარი
4. "Development Settings"-ში დააკოპირეთ App ID და App Secret
5. კონფიგურირეთ ბოტის intents (შეტყობინების ტიპები, რომლებიც ბოტმა უნდა მიიღოს)
6. ტესტირებისთვის ჩართეთ sandbox რეჟიმი, რომელიც ბოტს მოსანიშნ სატესტო გილდიაზე ზღუდავს

2. კონფიგურაცია

დაამატეთ შემდეგი თქვენს PRX კონფიგურაციის ფაილში:

[channels_config.qq]
app_id = "102012345"
app_secret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
allowed_users = ["user_openid_1", "user_openid_2"]
sandbox = true

მიუთითეთ sandbox = false ბოტის პროდაქშენისთვის დამტკიცების შემდეგ.

3. შემოწმება

prx channel doctor qq

კონფიგურაციის მითითება

ველი	ტიპი	ნაგულისხმევი	აღწერა
app_id	String	სავალდებულო	აპლიკაციის ID QQ Open Platform დეველოპერ კონსოლიდან
app_secret	String	სავალდებულო	აპლიკაციის საიდუმლო დეველოპერ კონსოლიდან
allowed_users	[String]	[]	ნებადართული მომხმარებლის OpenID-ები. ცარიელი = დაწყვილების რეჟიმი. "*" = ყველას დაშვება
sandbox	bool	false	ჩართვისას sandbox გეითვეისთან უკავშირდება ტესტირებისთვის
intents	[String]	["guilds", "guild_messages", "direct_messages"]	მოვლენების intents გამოსაწერად
stream_mode	String	"none"	სტრიმინგის რეჟიმი: "none" ან "typing". აკრეფის რეჟიმი აგზავნის აკრეფის ინდიკატორს გენერირებისას
interrupt_on_new_message	bool	false	ჩართვისას იგივე გამგზავნის ახალი შეტყობინება აუქმებს მიმდინარე მოთხოვნას
mention_only	bool	false	ჩართვისას მხოლოდ @-მოხსენიებებს პასუხობს ჯგუფურ ან გილდიის არხებში. პირადი შეტყობინებები ყოველთვის მუშავდება
ack_reactions	bool	მემკვიდრეობითი	გლობალური ack_reactions პარამეტრის გადაფარვა. თუ მითითებული არ არის, უკან ბრუნდება [channels_config].ack_reactions-ზე

როგორ მუშაობს

PRX QQ Bot API-თან WebSocket-ზე დაფუძნებული მოვლენების ნაკადით უკავშირდება. კავშირის სასიცოცხლო ციკლი:

1. ავთენტიფიკაცია -- PRX წვდომის ტოკენს იღებს App ID-ისა და App Secret-ის გამოყენებით OAuth2 კლიენტის სანდოობის მონაცემებით
2. გეითვეის აღმოჩენა -- ბოტი WebSocket გეითვეის URL-ს ითხოვს QQ API-დან
3. სესიის დამყარება -- WebSocket კავშირი იხსნება გეითვეისთან წვდომის ტოკენით
4. Intent-ის გამოწერა -- ბოტი აცხადებს, რომელი მოვლენების ტიპები სურს მიიღოს
5. მოვლენების ციკლი -- შემომავალი შეტყობინებები PRX აგენტის ციკლში გადაიგზავნება; პასუხები REST API-ით იგზავნება

QQ Gateway (WSS) ──► PRX არხის დამმუშავებელი ──► აგენტის ციკლი
                                                      │
QQ REST API ◄───── შეტყობინებით პასუხი ◄──────────────┘

ფუნქციები

• გილდიისა და ჯგუფის შეტყობინებები -- პასუხობს QQ გილდიებში (არხებში) და ჯგუფურ ჩატებში
• პირადი შეტყობინებები -- 1:1 პირადი საუბრების დამუშავება მომხმარებლებთან
• დაწყვილების რეჟიმი -- უსაფრთხო ერთჯერადი კოდით მიბმა, როდესაც ნებადართული მომხმარებლები კონფიგურირებული არ არის
• მედია დანართები -- სურათების, ფაილებისა და მდიდარი მედია ბარათების გაგზავნისა და მიღების მხარდაჭერა
• Markdown პასუხები -- QQ ბოტები Markdown-ის ფორმატირების ქვეკომპლექტს მხარს უჭერს პასუხებში
• დადასტურების რეაქციები -- შემომავალ შეტყობინებებზე რეაგირება მიღების დასადასტურებლად ჩართვისას
• Sandbox რეჟიმი -- ბოტის ტესტირება იზოლირებულ გილდიის გარემოში პროდაქშენის განთავსებამდე
• ტოკენის ავტომატური განახლება -- წვდომის ტოკენები ავტომატურად განახლდება ვადის გასვლამდე
• კროსპლატფორმული -- მუშაობს QQ desktop-ზე, მობილურზე და QQ for Linux-ზე

შეტყობინების ტიპები

QQ Bot API მრავალ შეტყობინების შინაარსის ტიპს მხარს უჭერს:

ტიპი	მიმართულება	აღწერა
ტექსტი	გაგზავნა / მიღება	ტექსტური შეტყობინებები, 2048 სიმბოლომდე
Markdown	გაგზავნა	ფორმატირებული ტექსტი QQ-ს Markdown ქვეკომპლექტით
სურათი	გაგზავნა / მიღება	სურათის დანართები (JPEG, PNG, GIF)
ფაილი	მიღება	ფაილური დანართები მომხმარებლებისგან
მდიდარი ჩაშვება	გაგზავნა	სტრუქტურირებული ბარათის შეტყობინებები სათაურით, აღწერითა და ესკიზით
Ark შაბლონი	გაგზავნა	შაბლონზე დაფუძნებული მდიდარი შეტყობინებები QQ-ს Ark სისტემით

Intents

Intents აკონტროლებს, რომელ მოვლენებს იღებს ბოტი. ხელმისაწვდომი intents:

Intent	მოვლენები	შენიშვნები
guilds	გილდიის შექმნა, განახლება, წაშლა	გილდიის მეტამონაცემების ცვლილებები
guild_members	წევრის დამატება, განახლება, ამოშლა	მოითხოვს ამაღლებულ ნებართვებს
guild_messages	შეტყობინებები გილდიის ტექსტურ არხებში	ყველაზე გავრცელებული intent
guild_message_reactions	რეაქციის დამატება/ამოშლა გილდიებში	ემოჯი რეაქციები
direct_messages	პირადი შეტყობინებები ბოტთან	ყოველთვის რეკომენდებული
group_and_c2c	ჯგუფური ჩატები და C2C შეტყობინებები	მოითხოვს ცალკე დამტკიცებას
interaction	ღილაკის დაწკაპუნებები და ურთიერთქმედებები	ინტერაქტიული შეტყობინების კომპონენტებისთვის

შეზღუდვები

• QQ Bot API რეგიონით შეზღუდულია; ბოტები ძირითადად ჩინეთის მატერიკზეა ხელმისაწვდომი
• Sandbox რეჟიმი ბოტს ერთ სატესტო გილდიაზე ზღუდავს მცირე რაოდენობის წევრებით
• პროდაქშენის ბოტები მოითხოვს QQ Open Platform-ის განხილვის გუნდის დამტკიცებას
• ჯგუფური ჩატი და C2C შეტყობინებები ცალკე ნებართვის განაცხადს მოითხოვს
• ფაილების ატვირთვა 20 MB-ით არის შეზღუდული თითო დანართზე
• შინაარსის მოდერაცია QQ-ს მიერ აღსრულდება; აკრძალულ შინაარსის შემცველი შეტყობინებები ჩუმად იშლება
• რეიტ ლიმიტები მოქმედებს: დაახლოებით 5 შეტყობინება წამში თითო გილდიაზე, 2 წამში პირადებისთვის
• ბოტს არ შეუძლია საუბრების წამოწყება; მომხმარებლებმა ან ადმინისტრატორებმა ჯერ ბოტი უნდა დაამატონ

პრობლემების მოგვარება

ბოტი QQ გეითვეისთან არ უკავშირდება

• შეამოწმეთ app_id და app_secret სწორია prx channel doctor qq-ით
• Sandbox რეჟიმის გამოყენებისას დარწმუნდით, რომ sandbox = true მითითებულია (sandbox და პროდაქშენი სხვადასხვა გეითვეის იყენებს)
• შეამოწმეთ, რომ api.sgroup.qq.com-თან და WebSocket გეითვეისთან გამავალი კავშირები არ არის დაბლოკილი

ბოტი უკავშირდება, მაგრამ შეტყობინებებს არ იღებს

• შეამოწმეთ სწორი intents კონფიგურირებულია თქვენი გამოყენების შემთხვევისთვის
• გილდიის არხებში ბოტს შეიძლება დასჭირდეს "Receive Messages" ნებართვის მინიჭება გილდიის ადმინისტრატორის მიერ
• შეამოწმეთ გამგზავნი მომხმარებლის OpenID allowed_users-შია, ან მიუთითეთ allowed_users = ["*"]

პასუხები არ მიტანილა

• QQ შინაარსის მოდერაციას აღასრულებს; შეამოწმეთ PRX ლოგები API-დან უარყოფის პასუხებისთვის
• დარწმუნდით, რომ ბოტს აქვს "Send Messages" ნებართვა სამიზნე გილდიაში ან ჯგუფში
• პირადი პასუხებისთვის მომხმარებელმა ჯერ ბოტს უნდა მისწეროს საუბრის გასახსნელად

ტოკენის განახლების შეფერხებები

• App Secret შეიძლება როტაცია გაიარა დეველოპერ კონსოლში; განაახლეთ კონფიგურაცია ახალი საიდუმლოთი
• ქსელის პრობლემებმა შეიძლება ტოკენის განახლება შეაფერხოს; შეამოწმეთ კავშირი bots.qq.com-თან

დაკავშირებული გვერდები

• არხების მიმოხილვა
• DingTalk -- მსგავსი გამართვა DingTalk პლატფორმისთვის
• Lark -- მსგავსი გამართვა Lark / Feishu-სთვის
• უსაფრთხოება: დაწყვილება -- ერთჯერადი მიბმის კოდით დაწყვილების დეტალები