Un widget est un composant interactif intégré directement dans un message de bot : un code promo avec un bouton de copie, un compte à rebours, un suivi de statut de commande, un quiz ou un calendrier pour sélectionner une date et une heure. Lorsqu'un client interagit avec un widget, le bot met à jour le même message sur place — sans envoyer de nouveaux messages ni afficher de mention « modifié ».

Il existe deux façons d'envoyer un widget :

• Modèle prêt à l'emploi — une seule ligne dans le Calculateur. La mise en page et les fonctionnalités sont déjà implémentées.
• Widget personnalisé — écrivez votre propre code HTML (ou demandez à Mavi de le créer) et traitez les interactions à l'aide des blocs de flux du bot.

Où les widgets fonctionnent

Messagerie	Telegram uniquement
Type de chat	Uniquement les conversations privées entre un client et un bot
Non pris en charge	Groupes, chaînes, Telegram Business
Application Telegram	Nécessite une version récente de Telegram. Les versions plus anciennes affichent un avis « Message non pris en charge » et la légende
Transfert	Les widgets ne peuvent pas être transférés ou copiés

Les widgets ne prennent pas en charge les champs de saisie de texte ni les claviers. Les clients ne peuvent interagir qu'en appuyant. Si vous avez besoin que les clients saisissent du texte, utilisez une question de bot classique ou une Web App.

Les widgets ne sont pas affichés dans la fenêtre de test du bot dans le tableau de bord, car ce n'est pas Telegram. Testez les widgets directement dans Telegram en envoyant un message à votre bot.

---

Modèles prêts à l'emploi

Tous les modèles sont envoyés à l'aide d'une seule fonction :

tg_send_widget(platform_id, template, params, caption)

Paramètre	Description
platform_id	ID du destinataire. Pour le client actuel, utilisez la variable platform_id
template	Nom du modèle : promo, timer, order_status, faq, quiz, calendar
params	Dictionnaire contenant les paramètres du modèle
caption	Texte affiché sous le widget. Les clients le voient également dans leur liste de discussions, les notifications et les versions plus anciennes de Telegram, il doit donc être significatif en soi

La fonction renvoie la réponse de l'API Telegram. L'ID du message envoyé est disponible dans response['result']['message_id']. Enregistrez-le si vous prévoyez de mettre à jour le widget plus tard.

Si la fonction renvoie du texte au lieu d'une réponse Telegram, une erreur s'est produite : modèle inconnu, paramètre invalide ou manquant, ou widget dépassant la limite de taille. Le texte de l'erreur explique ce qui n'a pas fonctionné.

Comment construire les paramètres

Créez un dictionnaire et assignez chaque paramètre sur une ligne séparée :

p = {}
p["code"] = "WIDGET10"
p["title"] = "Votre code promo"
p["note"] = "10% de réduction sur toute commande"
w = tg_send_widget(platform_id, "promo", p, "Votre code promo WIDGET10 — 10% de réduction")

Saisissez le code dans le champ Calculateur du bloc. La capture d'écran montre un bloc Condition de démarrage qui envoie un widget de statut de commande lorsque le client envoie la phrase « widget de commande ».

Dans le bloc qui envoie le widget, vous définirez généralement le champ de réponse sur #{none}. Le bloc n'envoie pas de message texte séparé car la légende du widget sert de texte du message.

Langue

Les modèles incluent un texte d'interface intégré, tel que les libellés des boutons, les noms des mois et des jours de la semaine, « Temps écoulé » et d'autres messages.

La langue par défaut dans Mavibot est l'anglais (en).

Pour utiliser une autre langue, spécifiez le paramètre lang :

p["lang"] = "fr"

Langues prises en charge :

ru, en, de, es, fr, pt, tr, uk, kk, ms, th, ar.

Les textes que vous fournissez vous-même — titres, questions, étapes et légendes — sont affichés exactement tels qu'ils sont saisis et ne sont pas automatiquement traduits.

---

Code promo — promo

