Travailler avec les identifiants de plateforme dans MaviBot

Dans MaviBot, toutes les entités Telegram (utilisateurs, groupes, canaux) sont identifiées par une variable générique platform_id. Cette variable ne fait pas de distinction entre les types d'entités.

Problème : Pour utiliser des fonctions comme accept ou reject qui nécessitent des types d'entités spécifiques, vous devez connaître séparément l'ID du chat et l'ID de l'utilisateur.

Solution : Lorsque vous recevez un callback ou un message, stockez immédiatement la valeur platform_id dans deux variables distinctes nommées en fonction de leur objectif :

  • chat_id – pour stocker l'ID du groupe/canal.
  • user_id – pour stocker l'ID de l'utilisateur individuel.

Cela vous permet de référencer le bon ID plus tard dans votre logique applicative.

Comment modifier le nom d'un chat via un bot Telegram

Description

tg_set_group_title(platform_id, title)

Modifie le titre d'un groupe Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat dans Telegram.
title Nouveau nom du chat.
Paramètre Description
**!** platform_id l'ID du chat dans Telegram *
**!** title nouveau nom du chat

Comment modifier la description d'un chat via un bot Telegram

Description

tg_set_chat_description(platform_id, description)

Modifie la description d'un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat dans Telegram.
description Nouvelle description du chat.
Paramètre Description
**!** platform_id l'ID du chat dans Telegram *
**!** description nouveau nom du chat

Comment définir un avatar dans un groupe/chat Telegram

Description

tg_set_chat_photo(platform_id, photo)

Définit une nouvelle photo de profil pour un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat dans Telegram où vous souhaitez définir une nouvelle photo de profil.
photo Lien direct vers la photo.
Paramètre Description
**!** platform_id ID du chat dans Telegram *, dans lequel vous souhaitez définir un avatar
**!** photo lien photo

Comment supprimer un avatar dans un groupe/chat Telegram

Description

tg_delete_chat_photo(platform_id)

Supprime la photo de profil actuelle d'un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat dans Telegram dont vous souhaitez supprimer la photo de profil.
Paramètre Description
**!** platform_id ID du chat dans Telegram *, dans lequel vous devez définir un avatar

Comment bannir un groupe Telegram

Description

tg_ban_chat_sender_chat(platform_id, sender_chat_id)

Bannit un chat expéditeur de la publication de messages dans un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram où le chat expéditeur sera banni.
sender_chat_id L'ID du chat expéditeur à bannir.

Remarque

Une fois banni, le propriétaire du chat expéditeur ne pourra plus publier de messages au nom de ce chat dans le chat Telegram spécifié jusqu'à ce que le bannissement soit levé.

Paramètre Description
**!** platform_id ID du chat dans Telegram *, que vous devez bannir
**!** sender_chat_id ID du chat qui va être banni

En même temps, le propriétaire du chat banni ne peut pas écrire au nom de ses autres chats tant qu'il/elle est banni(e).

Comment débloquer un groupe Telegram

Description

tg_unban_chat_sender_chat(platform_id, sender_chat_id)

Lève le bannissement d'un chat expéditeur précédemment banni dans un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram où le chat expéditeur sera débanni.
sender_chat_id L'ID du chat expéditeur à débannir.
Paramètre Description
**!** platform_id ID du chat dans Telegram *, dans lequel vous débloquez
**!** sender_chat_id ID du chat que vous débloquez

Comment créer un lien d'invitation pour rejoindre un chat Telegram

Description

Crée un nouveau lien d'invitation pour un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.
member_limit Nombre maximum d'utilisateurs pouvant rejoindre via ce lien d'invitation.
hours Durée d'expiration du lien d'invitation, en heures.
request Si défini sur True, les utilisateurs qui cliquent sur le lien doivent soumettre une demande d'adhésion qu'un administrateur peut approuver.
name Nom personnalisé pour le lien d'invitation.

Important

Si le paramètre member_limit est spécifié, le paramètre request est automatiquement défini sur False.

Pour exiger que les utilisateurs soumettent des demandes d'adhésion, laissez le paramètre member_limit vide.

Paramètre Description
**!** platform_id ID du chat dans Telegram *
member_limit limite du nombre de participants
hours Durée d'expiration du lien (en heures)
request un paramètre qui, après avoir cliqué sur le lien, doit générer une demande pour rejoindre le chat.
name nom du lien

Lors de la transmission du paramètre member_limit, la valeur du paramètre request est automatiquement modifiée en False. Si vous devez accepter des demandes d'adhésion, laissez le paramètre member_limit vide.

Création d'un lien d'invitation de chat

Comment supprimer un lien d'invitation de chat dans Telegram

Description

Révoque un lien d'invitation existant pour un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.
invite_link Le lien d'invitation à révoquer.
Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** invite_link lien que vous devez supprimer

Comment désactiver tous les liens existants et les remplacer par un seul lien 

Description

Crée un nouveau lien d'invitation principal pour un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.

Avertissement

Cette méthode génère un nouveau lien d'invitation principal pour le chat.

Tous les liens d'invitation principaux générés précédemment deviendront inactifs. Le lien nouvellement généré sera le seul lien d'invitation principal actif jusqu'à ce que des liens d'invitation supplémentaires soient créés.

Utilisez cette méthode avec prudence.

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** invite_link lien que vous devez supprimer

Comment accepter une demande et ajouter un utilisateur dans un canal/chat Telegram