Affiche un code promo avec un bouton qui le copie en un seul appui.

Paramètre	Description
code	Code promo. Requis
title	Texte affiché au-dessus du code
note	Texte affiché sous le code, comme une date d'expiration
button	Libellé du bouton. Par défaut : « Copier le code promo »
used_text	Texte affiché lorsque le code est marqué comme utilisé

p = {}
p["code"] = "WIDGET10"
p["title"] = "Votre code promo"
p["note"] = "10% de réduction sur toute commande"
p["button"] = "Copier le code"
w = tg_send_widget(platform_id, "promo", p, "Votre code promo WIDGET10 — 10% de réduction")
client.promo_widget_id = w['result']['message_id']

Pour marquer le code comme utilisé, ce qui le barre et supprime le bouton :

p = {}
p["used"] = 1
t = tg_edit_widget_data(platform_id, client.promo_widget_id, p)

---

Compte à rebours — timer

Affiche un compte à rebours jusqu'à une date et une heure spécifiées.

Le compte à rebours s'exécute sur l'appareil du client. Le bot n'est pas impliqué dans la mise à jour du minuteur.

Paramètre	Description
until	Date et heure cibles au format "JJ.MM.AAAA HH:MM", en utilisant le fuseau horaire du projet
seconds	Alternativement, le nombre de secondes à partir du moment où le widget est envoyé
title	Titre du minuteur. Par défaut : « L'offre se termine dans »
done	Texte affiché lorsque le compte à rebours se termine
text	Texte affiché sous le compte à rebours
button, url	Libellé du bouton et URL de destination (https:// uniquement)
hide_button	Définir sur 1 pour masquer le bouton lorsque le compte à rebours se termine

Vous devez fournir soit until, soit seconds.

p = {}
p["seconds"] = 7200
p["title"] = "L'offre se termine dans"
p["button"] = "Visiter le site web"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "L'offre se termine dans 2 heures")

Lorsque le compte à rebours atteint zéro, aucun message ni rappel n'est envoyé au bot. Si le bot doit effectuer une action à l'expiration de l'offre, utilisez une connexion de minuteur classique dans le flux du bot.

---

Statut de commande — order_status

Affiche une liste des étapes de la commande avec l'étape actuelle mise en évidence.

Le bot peut mettre à jour l'étape sur place, de sorte que le client voit toujours le même message.

Paramètre	Description
title	Titre du widget
steps	Liste des étapes, de 1 à 12. Par défaut : acceptée, en préparation, remise au coursier, en route, livrée
step	Numéro de l'étape actuelle, à partir de 1
text	Texte affiché sous les étapes

Envoi du widget :

p = {}
p["title"] = "Statut de la commande"
p["steps"] = ["Acceptée", "En préparation", "Livrée"]
p["step"] = 1
p["text"] = "Votre commande a été acceptée et est en cours de préparation"
w = tg_send_widget(platform_id, "order_status", p, "Votre commande")
client.order_widget_id = w['result']['message_id']

Passez à l'étape suivante depuis n'importe quel autre bloc, par exemple lorsqu'une étape de transaction change, qu'un gestionnaire envoie une commande ou qu'un minuteur se déclenche :

p = {}
p["step"] = 2
p["text"] = "Votre commande est en préparation et sera bientôt remise au coursier"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

La légende sous le widget ne change pas lorsque l'étape est mise à jour. Utilisez une légende neutre comme « Votre commande » au lieu de « Statut : Acceptée ».

---

Foire aux questions — faq

Affiche une liste de questions. Les clients peuvent appuyer sur une question pour développer sa réponse.

Paramètre	Description
title	Titre du widget
items	Liste de paires question-réponse. Requis

p = {}
p["title"] = "Foire aux questions"
p["items"] = [["Comment puis-je payer ?", "Vous pouvez payer par carte. Un lien de paiement sera envoyé dans cette discussion."], ["Combien de temps prend la livraison ?", "La livraison prend généralement 1 à 2 jours en local et 3 à 7 jours à l'échelle nationale."], ["Puis-je retourner un article ?", "Oui, dans les 14 jours."]]
w = tg_send_widget(platform_id, "faq", p, "Réponses aux questions fréquemment posées")