Description

tg_approve_chat_join_request(chat_id, user_id)

Approuve une demande d'adhésion en attente pour un groupe ou un canal Telegram.

Paramètres

Paramètre Description
chat_id L'ID du groupe ou du canal Telegram.
user_id L'ID utilisateur Telegram de l'utilisateur dont la demande d'adhésion doit être approuvée.
**!** chat_id ID du groupe/canal dans Telegram *
**!** user_id ID utilisateur dans Telegram *

Acceptation de la demande :

Comment refuser une demande dans un canal/chat Telegram

Description

tg_decline_chat_join_request(chat_id, user_id)

Refuse une demande d'adhésion en attente pour un groupe ou un canal Telegram.

Paramètres

Paramètre Description
chat_id L'ID du groupe ou du canal Telegram.
user_id L'ID utilisateur Telegram de l'utilisateur dont la demande d'adhésion doit être refusée.
**!** chat_id ID du groupe/canal dans Telegram *
**!** user_id ID utilisateur dans Telegram *

Comment bloquer un utilisateur dans Telegram

Description

tg_ban_chat_member(chat_id, user_id, hours)

Bannit un utilisateur d'un chat Telegram.

Paramètres

Paramètre Description
chat_id L'ID du chat Telegram.
user_id L'ID utilisateur Telegram de l'utilisateur à bannir.
hours Durée du bannissement, en heures. Si omis, le bannissement est permanent.

Note

Si la valeur hours dépasse 366 jours, l'utilisateur sera banni définitivement.

Paramètre Description
**!** chat_id ID du chat dans Telegram *
**!** user_id ID de l'utilisateur dans Telegram * à bloquer
hours Durée du blocage en heures. Par défaut, le blocage est permanent. Si vous spécifiez une durée de blocage supérieure à 366 jours, le blocage sera défini comme permanent.

Comment débloquer un utilisateur dans Telegram

Description

tg_unban_chat_member(chat_id, user_id)

Débloque un utilisateur d'un chat Telegram.

Paramètres

Paramètre Description
chat_id L'ID du chat Telegram.
user_id L'ID de l'utilisateur Telegram à débloquer.
Paramètre Description
**!** chat_id ID du chat dans Telegram *
**!** user_id ID de l'utilisateur dans Telegram *, que vous devez débloquer

Comment vérifier le statut d'abonnement dans Telegram

Description

tg_get_chat_member(chat_id, user_id)

Récupère des informations sur le statut d'adhésion d'un utilisateur dans un chat Telegram.

Paramètres

Paramètre Description
chat_id L'ID du chat Telegram.
user_id L'ID de l'utilisateur Telegram dont le statut d'adhésion sera vérifié.
Paramètre Description
**!** chat_id ID du chat dans Telegram *
**!** user_id ID de l'utilisateur dans Telegram *, dont nous vérifions l'abonnement

Comment déterminer le nombre de membres dans un canal/chat

Description

tg_get_chat_member_count(platform_id)

Retourne le nombre total de membres dans un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.
Paramètre Description
**!** platform_id ID du chat dans Telegram *

Comment vérifier si un membre du chat est dans une liste spécifique

some_client_in_list(list_id, recepient)

Vérifie si un utilisateur Telegram est inclus dans la liste spécifiée.

Paramètres

Paramètre Description
list_id L'ID de la liste à vérifier.
recepient L'ID de l'utilisateur Telegram. Pour les membres du chat, utilisez la variable chat_member_id.
Paramètre Description
**!** list_id numéro de la liste
**!** recepient ID de l'utilisateur dans Telegram *. Pour les clients du chat, cette valeur se trouve dans la variable chat_member_id.

Comment afficher les actions du bot à l'utilisateur (imprimer/sélectionner un sticker, etc.)

Description

tg_send_chat_action(platform_id, bot_action, message_thread_id)

Envoie une action de chat (comme taper ou télécharger un fichier) à un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.
bot_action L'action du chat à afficher. Choisissez l'une des actions de chat Telegram prises en charge.
message_thread_id L'ID du sujet. Disponible uniquement pour les supergroupes avec les sujets (Forums) activés.

Note

Cette fonction est prise en charge lors du travail avec les comptes Telegram Business.

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** bot_action action du bot depuis la liste
message_thread_id ID du sujet (disponible pour les supergroupes si la fonctionnalité de forum est disponible).
**Liste des actions disponibles bot_action**

typing pour les messages texte,
&#xNAN;upload_photo pour les photos,
&#xNAN;record_video ou upload_video pour les vidéos,
&#xNAN;record_voice ou upload_voice pour les notes vocales,
&#xNAN;upload_document pour les documents courants,
&#xNAN;choose_sticker pour les stickers,
&#xNAN;find_location pour les données de localisation,
&#xNAN;record_video_note ou upload_video_note pour les notes vidéo.

Cette notification sera affichée jusqu'à ce qu'une réponse soit reçue du bot, mais pas plus de 5 secondes.

Comment afficher une notification d'alerte à l'utilisateur

Description

tg_answer_callback_query(callback_query_id, text, show_alert, cache_time)

Envoie une réponse à une requête de callback déclenchée lorsqu'un utilisateur clique sur un bouton en ligne dans Telegram.

Paramètres

Paramètre Description
callback_query_id L'ID de la requête de callback reçu lorsque l'utilisateur clique sur un bouton en ligne. Cela identifie à quel callback répondre.
text Le texte à afficher dans la notification.
show_alert Contrôle la façon dont la notification est affichée. Définissez sur False pour afficher une notification temporaire de type infobulle, ou True pour afficher une boîte de dialogue d'alerte persistante.
cache_time Le temps maximum, en secondes, pendant lequel la réponse du callback peut être mise en cache côté client. Par défaut à 0. Les clients Telegram prennent en charge la mise en cache à partir de la version 3.14.

Important

Cette fonction ne peut être utilisée qu'en réponse à un clic sur un bouton de callback en ligne dans Telegram.

Exemple

Le clavier en ligne suivant envoie différentes valeurs de callback lorsque chaque bouton est cliqué :

[{"line":0,"index_in_line":0,"text":"111","type":"inline","callback":"first"}, {"line":1,"index_in_line":0,"text":"222","type":"inline","callback":"second"}, {"line":2,"index_in_line":0,"text":"333","type":"inline","callback":"third"}]

Après avoir cliqué sur un bouton, un callback arrive avec le texte contenu dans le champ correspondant. Lorsque vous cliquez sur le bouton "111", vous recevrez un callback avec le texte "first".

Créons un bloc Start et spécifions le texte souhaité dans le déclencheur. Dans notre cas : "first"

Si dans le champ Correspondance vous sélectionnez Ignorer les erreurs et les inexactitudes, ce bloc pourra ensuite être réutilisé pour toutes les variantes similaires qui diffèrent de 1 à 2 caractères. Par exemple, pour remercier l'utilisateur d'avoir fourni une évaluation avec un tel bouton.

Ensuite, dans la calculatrice, utilisez la fonction tg_answer_callback_query et transmettez les paramètres suivants :
callback_query_id - cet ID vous permet d'identifier l'utilisateur qui a appuyé sur le bouton et d'afficher une notification d'alerte.
text - texte de la notification d'alerte.

Exemple de code à copier :

tg_answer_callback_query('#{callback_query_id}', "Vous avez appuyé sur le bouton 111")

Attention ! Le paramètre callback_query_id doit être transmis exactement comme indiqué dans l'exemple, c'est-à-dire à l'intérieur de '#{}'

Si tout est configuré correctement, appuyer sur le bouton entraînera une notification d'alerte avec le texte spécifié. Dans la version mobile, le nom du bot apparaîtra comme en-tête au-dessus du texte.

Si vous souhaitez afficher un simple message contextuel à la place, transmettez False comme troisième paramètre, comme indiqué dans l'exemple ci-dessous :
tg_answer_callback_query('#{callback_query_id}', "Vous avez passé le bouton 222", False)

Ajouter une redirection de bot avec une balise comme réponse de bouton de callback

Description

tg_callback_url_open(callback_query_id, url, cache_time)

Ouvre un bot Telegram en utilisant un lien profond en réponse à un callback de bouton en ligne.

Paramètres

Paramètre Description
callback_query_id L'ID de la requête de callback reçu lorsque l'utilisateur clique sur un bouton en ligne. Cela identifie à quel callback répondre.
url Un lien profond vers le bot au format https://t.me/your_bot?start=XXXX, où your_bot est le nom d'utilisateur du bot et XXXX est le paramètre de démarrage.
cache_time Le temps maximum, en secondes, pendant lequel la réponse du callback peut être mise en cache côté client. Par défaut à 0. Les clients Telegram prennent en charge la mise en cache à partir de la version 3.14.

Important

Cette fonction ne peut être utilisée qu'en réponse à un clic sur un bouton de callback en ligne dans Telegram.

Exemple

Dans la réponse du bouton de callback, vous pouvez ajouter une transition vers le bot en utilisant la balise tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX')

Par exemple, utilisons les boutons suivants :

[{"line":0,"index_in_line":0,"text":"111","type":"inline","callback":"first"}, {"line":1,"index_in_line":0,"text":"222","type":"inline","callback":"second"}, {"line":2,"index_in_line":0,"text":"333","type":"inline","callback":"third"}]

Après avoir cliqué sur un bouton, un callback arrive avec le texte contenu dans le champ correspondant. Lorsque vous cliquez sur le bouton "111", vous recevrez un callback avec le texte "first".

Créez un bloc avec une vérification de condition primaire et spécifiez le texte souhaité dans la condition. Dans notre cas : "first" :

Si dans le champ Option de correspondance vous sélectionnez Ignorer les erreurs et les inexactitudes, ce bloc pourra ensuite être réutilisé pour toutes les variantes similaires qui diffèrent de 1 à 2 caractères. Par exemple, pour remercier l'utilisateur d'avoir fourni une évaluation avec un tel bouton.

Ensuite, dans la calculatrice du bloc, spécifiez tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX') :

Comment promouvoir un utilisateur en administrateur dans un supergroupe ou un canal

Description

tg_promote_user(platform_id, user_id, promote_options_list)

Promouvoir un utilisateur Telegram en administrateur dans un supergroupe ou un canal avec les autorisations spécifiées.

Paramètres

Paramètre Description
platform_id L'identifiant du supergroupe Telegram, ou le nom d'utilisateur du canal au format @channelusername lors de la promotion d'un utilisateur dans un canal.
user_id L'identifiant Telegram de l'utilisateur à promouvoir.
promote_options_list Une liste des autorisations d'administrateur à accorder à l'utilisateur.

Remarque