Le texte est affiché en texte brut. Les balises HTML et autres balises de formatage ne sont pas traitées.

---

Quiz et sondage — quiz

Affiche des questions avec des réponses à choix multiples, une question à la fois.

Si des réponses correctes sont spécifiées, le widget agit comme un quiz et calcule un score. Sans réponses correctes, il fonctionne comme un sondage.

Paramètre	Description
title	Titre affiché au-dessus des questions
questions	Liste des questions. Requis
retry	Définir sur 1 pour afficher un bouton « Réessayer » à la fin
callback	Texte de rappel personnalisé au lieu de widget_quiz_finished

Chaque question est un dictionnaire contenant :

• q — texte de la question
• options — options de réponse
• correct — réponse correcte, spécifiée par son index basé sur 1 ou son texte exact

p = {}
p["title"] = "Quiz : Testez vos connaissances"
p["retry"] = 1
p["questions"] = [{"q": "Combien font 2 + 2 ?", "options": ["3", "4", "5"], "correct": 2}, {"q": "Quelle est la capitale de la France ?", "options": ["Londres", "Paris", "Berlin"], "correct": "Paris"}]
w = tg_send_widget(platform_id, "quiz", p, "Faites ce quiz de deux questions !")

Pour créer un sondage sans notation, omettez correct dans chaque question.

Les réponses correctes sont vérifiées par la plateforme et ne sont pas envoyées sur l'appareil du client.

Ce que reçoit le flux du bot

Les réponses individuelles aux questions ne sont pas envoyées à la conversation.

Lorsque le client répond à la dernière question, le bot reçoit le rappel widget_quiz_finished et les variables suivantes sont remplies :

Variable	Valeur
widget_quiz_score	Nombre de réponses correctes ; vide pour les sondages
widget_quiz_total	Nombre total de questions
widget_quiz_answers	Indices des options sélectionnées, par exemple [2,2]

Pour traiter le résultat, créez une connexion à partir du bloc qui a envoyé le quiz ou utilisez un bloc Condition de démarrage avec la condition widget_quiz_finished.

Exemple de réponse :

Votre résultat : #{widget_quiz_score} sur #{widget_quiz_total} bonnes réponses

---

Calendrier — calendar

Affiche un calendrier mensuel où les clients peuvent sélectionner une date puis un créneau horaire.

Il remplace plusieurs pages de boutons de date et d'heure, y compris la navigation « Retour » et « Suivant ».

Le calendrier prend en charge trois modes.

Dates et heures personnalisées

Les heures disponibles sont toujours transmises via le paramètre slots.

Mêmes créneaux horaires chaque jour — fournissez une liste d'heures et une plage de dates :

p = {}
p["title"] = "Sélectionnez une date et une heure"
p["name"] = "Consultation"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Choisissez une date et une heure")

Créneaux horaires différents pour des dates spécifiques — fournissez un dictionnaire mappant les dates aux listes d'heures. Les dates disponibles sont extraites des clés du dictionnaire :

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Choisissez une date et une heure")

Paramètre	Description
slots	Heures disponibles, sous forme de liste ou de dictionnaire groupé par date
days	Nombre de jours disponibles à partir d'aujourd'hui
date_from, date_to	Alternativement, les limites de la plage de dates au format "JJ.MM.AAAA"
dates	Alternativement, une liste de dates spécifiques
weekdays_off	Jours de la semaine indisponibles : 1 = lundi à 7 = dimanche
title	Indice affiché sous la grille du calendrier
name	Nom de l'article ou du service réservé ; affiché après la sélection
change	Définir sur 1 pour afficher un bouton « Choisir une autre heure » après la sélection
callback	Texte de rappel personnalisé au lieu de widget_calendar_selected

Date uniquement

Ne transmettez pas slots si le client n'a besoin que de sélectionner une date.