Seules les autorisations incluses dans promote_options_list seront accordées à l'utilisateur.

**Paramètre requis : promote_options_list**

Les autorisations suivantes peuvent être spécifiées dans promote_options_list :

  1. is_anonymous — masque la présence de l'administrateur dans le chat,
  2. can_manage_chat — l'administrateur peut accéder au journal des événements du chat, aux statistiques du chat, aux statistiques des messages dans les canaux, voir les membres du canal, voir les administrateurs anonymes dans les supergroupes et contourner le mode lent. Ce niveau d'autorisation est accordé par défaut si l'un des privilèges suivants est spécifié
  3. can_post_messages — l'administrateur peut créer des publications dans le canal (canaux uniquement)
  4. can_edit_messages — l'administrateur peut modifier les messages des autres utilisateurs et épingler des messages (canaux uniquement)
  5. can_delete_messages — l'administrateur peut supprimer les messages des autres utilisateurs
  6. can_manage_video_chats — l'administrateur peut gérer les chats vidéo,
  7. can_restrict_members — l'administrateur peut restreindre les membres, les bannir/débannir du chat,
  8. can_promote_members — l'administrateur peut nommer de nouveaux administrateurs avec un sous-ensemble de ses propres privilèges, ou rétrograder des administrateurs qu'il a nommés directement ou indirectement (par exemple, des administrateurs nommés par lui)
  9. can_change_info — l'administrateur peut modifier le titre, la photo et d'autres paramètres du chat
  10. can_invite_users — l'administrateur peut inviter de nouveaux utilisateurs dans le chat
  11. can_pin_messages — l'administrateur peut épingler des messages (supergroupes uniquement).
Exemple

Exemple : Promouvoir un utilisateur en administrateur dans un supergroupe :

Dans cet exemple, en plus des autorisations spécifiées, l'autorisation can_manage_chat sera accordée par défaut.

Exemple de code à copier

Exemple 1. 
promote_options_list = '["can_promote_members","can_change_info","can_invite_users"]' 
tg_promote_user(platform_id, user_id, promote_options_list)

Exemple 2. 
promote_options_list = '["can_manage_chat","can_post_messages","can_edit_messages","can_delete_messages","can_manage_video_chats","can_promote_members","can_restrict_members","can_invite_users","can_pin_messages"]' 
result=tg_promote_user(platform_id, reply_from, promote_options_list)  

Comment modifier un titre d'administrateur à l'aide d'un bot dans Telegram

Description

tg_set_administrator_title(platform_id, user_id, title)

Définit un titre d'administrateur personnalisé pour un administrateur de supergroupe Telegram.

Paramètres

Paramètre Description
platform_id L'identifiant du supergroupe Telegram.
user_id L'identifiant Telegram de l'administrateur.
title Le titre d'administrateur personnalisé.

Important

  • Le titre doit comporter entre 0 et 16 caractères.
  • Les emojis ne sont pas autorisés dans le titre.
  • Cette fonction fonctionne uniquement pour les administrateurs promus par le bot.

Exemple

result = tg_set_administrator_title(platform_id, reply_from, "firetitle")

Restrictions générales pour les membres ordinaires du chat ou des utilisateurs Telegram spécifiques

Description

tg_chat_permission(platform_id, permission, media_permissions)

Définit les autorisations par défaut pour les membres d'un chat Telegram.

Paramètres

Paramètre Description
platform_id L'identifiant du chat Telegram.
permission Un tableau d'autorisations générales du chat. Chaque élément correspond à une autorisation dans la liste des autorisations prises en charge. Utilisez 1 pour autoriser l'action et 0 pour l'interdire.
media_permissions Un tableau d'autorisations liées aux médias. Chaque élément correspond à une autorisation dans la liste des autorisations médias prises en charge. Utilisez 1 pour autoriser l'action et 0 pour l'interdire.

Remarque

L'ordre des valeurs dans les deux tableaux doit correspondre à l'ordre des listes d'autorisations correspondantes. Chaque élément du tableau contrôle une autorisation spécifique :

  • 1 — L'autorisation est accordée.
  • 0 — L'autorisation est refusée.
Liste des restrictions pour le paramètre requis **permission**

Liste des restrictions pour permission:

  1. ! can_send_messages - autorisation d'envoyer des messages texte, des contacts, des lieux et des lieux.
  2. ! can_send_media_messages - autorisation d'envoyer de l'audio, des documents, des photos, des vidéos, des notes vidéo et des notes vocales. Nécessite can_send_messages
  3. ! can_send_polls - autorisation d'envoyer des sondages. Nécessite can_send_messages
  4. ! can_send_other_messages - autorisation d'envoyer des animations, des jeux, des autocollants et d'utiliser des bots inline. Nécessite can_send_media_messages
  5. ! can_add_web_page_previews - autorisation d'ajouter des aperçus de pages Web aux messages. Nécessite can_send_media_messages
  6. ! can_change_info - autorisation de modifier le titre, la photo et d'autres paramètres du chat. Ignoré dans les supergroupes publics.
  7. ! can_invite_users - autorisation d'inviter des utilisateurs
  8. ! can_pin_messages - autorisation d'épingler des messages. Ignoré dans les supergroupes publics.
  9. can_manage_topics - autorisation de créer des sujets dans les groupes de forum. Si utilisé dans un groupe de type incorrect, la fonction échouera et renverra une erreur.
Liste des valeurs pour le paramètre requis **media_permissions**