p = {}
p["days"] = 45
p["weekdays_off"] = [7]
w = tg_send_widget(platform_id, "calendar", p, "Choose a date")

Réservation en ligne

Fournissez une succursale et un service, et le calendrier récupérera automatiquement les dates et créneaux horaires disponibles à partir du module Services.

cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
w = tg_send_widget(platform_id, "calendar", cal, serv_title)

Paramètre	Description
company_id	Identifiant de la succursale
service_ids	Service ou liste de services
employee_id	Identifiant de l'employé ; s'il est omis, tout employé disponible est utilisé
days_limit	Nombre de jours à l'avance pour rechercher la disponibilité. Par défaut : 14
people_count	Nombre de places requises pour un service de groupe
auto_booking	Définir sur 1 pour laisser la plateforme créer la réservation automatiquement

Ces paramètres sont les mêmes que ceux utilisés par get_dates_for_booking et get_slots_for_booking.

Ce que reçoit le flux du bot

Les sélections de dates individuelles ne sont pas envoyées à la conversation.

Lorsque le client sélectionne un créneau horaire, ou une date si le calendrier n'a pas de créneaux horaires, le bot reçoit le callback widget_calendar_selected et les variables suivantes sont remplies :

Variable	Valeur
widget_date	Date sélectionnée au format DD.MM.YYYY
widget_time	Heure sélectionnée au format HH:MM ; vide pour les calendriers date uniquement
widget_message_id	ID du message contenant le widget

Les formats de date et d'heure sont les mêmes que ceux acceptés par create_booking et modify_booking_time.

---

Réservation en ligne avec un calendrier : exemple complet

Le widget gère la sélection de la date, les créneaux horaires et la navigation, réduisant ainsi le nombre de blocs de bot requis.

Bloc 1. Sélection du service

Utilisez un bloc Condition de démarrage avec la condition « prendre rendez-vous ».

Réponse : « Choisissez un service : »

Définissez le champ des boutons sur #{srv_buttons}.

comp_id = 8
srv_data = get_services_for_booking(comp_id)
srv_kb = tools_make_button_str_checker(srv_data, 'title', 1)
srv_buttons = srv_kb['buttons']
srv_checker = srv_kb['checker']

Bloc 2. Calendrier

Réponse : #{none}.

Connectez le Bloc 1 au Bloc 2 en utilisant la condition #{srv_checker}.

serv_id = tools_check_user_input(srv_data, question, 'title', 'id')
serv_title = tools_check_user_input(srv_data, question, 'title', 'title')
cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
cal_sent = tg_send_widget(platform_id, "calendar", cal, serv_title)

Bloc 3. Créer la réservation

Réponse : #{none}.

Connectez le Bloc 2 au Bloc 3 en utilisant la condition widget_calendar_selected avec Correspondance exacte.

booking_date = widget_date
booking_time = widget_time
booking_result = create_booking(comp_id, serv_id, booking_date, booking_time, '')
booking_ok = booking_result['status']

Bloc 4. Réservation confirmée

Connectez le Bloc 3 au Bloc 4 en utilisant la condition de variable booking_ok == True avec un délai d'une seconde.

Réponse :

Votre rendez-vous est confirmé : #{serv_title}, #{booking_date} à #{booking_time}. À bientôt !

Bloc 5. Créneau horaire plus disponible

Réponse : #{none}.

Connectez le Bloc 3 au Bloc 5 en utilisant la condition de variable booking_ok != True avec un délai d'une seconde.

Ce bloc réinitialise le calendrier existant, permettant au client de sélectionner une autre heure et affichant un message d'erreur.

fix = {}
fix["reset"] = 1
fix["error"] = "Ce créneau horaire vient d'être réservé. Veuillez en choisir un autre."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

Ajoutez une autre connexion du Bloc 5 au Bloc 3 avec la condition widget_calendar_selected.

Le client peut maintenant sélectionner une autre heure dans le même calendrier.

Option plus simple : réservation automatique

Ajoutez le paramètre suivant aux paramètres du calendrier :

cal["auto_booking"] = 1

La plateforme créera la réservation immédiatement lorsque le client sélectionnera une heure.

Si le créneau horaire sélectionné devient indisponible, le widget affiche une erreur directement.

Le callback widget_calendar_selected n'est envoyé qu'après une réservation réussie, avec la variable widget_booking_id.

Avec cette approche, les Blocs 3 et 5 ne sont pas nécessaires.

Utilisez la réservation via le flux du bot (la première approche) si vous avez besoin d'un prépaiement ou de vérifications personnalisées avant de confirmer un rendez-vous.

---

Mise à jour d'un widget envoyé

Utilisez la fonction suivante pour mettre à jour les données du widget :

tg_edit_widget_data(platform_id, message_id, data)

Paramètre	Description
message_id	ID du message du widget, enregistré lors de son envoi ou obtenu à partir de widget_message_id après une interaction
data	Dictionnaire contenant les nouvelles valeurs

Seules les données du widget peuvent être mises à jour. Vous ne pouvez pas modifier la mise en page d'un widget déjà envoyé. Pour utiliser une mise en page différente, envoyez un nouveau widget.

Comment les mises à jour sont appliquées :

• Code promo, minuteur, statut de commande, FAQ : les nouvelles données remplacent complètement la mise à jour précédente. Les champs manquants reviennent aux valeurs d'origine fournies lors de l'envoi du widget. Par conséquent, incluez chaque champ qui doit différer des données initiales, comme step et text.
• Quiz et calendrier : les nouvelles données sont appliquées en plus de l'état actuel du widget.

Paramètres de mise à jour spéciaux :

Modèle	Données	Résultat
promo	{"used": 1}	Marque le code promo comme utilisé
timer	{"seconds": 600} ou {"until": "…"}	Redémarre le compte à rebours
calendar	{"reset": 1, "error": "message"}	Efface la sélection, rouvre le calendrier et affiche un message

---

Widgets personnalisés

Lorsque les modèles prêts à l'emploi ne suffisent pas — par exemple, si vous avez besoin d'un catalogue de produits avec un panier, d'une évaluation par étoiles ou d'un calculateur de prix — vous pouvez créer un widget HTML personnalisé.

Comment cela fonctionne

1. Créez un widget sous forme de fichier HTML unique contenant ses styles et son JavaScript.
2. Enregistrez le code sous forme de fichier .txt dans la section Fichiers du projet et copiez l'URL du fichier. Le système de stockage n'accepte pas les fichiers .html.
3. Un bloc de bot envoie le widget en utilisant l'URL et transmet ses données initiales.
4. Lorsqu'un client interagit avec le widget, le bot reçoit un callback contenant le texte défini dans le code du widget.
5. Un bloc de gestionnaire calcule les nouvelles données et les renvoie au widget, qui met à jour sa propre interface.

Envoi d'un widget personnalisé

tg_send_widget_file(platform_id, url, data, caption)

Exemple :

st = {}
st["rating"] = 0
w = tg_send_widget_file(platform_id, "https://files.mavibot.ai/…/rating.txt", st, "Évaluez votre commande — appuyez sur une étoile")

Le paramètre data est un dictionnaire contenant l'état initial utilisé pour rendre le widget.

Gestion des interactions

Lorsqu'un client interagit avec un widget personnalisé, le bot reçoit un callback.

Les variables suivantes sont également remplies :

Variable	Valeur
widget_data	Texte de la requête envoyé par le widget, par exemple rate:4
widget_message_id	ID du message où l'interaction a eu lieu
widget_query_id	Identifiant de la requête

Créez le gestionnaire à l'aide d'un bloc Déclencheur et activez le paramètre Déclencheur uniquement sur callback.

La condition doit correspondre au texte de la requête du widget.

Ce type de bloc fonctionne indépendamment de la position actuelle du client dans le flux du bot et ne le déplace pas de son étape actuelle.