Valeurs pour accorder des autorisations liées aux médias media_permissions:

  1. can_send_audios - autorisation d'envoyer des fichiers audio
  2. can_send_documents - autorisation d'envoyer des documents
  3. can_send_photos - autorisation d'envoyer des photos
  4. can_send_videos - autorisation d'envoyer des vidéos
  5. can_send_video_notes - autorisation d'envoyer des messages vidéo ronds
  6. can_send_voice_notes - autorisation d'envoyer des messages vocaux

Restrictions personnelles Telegram pour les utilisateurs réguliers du chat ou pour des utilisateurs Telegram spécifiques

Description

tg_restrict_chat_member(platform_id, user_id, minutes, permission, media_permissions).

Paramètres :

Paramètre Description
! platform_id ID du chat dans Telegram *
! user_id ID de l'utilisateur dans Telegram *
minutes le nombre de minutes pendant lesquelles la restriction restera active. Si vous ne définissez pas de valeur, la valeur par défaut est 3600, ce qui équivaut à 60 heures. Si vous la définissez sur 0, la restriction devient permanente
permission un tableau de valeurs de la liste des restrictions d'autorisation.
media_permissions une liste de valeurs pour accorder des autorisations liées aux médias
Liste des restrictions pour le paramètre requis **permission**

Liste des restrictions pour permission:

  1. ! can_send_messages - autorisation d'envoyer des messages texte, des contacts, des lieux et des lieux.
  2. ! can_send_media_messages - autorisation d'envoyer de l'audio, des documents, des photos, des vidéos, des notes vidéo et des notes vocales. Nécessite can_send_messages
  3. ! can_send_polls - autorisation d'envoyer des sondages. Nécessite can_send_messages
  4. ! can_send_other_messages - autorisation d'envoyer des animations, des jeux, des autocollants et d'utiliser des bots inline. Nécessite can_send_media_messages
  5. ! can_add_web_page_previews - autorisation d'ajouter des aperçus de pages Web aux messages. Nécessite can_send_media_messages
  6. ! can_change_info - autorisation de modifier le titre, la photo et d'autres paramètres du chat. Ignoré dans les supergroupes publics.
  7. ! can_invite_users - autorisation d'inviter des utilisateurs
  8. ! can_pin_messages - autorisation d'épingler des messages. Ignoré dans les supergroupes publics.
  9. can_manage_topics - autorisation de créer des sujets dans les groupes de forum. Si utilisé dans un groupe de type incorrect, la fonction échouera et renverra une erreur.
Liste des valeurs pour le paramètre requis **media_permissions**

Valeurs pour accorder des autorisations liées aux médias media_permissions:

  1. can_send_audios - autorisation d'envoyer des fichiers audio
  2. can_send_documents - autorisation d'envoyer des documents
  3. can_send_photos - autorisation d'envoyer des photos
  4. can_send_videos - autorisation d'envoyer des vidéos
  5. can_send_video_notes - autorisation d'envoyer des messages vidéo ronds
  6. can_send_voice_notes - autorisation d'envoyer des messages vocaux
Exemple

Exemple d'utilisation de la fonction, où l'utilisateur est restreint de tout pendant 3 minutes :

Lorsque l'utilisateur entre dans le chat, il verra une notification indiquant qu'il ne peut pas envoyer de messages dans le chat.
Si une limite de temps est définie, il verra également la durée de cette restriction.

Exemple de code à copier :

permission = [0, 0, 0, 0, 0, 0, 0, 0] 
tg_restrict_chat_member(-1001607137668, 473737685, 3, permission)

Comment épingler un message

Description

tg_pin_chat_message(platform_id, message_id, disable_notification)

Épingle un message dans un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.
message_id L'ID du message à épingler.
disable_notification Contrôle si les membres du chat sont notifiés du message épinglé. Définissez sur 1 pour épingler le message silencieusement, ou 0 pour envoyer une notification.

Remarque

Les notifications sont toujours désactivées dans les canaux et les chats privés, quelle que soit la valeur de disable_notification.

Comment désépingler un message

Description

tg_unpin_chat_message(platform_id, message_id)

Désépingle un message dans un chat Telegram.

Paramètres

Paramètre Description
platform_id L'ID du chat Telegram.
message_id L'ID du message à désépingler. S'il est omis, le message le plus récemment épinglé est désépinglé.

Remarque

Si message_id n'est pas spécifié, la fonction désépingle le dernier message épinglé en fonction de son heure d'envoi.

Comment désépingler tous les messages épinglés

Description