Important : N'utilisez pas un bloc Condition de démarrage pour gérer les interactions de widgets personnalisés. Un widget reste dans la conversation et le client peut interagir avec lui à tout moment — même en remplissant un questionnaire, en réservant un rendez-vous ou en effectuant un paiement. Un bloc Condition de démarrage redirigerait le client vers le gestionnaire et interromprait son étape actuelle.

Exemple de gestionnaire d'évaluation :

Condition (expression régulière) :

^rate:[1-5]$

Calculatrice :

local a = splitter(widget_data, ":")
client.widget_rating = a[1]
st = {}
st["rating"] = client.widget_rating
t = tg_edit_widget_data(platform_id, widget_message_id, st)

Les données du widget personnalisé sont entièrement remplacées lors des mises à jour. Envoyez toujours l'état complet plutôt que seulement le champ modifié.

La limite de taille des données est de 1024 octets.

Conservez les grands ensembles de données statiques (tels que les catalogues de produits) dans le code du widget et envoyez uniquement les valeurs qui changent via les données du widget.

Répondre à une requête de widget

Par défaut, le widget reçoit immédiatement une réponse vide et les données mises à jour arrivent via une mise à jour de widget séparée.

Si le widget doit recevoir des données directement en réponse à sa requête, le texte de la requête doit commencer par ?, par exemple :

?price

Dans ce cas, le bloc de gestionnaire doit appeler la fonction suivante dans les 15 secondes :

tg_answer_widget_query(data)

Sinon, le widget affiche une erreur de délai d'attente.

La limite de taille de la réponse est de 1024 octets.

Exigences de code

• Fichier unique : incluez les styles dans <style> et le JavaScript dans <script>. Les scripts externes, feuilles de style, polices et images ne peuvent pas être chargés. Les images doivent être intégrées à l'aide d'URL data: ou SVG.
• Limites de taille : maximum 32 Ko avant compression et 4 Ko après compression.
• Aucun champ de saisie : les éléments input, select, textarea et form sont supprimés. Seuls les éléments <button> sont pris en charge comme contrôles interactifs.
• Aucune requête réseau : fetch et les API similaires ne fonctionnent pas. Le seul moyen de communiquer avec le bot est via TelegramWidget.request("text"), avec une taille de requête de 1 à 64 octets.
• Aucun défilement interne : la hauteur maximale du widget est de 600 pixels. Tout ce qui dépasse est coupé. Pour créer un carrousel, déplacez une rangée de cartes plutôt que d'utiliser le défilement.
• Accès aux éléments : utilisez document.getElementById. L'accès aux éléments en tant que variables globales basées sur leurs ID ne fonctionne pas.
• Thème Telegram : utilisez les variables de thème Telegram telles que var(--tg-theme-text-color) pour que le widget soit correct dans les thèmes clair et sombre.
• Données du widget : lisez les données à partir de TelegramWidget.chatData et redessinez le widget lorsque l'événement chatDataChanged se produit.
• Requêtes : appelez request directement dans un gestionnaire d'interaction utilisateur. Une seule requête est autorisée par interaction.

Le widget n'affiche pas les erreurs de codage. Les éléments non pris en charge sont silencieusement supprimés, et une erreur JavaScript peut entraîner un widget vide. Testez toujours le widget dans Telegram après avoir effectué des modifications.

Exemple minimal de widget personnalisé

L'exemple ci-dessous affiche un produit, un bouton qui envoie une requête au bot et un compteur de panier basé sur les données du widget.

<style>
body{margin:0;padding:14px}
.h{color:var(--tg-theme-hint-color);font-size:.85em}
button{width:100%;margin-top:8px}
</style>

<b>Margherita · 10 $</b>
<div class="h" id="c"></div>
<button id="add">Ajouter au panier</button>
<div class="h" id="e"></div>

<script>
var W=window.TelegramWidget,$=function(i){return document.getElementById(i)},busy=0;