tg_unpin_all(platform_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *

ATTENTION !

Telegram a une limitation pour les fonctions d'épingle/désépingle de message.

Les limites de temps pour l'utilisation de **tg_pin_chat_message / tg_unpin_chat_message / tg_unpin_all **ne sont PAS définies par le système MaviBot.

Si le temps autorisé pour épingler un message est dépassé, la fonction retournera toujours true, mais Telegram n'appliquera pas la modification.

Il est également important de noter que les messages épinglés peuvent rester dans le cache, donc ils peuvent ne pas disparaître visuellement immédiatement.

Comment créer un sondage dans Telegram

Description

tg_send_poll(platform_id, question, options, is_anonymous, allows_multiple_answers, reply_markup, disable_notification, protect_content, token, reply_to_message_id, message_thread_id, business_connection_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** question question
**!** options un tableau d'options de réponse
is_anonymous 1 - sondage anonyme , '' - non anonyme
allows_multiple_answers 1 - réponses multiples disponibles, '' - une seule réponse
reply_markup clavier ou '' - sans clavier
disable_notification indicateur pour l'envoi avec notification sonore (par défaut 0)
1 – désactiver la notification à la réception, 0 – envoyer avec notification
protect_content 1 pour protéger contre la copie et les captures d'écran, '' pas de protection
token jeton du bot ; s'il n'est pas fourni, le jeton actuel est utilisé
reply_to_message_id ID du message cité
message_thread_id ID du fil de discussion (disponible pour les supergroupes si la fonctionnalité de forum existe)
business_connection_id valeur lors de la connexion d'un bot (ID Business). S'affiche dans les canaux. Doit être fourni si le jeton du bot est utilisé et que le message doit être envoyé via un compte utilisateur connecté au bot
Important à savoir !

Remarques

  1. La fonction retourne une réponse de Telegram avec message_id. Il est préférable de la sauvegarder. En utilisant message_id, vous pouvez arrêter le sondage avec tg_stop_poll (voir description ci-dessous) et obtenir le résultat.

  2. Si un utilisateur ajoute un sondage dans un messager, un callback est envoyé au chat :

poll_added - partie immuable
YOUR QUESTION - texte de la question du sondage

Exemple de callback lors de l'ajout d'un sondage dans un canal

Exemple de callback lors de l'ajout d'un sondage dans un chat

Le deuxième callback après poll_added contient des chiffres - ce n'est rien d'autre que l'identifiant de l'utilisateur dans Telegram qui a ajouté le sondage.

Lors de la création d'un sondage par un bot, le callback n'arrive pas.

3. Dans un canal, vous ne pouvez créer que des sondages anonymes

Attention, il est recommandé d'envoyer uniquement des sondages anonymes dans un groupe !

  1. Après avoir créé le sondage, sauvegardez son identifiant dans une variable pour savoir à quel sondage le callback se rapporte.
Exemple

Les retours clients sont essentiels à notre croissance. Les sondages offrent une méthode simple pour capturer ces retours et les traduire en conclusions commerciales concrètes.

Exemple de code à copier :

/* Example of creating a simple poll */
options = ["white", "red", "blue", "green"]
poll1 = tg_send_poll(platform_id, 'What is your favorite color?', options, 1, '', '', 1, '')

Fonction de création d'un sondage dans Telegram :

Le sondage que nous avons créé dans Telegram

Comment créer un quiz dans Telegram

Description

tg_send_quiz_poll(platform_id, question, options, explanation, correct_option_id, is_anonymous, reply_markup, parse_mode, protect_content, disable_notification, token, reply_to_message_id, message_thread_id )

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** question question
**!** options un tableau d'options de réponse
**!** explanation texte affiché lorsqu'un utilisateur sélectionne une réponse incorrecte ou clique sur l'icône de la lampe dans un sondage de type quiz, 0–200 caractères avec pas plus de deux sauts de ligne après l'analyse des entités.
**!** correct_option_id numéro de la bonne réponse, numérotation à partir de 1
is_anonymous 1 - sondage anonyme , '' - non anonyme
reply_markup clavier ou '' - sans clavier
parse_mode format de l'explication : markdown, html, ou '' (chaîne vide pour aucun formatage)
protect_content 1 pour protéger contre la copie et les captures d'écran, '' pas de protection
disable_notification indicateur pour l'envoi avec notification sonore (par défaut 0)
1 – désactiver la notification à la réception, 0 – envoyer avec notification
token jeton du bot ; s'il n'est pas fourni, le jeton actuel est utilisé
reply_to_message_id ID du message cité
message_thread_id ID du sujet (disponible dans les supergroupes avec des fonctionnalités de forum actives)
**Important à savoir !**

Remarques

1. Sauvegardez le message_id

La fonction API retourne une réponse Telegram contenant un message_id. Sauvegardez toujours cet ID, car il est nécessaire pour :

  • Terminer le quiz à l'aide de la fonction tg_stop_poll (voir description ci-dessous).
  • Récupérer les résultats finaux.

2. Callback poll_added

Si un utilisateur ajoute un sondage à un canal, le bot reçoit un callback :

  • Format : poll_added + Question du sondage
  • Si ajouté à un chat de groupe : le callback inclut également l'ID utilisateur Telegram de la personne qui a ajouté le sondage.

Si créé par le bot : Aucun callback poll_added n'est envoyé.

3. Restriction du canal

Seuls les quiz anonymes peuvent être créés dans les canaux.

4. Callback poll_answer (Vote de l'utilisateur)

Lorsqu'un utilisateur vote dans un quiz envoyé à un chat privé ou à un groupe, un callback est envoyé au dialogue du bot avec ce client :

  • Format : poll_answer + ID du sondage + [Index de la réponse]
  • Exemple : poll_answer 5325838371359031648 [3]
  • Remarque : la numérotation des réponses commence à 0. [3] signifie que l'utilisateur a sélectionné la quatrième option de réponse.

5. Webhook pour les sondages de groupe non anonymes

Pour les sondages non anonymes dans les groupes où le bot est administrateur, un webhook est envoyé pour chaque vote. En le recevant, le bot transmettra le callback poll_answer (comme au point 4) à son dialogue avec le client correspondant.

6. Exigence d'activation et meilleure pratique

  • Exigence : un bot ne peut pas initier une conversation. Si un client n'a jamais contacté le bot, vous ne pouvez pas lui envoyer un message direct en réponse à son vote tant qu'il n'a pas activé le bot d'abord (par exemple, en envoyant une commande /start).

Recommandation : pour éviter cette limitation, il est fortement recommandé d'envoyer uniquement des quiz anonymes aux groupes.

7. Suivez vos sondages

Immédiatement après avoir créé un quiz, sauvegardez son ID de sondage unique dans une variable. Cela vous permet d'identifier à quel sondage spécifique un callback entrant se réfère.

Exemple

Exemple de code à copier.

options = ["white", "red", "blue", "green"] 
r = tg_send_quiz_poll(platform_id, "What color is a crocodile?", options, "That is the explanation", 4, '', '', '', '', 1)

Exemple : création d'un quiz.

Comment terminer un sondage

Description

tg_stop_poll(platform_id, message_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** message_id ID du message du sondage/quiz. Il peut être obtenu à partir du webhook

L'appel de cette fonction pour terminer un sondage/quiz retourne un dictionnaire contenant les résultats finaux.

Comment travailler avec les sujets dans Telegram

Important : le sujet principal du groupe n'a pas d'ID et nécessite des fonctions séparées pour travailler avec lui.

Comment renommer le sujet général d'un groupe

Description

tg_edit_general_forum_topic(platform_id, topic_name)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** topic_name nouveau nom du sujet
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Ceci est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple

Le sujet général du groupe peut être modifié à l'aide de la fonction tg_edit_general_forum_topic(). Elle nécessite deux paramètres obligatoires : l'ID du chat et le nouveau nom du sujet de groupe :

Exemple de code à copier

renommer le chat du sujet général/
answer = tg_edit_general_forum_topic(-1001839380031, 'General')

Comment fermer le sujet général

Description

tg_close_general_forum_topic(platform_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

/fermer le chat du sujet général/
answer = tg_close_general_forum_topic(-1001839380031)

Comment rouvrir un sujet général précédemment fermé

Description

tg_reopen_general_forum_topic(platform_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

/rouvrir le chat du sujet général/
answer = tg_reopen_general_forum_topic(-1001839380031)

Comment masquer le sujet général

Description

tg_hide_general_forum_topic(platform_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Le chat du sujet général peut être fermé pour les participants du sujet (ils peuvent lire mais pas écrire) et masqué de la liste des chats généraux de Telegram pour les nouveaux utilisateurs.

Exemple de code à copier

/masquer le chat du sujet général/
answer = tg_hide_general_forum_topic(-1001839380031)

Comment afficher le sujet général ou restaurer sa visibilité

Description

tg_unhide_general_forum_topic(platform_id)

Paramètres :

Paramètre Description
**!** platform_id ID du sujet dans Telegram *
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Important !

Cette fonction ne rouvre pas le sujet général ; elle le rend seulement visible.

Exemple de code à copier

/afficher le chat du sujet général/
answer = tg_unhide_general_forum_topic(-1001839380031)

Comment créer un nouveau sujet dans Telegram

Description

tg_create_forum_topic(platform_id, name, icon, icon_color)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** name nom du nouveau sujet
icon ID de l'emoji à définir pour le sujet. Transmis sous forme de chaîne. Vous ne pouvez utiliser que des emojis de la liste récupérée par la fonction tg_get_forum_icon.
icon_color couleur de l'emoji parmi la liste : 7322096, 16766590, 13338331, 9367192, 16749490, 16478047. Tous les emojis ne prennent pas en charge les changements de couleur.
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

La couleur définie ne peut pas être modifiée ; la couleur ne peut être attribuée que lors de la création du sujet.

Lors de l'exécution, la fonction renverra une réponse contenant les paramètres du nouveau sujet, y compris l'ID du sujet (nécessaire pour diverses fonctions).

Exemple de code à copier

Pour créer un chat de sujet supplémentaire
answer = tg_create_forum_topic(-1001839380031, 'second_bot_topic', None, 7322096)

Pour enregistrer l'ID du chat de sujet supplémentaire créé
answer={"ok":true,"result":{"message_thread_id":254,"name":"second_bot_topic","icon_color":7322096}}/
idtema1=answer['result']['message_thread_id']

Comment modifier un sujet. Comment renommer et/ou changer l'emoji d'un sujet

Description

tg_edit_forum_topic(platform_id, message_thread_id, name, icon)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** message_thread_id ID du chat de sujet supplémentaire
name nouveau nom du sujet
icon ID de l'emoji à définir pour le sujet. Transmis sous forme de chaîne. Vous ne pouvez utiliser que des emojis de la liste récupérée par la fonction tg_get_forum_icon.
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

answer = tg_edit_forum_topic(-1001839380031, 254)

Comment fermer un sujet sélectionné

Description

Fermer un sujet signifie le rendre en lecture seule ; l'écriture dans un sujet fermé n'est pas autorisée.

tg_close_forum_topic(platform_id, message_thread_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** message_thread_id ID du chat de sujet supplémentaire
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

answer = tg_close_forum_topic(-1001839380031, 254)

Comment rouvrir un sujet précédemment fermé

Description

tg_reopen_forum_topic(platform_id, message_thread_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** message_thread_id ID du chat de sujet supplémentaire
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

answer = tg_reopen_forum_topic(-1001839380031, 254)

Comment supprimer un sujet et tous ses messages

Description

tg_delete_forum_topic(platform_id, message_thread_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** message_thread_id ID du chat de sujet supplémentaire
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

answer = tg_delete_forum_topic(-1001839380031, 254)

Comment désépingler tous les messages dans un sujet

Description

tg_unpin_topic_messages(platform_id, message_thread_id)

Paramètres :

Paramètre Description
**!** platform_id ID du chat dans Telegram *
**!** message_thread_id ID du chat de sujet supplémentaire
bot_name

paramètre optionnel : nom du bot.

Lorsque vous travaillez avec des sujets, vous pouvez spécifier quel bot doit exécuter la fonction. Cela est utile si votre projet utilise plusieurs bots Telegram. Trouvez le nom du bot dans la section "Canaux", dans le champ "ID du groupe".

Exemple de code à copier

answer = tg_unpin_topic_messages(-1001839380031, 254)

Comment obtenir la liste des emojis pour un sujet Telegram

Description

Comment obtenir la liste des emojis

tg_get_forum_icon() – cette fonction renvoie une liste d'emojis disponibles pour être utilisés comme icônes de sujet de forum. Le résultat doit être assigné à une variable, car elle renvoie un dictionnaire où chaque clé est un emoji et sa valeur correspondante est l'identifiant unique (id) de l'emoji.

Paramètres : aucun.

Le contenu de la liste d'emojis

Pour obtenir la liste des emojis pour un chat de sujet, envoyez la commande au chat concerné.

La fonction renverra la liste d'emojis dans sa réponse. Cela signifie que la variable answer contiendra un dictionnaire comme valeur.

{'📰': '5434144690511290129', '💡': '5312536423851630001', '⚡️': '5312016608254762256', '🎙': '5377544228505134960', '🔝': '5418085807791545980', '🗣': '5368697802761185083', '🆒': '5420216386448270341', '❗️': '5379748062124056162', '📝': '5357193964787081133', '📆': '5433614043006903194', '📁': '5357315181649076022', '🔎': '5309965701241379366', '📣': '5309984423003823246', '🔥': '5312241539987020022', '❤️': '5312138559556164615', '❓': '5377316857231450742', '📈': '5350305691942788490', '📉': '5350713563512052787', '💎': '5309958691854754293', '💰': '5350452584119279096', '💸': '5309929258443874898', '\U0001fa99': '5377690785674175481', '💱': '5310107765874632305', '⁉️': '5377438129928020693', '🎮': '5309950797704865693', '💻': '5350554349074391003', '📱': '5409357944619802453', '🚗': '5312322066328853156', '🏠': '5312486108309757006', '💘': '5310029292527164639', '🎉': '5310228579009699834', '‼️': '5377498341074542641', '🏆': '5312315739842026755', '🏁': '5408906741125490282', '🎬': '5368653135101310687', '🎵': '5310045076531978942', '🔞': '5420331611830886484', '📚': '5350481781306958339', '👑': '5357107601584693888', '⚽️': '5375159220280762629', '🏀': '5384327463629233871', '📺': '5350513667144163474', '👀': '5357121491508928442', '\U0001fae6': '5357185426392096577', '🍓': '5310157398516703416', '💄': '5310262535021142850', '👠': '5368741306484925109', '✈️': '5348436127038579546', '\U0001f9f3': '5357120306097956843', '🏖': '5310303848311562896', '⛅️': '5350424168615649565', '🦄': '5413625003218313783', '🛍': '5350699789551935589', '👜': '5377478880577724584', '🛒': '5431492767249342908', '🚂': '5350497316203668441', '🛥': '5350422527938141909', '🏔': '5418196338774907917', '🏕': '5350648297189023928', '🤖': '5309832892262654231', '\U0001faa9': '5350751634102166060', '🎟': '5377624166436445368', '🏴\u200d☠️': '5386395194029515402', '🗳': '5350387571199319521', '🎓': '5357419403325481346', '🔭': '5368585403467048206', '🔬': '5377580546748588396', '🎶': '5377317729109811382', '🎤': '5382003830487523366', '🕺': '5357298525765902091', '💃': '5357370526597653193', '\U0001fa96': '5357188789351490453', '💼': '5348227245599105972', '\U0001f9ea': '5411138633765757782', '👨\u200d👩\u200d👧\u200d👦': '5386435923204382258', '👶': '5377675010259297233', '🤰': '5386609083400856174', '💅': '5368808634392257474', '🏛': '5350548830041415279', '\U0001f9ee': '5355127101970194557', '🖨': '5386379624773066504', '👮\u200d♂️': '5377494501373780436', '\U0001fa7a': '5350307998340226571', '💊': '5310094636159607472', '💉': '5310139157790596888', '\U0001f9fc': '5377468357907849200', '\U0001faaa': '5418115271267197333', '🛃': '5370947704199323325', '🍽': '5350344462612570293', '🐟': '5384574037701696503', '🎨': '5310039132297242441', '🎭': '5350658016700013471', '🎩': '5357504778685392027', '🔮': '5350367161514732241', '🍹': '5350520238444126134', '🎂': '5310132165583840589', '☕️': '5350392020785437399', '🍣': '5350406176997646350', '🍔': '5350403544182694064', '🍕': '5350444672789519765', '\U0001f9a0': '5312424913615723286', '💬': '5417915203100613993', '🎄': '5312054580060625569', '🎃': '5309744892677727325'}

Exemple de code pour copie
answer = tg_get_forum_icon()