function draw(){
  var s={};
  try{s=JSON.parse(W.chatData)||{}}catch(e){}
  $('c').textContent='Dans le panier : '+(s.count||0)
}

$('add').onclick=function(){
  if(busy)return;
  busy=1;
  $('e').textContent='';
  W.request('cart_add').then(
    function(){busy=0},
    function(x){
      busy=0;
      $('e').textContent='Erreur : '+x.code
    }
  )
};

W.onEvent('chatDataChanged',draw);
draw();
</script>

---

Mavi et widgets

Mavi peut créer des flux de bot complets avec des widgets automatiquement.

Décrivez simplement ce dont vous avez besoin en langage naturel.

Par exemple :

• « Lorsque le client envoie 'commande', affichez un widget de statut de commande avec trois étapes. Lorsqu'il envoie 'prêt', déplacez la commande à la deuxième étape. »
• « Créez un flux de réservation de service : les clients choisissent un service à l'aide de boutons, puis sélectionnent une date et une heure à l'aide d'un widget calendrier. »
• « Créez un widget d'évaluation par étoiles pour les commandes et enregistrez la note sélectionnée dans une variable client. »

Mavi configure automatiquement des modèles prêts à l'emploi.

Pour les widgets personnalisés, Mavi écrit et vérifie le code, enregistre le fichier du widget dans le projet et crée les blocs nécessaires pour envoyer le widget et gérer les interactions client.

---

Référence

Fonctions

Fonction	Description
tg_send_widget(platform_id, template, params, caption)	Envoie un modèle de widget prêt à l'emploi
tg_send_widget_file(platform_id, url, data, caption)	Envoie un widget personnalisé à partir d'un fichier
tg_edit_widget_data(platform_id, message_id, data)	Met à jour les données d'un widget existant
tg_answer_widget_query(data)	Répond à une requête de widget personnalisé commençant par ?

Callbacks et variables

Événement	Callback	Variables
Quiz terminé	widget_quiz_finished	widget_quiz_score, widget_quiz_total, widget_quiz_answers
Date et heure sélectionnées dans le calendrier	widget_calendar_selected	widget_date, widget_time ; également widget_booking_id lorsque auto_booking est activé
Interaction avec un widget personnalisé	Texte de requête défini dans le code du widget	widget_data, widget_message_id, widget_query_id

Si votre bot contient plusieurs quiz ou calendriers, attribuez un callback unique à chaque widget à l'aide du paramètre callback afin de pouvoir les distinguer dans les conditions de votre flux de bot.

Limitations

• Les widgets fonctionnent uniquement dans les discussions privées Telegram entre un client et un bot.
• Seuls les cinq quiz et calendriers les plus récents sont conservés pour chaque client. Les plus anciens cessent de répondre aux interactions.
• Effacer toutes les variables client dans un flux de bot désactive les quiz et calendriers précédemment envoyés.
• Les données des widgets sont limitées à 1024 octets.
• Les requêtes des widgets personnalisés sont limitées à 64 octets.
• Les requêtes de widgets personnalisés nécessitant tg_answer_widget_query doivent recevoir une réponse dans les 15 secondes.

Dépannage

Problème	Cause / Solution
Le widget n'est pas envoyé et la variable contient Unknown parameter…	Le modèle a reçu un paramètre non pris en charge. Le message d'erreur répertorie les paramètres autorisés
Le calendrier s'arrête après la sélection de la date sans afficher les créneaux horaires	Le paramètre slots n'a pas été fourni
Après une interaction avec un widget, le bot cesse de répondre aux boutons de l'étape en cours	Le gestionnaire d'interaction utilise un bloc de condition de départ. Remplacez-le par un bloc non-état avec condition
Le widget personnalisé apparaît vide	Il y a une erreur dans le code du widget. Une cause courante est l'accès à un élément par son ID sans utiliser document.getElementById
Telegram affiche « Unsupported message »	Le client utilise une version obsolète de Telegram
Bad Request: chat not found	Le widget a été envoyé en dehors de Telegram, par exemple depuis la fenêtre de test du bot