Trabajar con IDs de plataforma en MaviBot

En MaviBot, todas las entidades de Telegram (usuarios, grupos, canales) se identifican mediante una variable genérica platform_id. Esta variable no distingue entre tipos de entidad.

Problema: Para usar funciones como accept o reject que requieren tipos de entidad específicos, necesitas conocer tanto el ID del chat como el ID del usuario por separado.

Solución: Cuando recibas un callback o mensaje, almacena inmediatamente el valor de platform_id en dos variables distintas con nombres descriptivos:

  • chat_id – para almacenar el ID del grupo/canal.
  • user_id – para almacenar el ID del usuario individual.

Esto te permite hacer referencia al ID correcto más adelante en la lógica de tu aplicación.

Cómo cambiar el nombre del chat mediante el bot de Telegram

Descripción

tg_set_group_title(platform_id, title)

Cambia el título de un grupo de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat dentro de Telegram.
title Nuevo nombre del chat.
Parámetro Descripción
**!** platform_id el ID del chat dentro de Telegram *
**!** title nuevo nombre del chat

Cómo cambiar la descripción del chat mediante el bot de Telegram

Descripción

tg_set_chat_description(platform_id, description)

Cambia la descripción de un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat dentro de Telegram.
description Nueva descripción del chat.
Parámetro Descripción
**!** platform_id el ID del chat dentro de Telegram *
**!** description nuevo nombre del chat

Cómo establecer un avatar en un grupo/chat de Telegram

Descripción

tg_set_chat_photo(platform_id, photo)

Establece una nueva foto de perfil para un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat dentro de Telegram donde deseas establecer una nueva foto de perfil.
photo Enlace directo a la foto.
Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *, en el que deseas establecer un avatar
**!** photo enlace de la foto

Cómo eliminar un avatar en un grupo/chat de Telegram

Descripción

tg_delete_chat_photo(platform_id)

Elimina la foto de perfil actual de un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat dentro de Telegram del cual deseas eliminar la foto de perfil.
Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *, en el que necesitas establecer un avatar

Cómo bloquear un grupo de Telegram

Descripción

tg_ban_chat_sender_chat(platform_id, sender_chat_id)

Bloquea un chat remitente para que no publique mensajes en un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram donde se bloqueará el chat remitente.
sender_chat_id El ID del chat remitente a bloquear.

Nota

Una vez bloqueado, el propietario del chat remitente ya no podrá publicar mensajes en nombre de ese chat en el chat de Telegram especificado hasta que se elimine el bloqueo.

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *, que necesitas bloquear
**!** sender_chat_id ID del chat que va a ser bloqueado

Al mismo tiempo, el propietario del chat bloqueado no puede escribir en nombre de sus otros chats hasta que sea bloqueado.

Cómo desbloquear un grupo de Telegram

Descripción

tg_unban_chat_sender_chat(platform_id, sender_chat_id)

Desbloquea un chat remitente previamente bloqueado en un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram donde se desbloqueará el chat remitente.
sender_chat_id El ID del chat remitente a desbloquear.
Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *, en el que desbloqueas
**!** sender_chat_id ID del chat que desbloqueas

Cómo crear un enlace de invitación para unirse a un chat de Telegram

Descripción

Crea un nuevo enlace de invitación para un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
member_limit Número máximo de usuarios que pueden unirse usando este enlace de invitación.
hours Tiempo de expiración del enlace de invitación, en horas.
request Si se establece en True, los usuarios que hagan clic en el enlace deben enviar una solicitud de unión que un administrador pueda aprobar.
name Nombre personalizado para el enlace de invitación.

Importante

Si se especifica el parámetro member_limit, el parámetro request se establece automáticamente en False.

Para requerir que los usuarios envíen solicitudes de unión, deja el parámetro member_limit vacío.

Parámetro Descripción
**!** platform_id ID del chat en Telegram *
member_limit límite en el número de participantes
hours Tiempo de expiración del enlace (en horas)
request un parámetro que, después de hacer clic en el enlace, se debe generar una solicitud para unirse al chat.
name nombre del enlace

Al pasar el parámetro member_limit, el valor del parámetro request se cambia automáticamente a False. Si necesitas aceptar solicitudes de membresía, entonces deja el parámetro member_limit vacío.

Creación de enlace de invitación al chat

Cómo eliminar el enlace de invitación al chat en Telegram

Descripción

Revoca un enlace de invitación existente para un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
invite_link El enlace de invitación a revocar.
Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** invite_link enlace que necesitas eliminar

Cómo desactivar todos los enlaces existentes y reemplazarlos por un enlace

Descripción

Crea un nuevo enlace de invitación principal para un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.

Advertencia

Este método genera un nuevo enlace de invitación principal para el chat.

Todos los enlaces de invitación principales generados anteriormente quedarán inactivos. El enlace recién generado será el único enlace de invitación principal activo hasta que se creen enlaces de invitación adicionales.

Usa este método con precaución.

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** invite_link enlace que necesitas eliminar

Cómo aceptar solicitud y agregar usuario en un canal/chat de Telegram

Descripción

tg_approve_chat_join_request(chat_id, user_id)

Aprueba una solicitud de unión pendiente para un grupo o canal de Telegram.

Parámetros

Parámetro Descripción
chat_id El ID del grupo o canal de Telegram.
user_id El ID de usuario de Telegram del usuario cuya solicitud de unión debe ser aprobada.
**!** chat_id ID del grupo/canal dentro de Telegram *
**!** user_id ID de usuario dentro de Telegram *

Aceptación de solicitud:

Cómo rechazar solicitud en un canal/chat de Telegram

Descripción

tg_decline_chat_join_request(chat_id, user_id)

Rechaza una solicitud de unión pendiente para un grupo o canal de Telegram.

Parámetros

Parámetro Descripción
chat_id El ID del grupo o canal de Telegram.
user_id El ID de usuario de Telegram del usuario cuya solicitud de unión debe ser rechazada.
**!** chat_id ID del grupo/canal dentro de Telegram *
**!** user_id ID de usuario dentro de Telegram *

Cómo bloquear usuario en Telegram

Descripción

tg_ban_chat_member(chat_id, user_id, hours)

Bloquea a un usuario de un chat de Telegram.

Parámetros

Parámetro Descripción
chat_id El ID del chat de Telegram.
user_id El ID de usuario de Telegram del usuario a bloquear.
hours Duración del bloqueo, en horas. Si se omite, el bloqueo es permanente.

Nota

Si el valor de hours supera los 366 días, el usuario será baneado permanentemente.

Parámetro Descripción
**!** chat_id ID del chat dentro de Telegram *
**!** user_id ID del usuario dentro de Telegram * para bloquear
hours Duración del bloqueo en horas. Por defecto, el bloqueo es permanente. Si especifica una duración de bloqueo superior a 366 días, el bloqueo se establecerá como permanente.

Cómo desbloquear un usuario en Telegram

Descripción

tg_unban_chat_member(chat_id, user_id)

Desbloquea a un usuario de un chat de Telegram.

Parámetros

Parámetro Descripción
chat_id El ID del chat de Telegram.
user_id El ID de usuario de Telegram del usuario a desbloquear.
Parámetro Descripción
**!** chat_id ID del chat dentro de Telegram *
**!** user_id ID del usuario dentro de Telegram *, a quien necesita desbloquear

Cómo verificar el estado de suscripción en Telegram

Descripción

tg_get_chat_member(chat_id, user_id)

Recupera información sobre el estado de membresía de un usuario en un chat de Telegram.

Parámetros

Parámetro Descripción
chat_id El ID del chat de Telegram.
user_id El ID de usuario de Telegram del usuario cuyo estado de membresía se verificará.
Parámetro Descripción
**!** chat_id ID del chat dentro de Telegram *
**!** user_id ID del usuario dentro de Telegram *, cuya suscripción estamos verificando

Cómo determinar el número de miembros en un canal/chat

Descripción

tg_get_chat_member_count(platform_id)

Devuelve el número total de miembros en un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
Parámetro Descripción
**!** platform_id ID del chat en Telegram *

Cómo verificar si un miembro del chat está en una lista específica

some_client_in_list(list_id, recepient)

Verifica si un usuario de Telegram está incluido en la lista especificada.

Parámetros

Parámetro Descripción
list_id El ID de la lista a verificar.
recepient El ID de usuario de Telegram. Para miembros del chat, use la variable chat_member_id.
Parámetro Descripción
**!** list_id número de lista
**!** recepient ID del usuario dentro de Telegram *. Para clientes del chat, este valor está en la variable chat_member_id.

Cómo mostrar las acciones del bot al usuario (escribir/seleccionar un sticker, etc.)

Descripción

tg_send_chat_action(platform_id, bot_action, message_thread_id)

Envía una acción de chat (como escribir o subir un archivo) a un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
bot_action La acción de chat a mostrar. Elija una de las acciones de chat de Telegram compatibles.
message_thread_id El ID del tema. Disponible solo para supergrupos con Temas (Foros) habilitados.

Nota

Esta función es compatible cuando se trabaja con cuentas de Telegram Business.

Parámetro Descripción
**!** platform_id ID del chat en Telegram *
**!** bot_action acción del bot de la lista
message_thread_id ID del tema (disponible para supergrupos si la funcionalidad de foro está disponible).
**Lista de acciones disponibles bot_action**

typing para mensajes de texto,
&#xNAN;upload_photo para fotos,
&#xNAN;record_video o upload_video para videos,
&#xNAN;record_voice o upload_voice para notas de voz,
&#xNAN;upload_document para documentos comunes,
&#xNAN;choose_sticker para stickers,
&#xNAN;find_location para datos de ubicación,
&#xNAN;record_video_note o upload_video_note para nota de video.

Esta notificación se mostrará hasta que se reciba alguna respuesta del bot, pero no más de 5 segundos.

Cómo mostrar una notificación de alerta al usuario

Descripción

tg_answer_callback_query(callback_query_id, text, show_alert, cache_time)

Envía una respuesta a una consulta de devolución de llamada activada cuando un usuario hace clic en un botón en línea en Telegram.

Parámetros

Parámetro Descripción
callback_query_id El ID de la consulta de devolución de llamada recibido cuando el usuario hace clic en un botón en línea. Esto identifica a qué devolución de llamada responder.
text El texto a mostrar en la notificación.
show_alert Controla cómo se muestra la notificación. Establézcalo en False para mostrar una notificación temporal tipo tooltip, o True para mostrar un cuadro de diálogo de alerta persistente.
cache_time El tiempo máximo, en segundos, que la respuesta de devolución de llamada se puede almacenar en caché en el lado del cliente. El valor predeterminado es 0. Los clientes de Telegram admiten el almacenamiento en caché a partir de la versión 3.14.

Importante

Esta función solo se puede usar en respuesta a un usuario que hace clic en un botón de devolución de llamada en línea en Telegram.

Ejemplo

El siguiente teclado en línea envía diferentes valores de devolución de llamada cuando se hace clic en cada botón:

[{"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"}]

Después de hacer clic en un botón, llega una devolución de llamada con el texto contenido en el campo correspondiente. Cuando hace clic en el botón "111", recibirá una devolución de llamada con el texto "first".

Creemos un bloque de inicio y especifiquemos el texto deseado en el disparador. En nuestro caso: "first"

Si en el campo Coincidencias selecciona Ignorar errores e imprecisiones, este bloque se puede reutilizar más tarde para todas las variantes similares que difieren en 1 o 2 caracteres. Por ejemplo, para agradecer al usuario por proporcionar una calificación con dicho botón.

A continuación, en la calculadora, use la función tg_answer_callback_query y pase los siguientes parámetros:
callback_query_id - este ID le permite identificar al usuario que presionó el botón y mostrarle una notificación de alerta
text - texto de la notificación de alerta.

Ejemplo de código para copiar:

tg_answer_callback_query('#{callback_query_id}', "Presionaste el botón 111")

¡Preste atención! El parámetro callback_query_id debe pasarse exactamente como se muestra en el ejemplo, es decir, dentro de '#{}'

Si todo está configurado correctamente, al presionar el botón aparecerá una notificación de alerta con el texto especificado. En la versión móvil, el nombre del bot aparecerá como encabezado sobre el texto.

Si desea mostrar un mensaje emergente simple en su lugar, pase False como tercer parámetro, como se muestra en el siguiente ejemplo:
tg_answer_callback_query('#{callback_query_id}', "Pasaste el botón 222", False)

Agregar una redirección del bot con una etiqueta como respuesta del botón de devolución de llamada

Descripción

tg_callback_url_open(callback_query_id, url, cache_time)

Abre un bot de Telegram usando un enlace profundo en respuesta a una devolución de llamada de un botón en línea.

Parámetros

Parámetro Descripción
callback_query_id El ID de la consulta de devolución de llamada recibido cuando el usuario hace clic en un botón en línea. Esto identifica a qué devolución de llamada responder.
url Un enlace profundo al bot en el formato https://t.me/your_bot?start=XXXX, donde your_bot es el nombre de usuario del bot y XXXX es el parámetro de inicio.
cache_time El tiempo máximo, en segundos, que la respuesta de devolución de llamada se puede almacenar en caché en el lado del cliente. El valor predeterminado es 0. Los clientes de Telegram admiten el almacenamiento en caché a partir de la versión 3.14.

Importante

Esta función solo se puede usar en respuesta a un usuario que hace clic en un botón de devolución de llamada en línea en Telegram.

Ejemplo

En la respuesta del botón de devolución de llamada, puede agregar una transición al bot usando la etiqueta tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX')

Por ejemplo, usemos los siguientes botones:

[{"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"}]

Después de hacer clic en un botón, llega una devolución de llamada con el texto contenido en el campo correspondiente. Cuando hace clic en el botón "111", recibirá una devolución de llamada con el texto "first".

Cree un bloque con una verificación de condición primaria y especifique el texto deseado en la condición. En nuestro caso: "first":

Si en el campo Opción de coincidencia selecciona Ignorar errores e imprecisiones, este bloque se puede reutilizar más tarde para todas las variantes similares que difieren en 1 o 2 caracteres. Por ejemplo, para agradecer al usuario por proporcionar una calificación con dicho botón.

A continuación, en la calculadora del bloque, especifique tg_callback_url_open('#{callback_query_id}', 't.me/bot_name?start=XXXX'):

Cómo promover a un usuario como administrador en un supergrupo o canal

Descripción

tg_promote_user(platform_id, user_id, promote_options_list)

Promueve a un usuario de Telegram como administrador en un supergrupo o canal con los permisos especificados.

Parámetros

Parámetro Descripción
platform_id El identificador del supergrupo de Telegram, o el nombre de usuario del canal en el formato @channelusername cuando se promueve a un usuario en un canal.
user_id El ID de usuario de Telegram del usuario a promover.
promote_options_list Una lista de permisos de administrador que se otorgarán al usuario.

Nota

Solo se otorgarán al usuario los permisos incluidos en promote_options_list.

**Parámetro requerido: promote_options_list**

En promote_options_list se pueden especificar los siguientes permisos:

  1. is_anonymous — oculta la presencia del administrador en el chat,
  2. can_manage_chat — el administrador puede acceder al registro de eventos del chat, estadísticas del chat, estadísticas de mensajes en canales, ver miembros del canal, ver administradores anónimos en supergrupos y omitir el modo lento. Este nivel de permiso se otorga por defecto si se especifica alguno de los privilegios posteriores.
  3. can_post_messages — el administrador puede crear publicaciones en el canal (solo canales)
  4. can_edit_messages — el administrador puede editar mensajes de otros usuarios y fijar mensajes (solo canales)
  5. can_delete_messages — el administrador puede eliminar mensajes de otros usuarios
  6. can_manage_video_chats — el administrador puede gestionar videollamadas,
  7. can_restrict_members — el administrador puede restringir miembros, banear/desbanearlos en el chat,
  8. can_promote_members — el administrador puede nombrar nuevos administradores con un subconjunto de sus propios privilegios, o degradar administradores que haya nombrado directa o indirectamente (por ejemplo, administradores nombrados por ellos)
  9. can_change_info — el administrador puede cambiar el título del chat, la foto y otras configuraciones
  10. can_invite_users — el administrador puede invitar nuevos usuarios al chat
  11. can_pin_messages — el administrador puede fijar mensajes (solo supergrupos).
Ejemplo

Ejemplo: Promover a un usuario como administrador en un supergrupo:

En este ejemplo, además de los permisos especificados, el permiso can_manage_chat se otorgará por defecto.

Ejemplo de código para copiar

Ejemplo 1. 
promote_options_list = '[“can_promote_members”,”can_change_info”,”can_invite_users”]' 
tg_promote_user(platform_id, user_id, promote_options_list)

Ejemplo 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)  

Cómo cambiar el título de un administrador usando un bot en Telegram

Descripción

tg_set_administrator_title(platform_id, user_id, title)

Establece un título de administrador personalizado para un administrador de supergrupo de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del supergrupo de Telegram.
user_id El ID de usuario de Telegram del administrador.
title El título de administrador personalizado.

Importante

  • El título debe tener entre 0 y 16 caracteres de longitud.
  • No se permiten emojis en el título.
  • Esta función funciona solo para administradores que fueron promovidos por el bot.

Ejemplo

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

Restricciones generales para miembros regulares del chat o usuarios específicos de Telegram

Descripción

tg_chat_permission(platform_id, permission, media_permissions)

Establece los permisos predeterminados para los miembros en un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
permission Un arreglo de permisos generales del chat. Cada elemento corresponde a un permiso en la lista de permisos admitidos. Use 1 para permitir la acción y 0 para prohibirla.
media_permissions Un arreglo de permisos relacionados con medios. Cada elemento corresponde a un permiso en la lista de permisos de medios admitidos. Use 1 para permitir la acción y 0 para prohibirla.

Nota

El orden de los valores en ambos arreglos debe coincidir con el orden de las listas de permisos correspondientes. Cada elemento del arreglo controla un permiso específico:

  • 1 — Permiso concedido.
  • 0 — Permiso denegado.
Lista de restricciones para el parámetro requerido **permission**

Lista de restricciones para permission:

  1. ! can_send_messages - permiso para enviar mensajes de texto, contactos, ubicaciones y lugares.
  2. ! can_send_media_messages - permiso para enviar audio, documentos, fotos, videos, notas de video y notas de voz. Requiere can_send_messages
  3. ! can_send_polls - permiso para enviar encuestas. Requiere can_send_messages
  4. ! can_send_other_messages - permiso para enviar animaciones, juegos, stickers y usar bots inline. Requiere can_send_media_messages
  5. ! can_add_web_page_previews - permiso para agregar vistas previas de páginas web a los mensajes. Requiere can_send_media_messages
  6. ! can_change_info - permiso para cambiar el título del chat, la foto y otras configuraciones. Esto se ignora en supergrupos públicos.
  7. ! can_invite_users - permiso para invitar usuarios
  8. ! can_pin_messages - permiso para fijar mensajes. Esto se ignora en supergrupos públicos.
  9. can_manage_topics - permiso para crear temas en grupos de foro. Si se usa en un grupo de tipo incorrecto, la función fallará y devolverá un error.
Lista de valores para el parámetro requerido **media_permissions**

Valores para otorgar permisos relacionados con medios media_permissions:

  1. can_send_audios - permiso para enviar archivos de audio
  2. can_send_documents - permiso para enviar documentos
  3. can_send_photos - permiso para enviar fotos
  4. can_send_videos - permiso para enviar videos
  5. can_send_video_notes - permiso para enviar mensajes de video redondos
  6. can_send_voice_notes - permiso para enviar mensajes de voz

Restricciones personales de Telegram para usuarios regulares del chat o para usuarios específicos de Telegram

Descripción

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

Parámetros:

Parámetro Descripción
! platform_id ID del chat en Telegram *
! user_id ID de usuario en Telegram *
minutes el número de minutos durante los cuales la restricción estará activa. Si no establece un valor, el valor predeterminado es 3600, que equivale a 60 horas. Si lo establece en 0, la restricción se vuelve permanente
permission un arreglo de valores de la lista de restricciones de permisos.
media_permissions una lista de valores para otorgar permisos relacionados con medios
Lista de restricciones para el parámetro requerido **permission**

Lista de restricciones para permission:

  1. ! can_send_messages - permiso para enviar mensajes de texto, contactos, ubicaciones y lugares.
  2. ! can_send_media_messages - permiso para enviar audio, documentos, fotos, videos, notas de video y notas de voz. Requiere can_send_messages
  3. ! can_send_polls - permiso para enviar encuestas. Requiere can_send_messages
  4. ! can_send_other_messages - permiso para enviar animaciones, juegos, stickers y usar bots inline. Requiere can_send_media_messages
  5. ! can_add_web_page_previews - permiso para agregar vistas previas de páginas web a los mensajes. Requiere can_send_media_messages
  6. ! can_change_info - permiso para cambiar el título del chat, la foto y otras configuraciones. Esto se ignora en supergrupos públicos.
  7. ! can_invite_users - permiso para invitar usuarios
  8. ! can_pin_messages - permiso para fijar mensajes. Esto se ignora en supergrupos públicos.
  9. can_manage_topics - permiso para crear temas en grupos de foro. Si se usa en un grupo de tipo incorrecto, la función fallará y devolverá un error.
Lista de valores para el parámetro requerido **media_permissions**

Valores para otorgar permisos relacionados con medios media_permissions:

  1. can_send_audios - permiso para enviar archivos de audio
  2. can_send_documents - permiso para enviar documentos
  3. can_send_photos - permiso para enviar fotos
  4. can_send_videos - permiso para enviar videos
  5. can_send_video_notes - permiso para enviar mensajes de video redondos
  6. can_send_voice_notes - permiso para enviar mensajes de voz
Ejemplo

Ejemplo de uso de la función, donde el usuario está restringido de todo durante 3 minutos:

Cuando el usuario ingresa al chat, verá una notificación de que no puede enviar mensajes en el chat.
Si se establece un límite de tiempo, también verá la duración de esta restricción.

Ejemplo de código para copiar:

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

Cómo fijar un mensaje

Descripción

tg_pin_chat_message(platform_id, message_id, disable_notification)

Fija un mensaje en un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
message_id El ID del mensaje a fijar.
disable_notification Controla si los miembros del chat son notificados sobre el mensaje fijado. Establece en 1 para fijar el mensaje silenciosamente, o 0 para enviar una notificación.

Nota

Las notificaciones siempre están deshabilitadas en canales y chats privados, independientemente del valor de disable_notification.

Cómo desfijar un mensaje

Descripción

tg_unpin_chat_message(platform_id, message_id)

Desfija un mensaje en un chat de Telegram.

Parámetros

Parámetro Descripción
platform_id El ID del chat de Telegram.
message_id El ID del mensaje a desfijar. Si se omite, se desfija el mensaje fijado más recientemente.

Nota

Si message_id no se especifica, la función desfija el último mensaje fijado según su hora de envío.

Cómo desfijar todos los mensajes fijados

Descripción

tg_unpin_all(platform_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *

¡ATENCIÓN!

Telegram tiene una limitación para las funciones de fijar/desfijar mensajes.

Los límites de tiempo para usar **tg_pin_chat_message / tg_unpin_chat_message / tg_unpin_all **NO son establecidos por el sistema MaviBot.

Si el tiempo permitido para fijar un mensaje ha pasado, la función seguirá devolviendo true, pero Telegram no aplicará el cambio.

También es importante tener en cuenta que los mensajes fijados pueden permanecer en caché, por lo que es posible que no desaparezcan visualmente de inmediato.

Cómo crear una encuesta en Telegram

Descripción

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)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat en Telegram *
**!** question pregunta
**!** options un array de opciones de respuesta
is_anonymous 1 - encuesta anónima , '' - no anónima
allows_multiple_answers 1 - respuestas múltiples disponibles, '' - una respuesta
reply_markup teclado o '' - sin teclado
disable_notification indicador para enviar con notificación sonora (por defecto 0)
1 – deshabilitar notificación al recibir, 0 – enviar con notificación
protect_content 1 para proteger contra copia y capturas de pantalla, '' sin protección
token token del bot; si no se proporciona, se usa el actual
reply_to_message_id ID del mensaje citado
message_thread_id ID del hilo (disponible para supergrupos si existe funcionalidad de foro)
business_connection_id valor al conectar un bot (Business ID). Se muestra en los canales. Debe proporcionarse si se usa el token del bot y el mensaje debe enviarse a través de una cuenta de usuario conectada al bot
¡Importante saberlo!

Notas

  1. La función devuelve una respuesta de Telegram con message_id. Es mejor guardarlo. Usando message_id, puedes detener la encuesta con tg_stop_poll (ver descripción a continuación) y obtener el resultado.

  2. Si un usuario añade una encuesta en un mensajero, se envía un callback al chat:

poll_added - parte invariable
YOUR QUESTION - texto de la pregunta de la encuesta

Ejemplo de callback al añadir una encuesta en un canal

Ejemplo de callback al añadir una encuesta en un chat

El segundo callback después de poll_added contiene números: esto no es más que el identificador del usuario en Telegram que añadió la encuesta.

Al crear una encuesta con un bot, no llega ningún callback.

3. En un canal solo se pueden crear encuestas anónimas

Atención, ¡se recomienda enviar solo encuestas anónimas al grupo!

  1. Después de crear la encuesta, guarda su identificador en una variable para saber a qué encuesta llegó el callback.
Ejemplo

La retroalimentación del cliente es clave para nuestro crecimiento. Las encuestas ofrecen un método directo para capturar esta retroalimentación y traducirla en conclusiones comerciales concretas.

Ejemplo de código para copiar:

/* 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, '')

Función para crear una encuesta en Telegram:

La encuesta que creamos en Telegram

Cómo crear un cuestionario en Telegram

Descripción

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 )

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** question pregunta
**!** options un array de opciones de respuesta
**!** explanation texto que se muestra cuando un usuario selecciona una respuesta incorrecta o hace clic en el ícono de la lámpara en una encuesta tipo cuestionario, 0–200 caracteres con no más de dos saltos de línea después del análisis de entidades.
**!** correct_option_id número de la respuesta correcta, numeración desde 1
is_anonymous 1 - encuesta anónima , '' - no anónima
reply_markup teclado o '' - sin teclado
parse_mode formato de la explicación: markdown, html, o '' (cadena vacía para sin formato)
protect_content 1 para proteger contra copia y capturas de pantalla, '' sin protección
disable_notification indicador para enviar con notificación sonora (por defecto 0)
1 – deshabilitar notificación al recibir, 0 – enviar con notificación
token token del bot; si no se proporciona, se usa el actual
reply_to_message_id ID del mensaje citado
message_thread_id ID del tema (disponible en supergrupos con funciones de foro activas)
**¡Importante saberlo!**

Notas

1. Guarda el message_id

La función de la API devuelve una respuesta de Telegram que contiene un message_id. Guarda siempre este ID, ya que es necesario para:

  • Finalizar el cuestionario usando la función tg_stop_poll (ver descripción a continuación).
  • Recuperar los resultados finales.

2. Callback poll_added

Si un usuario añade una encuesta a un canal, el bot recibe un callback:

  • Formato: poll_added + Pregunta de la encuesta
  • Si se añade a un chat grupal: el callback también incluye el ID de usuario de Telegram de la persona que añadió la encuesta.

Si es creado por el bot: No se envía ningún callback poll_added.

3. Restricción del canal

Solo se pueden crear cuestionarios anónimos en los canales.

4. Callback poll_answer (Votación del usuario)

Cuando un usuario vota en un cuestionario enviado a un chat privado o grupo, se envía un callback al diálogo del bot con ese cliente:

  • Formato: poll_answer + ID de la encuesta + [Índice de respuesta]
  • Ejemplo: poll_answer 5325838371359031648 [3]
  • Nota: la numeración de respuestas comienza desde 0. [3] significa que el usuario seleccionó la cuarta opción de respuesta.

5. Webhook para encuestas grupales no anónimas

Para encuestas no anónimas en grupos donde el bot es administrador, se envía un webhook por cada voto. Al recibirlo, el bot reenviará el callback poll_answer (como en el punto 4) a su diálogo con el cliente correspondiente.

6. Requisito de activación y mejor práctica

  • Requisito: un bot no puede iniciar una conversación. Si un cliente nunca ha contactado al bot, no puedes enviarle un mensaje directo en respuesta a su voto hasta que active el bot primero (por ejemplo, enviando un comando /start).

Recomendación: para evitar esta limitación, se recomienda encarecidamente enviar solo cuestionarios anónimos a los grupos.

7. Rastrea tus encuestas

Inmediatamente después de crear un cuestionario, guarda su ID de encuesta único en una variable. Esto te permite identificar a qué encuesta específica se refiere un callback entrante.

Ejemplo

Ejemplo de código para copiar.

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

Ejemplo: creación de un cuestionario.

Cómo finalizar una encuesta

Descripción

tg_stop_poll(platform_id, message_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat en Telegram *
**!** message_id ID del mensaje de la encuesta/cuestionario. Se puede obtener del webhook

Llamar a esta función para finalizar una encuesta/cuestionario devuelve un diccionario que contiene los resultados finales.

Cómo trabajar con temas en Telegram

Importante: el tema principal del grupo no tiene un ID y requiere funciones separadas para trabajar con él.

Cómo renombrar el Tema General del grupo

Descripción

tg_edit_general_forum_topic(platform_id, topic_name)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** topic_name nuevo nombre del tema
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza múltiples bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo

El Tema General del grupo se puede cambiar usando la función tg_edit_general_forum_topic(). Requiere dos parámetros obligatorios: el ID del chat y el nuevo nombre para el Tema del Grupo:

Ejemplo de código para copiar

/renombrar el chat del Tema General/
answer = tg_edit_general_forum_topic(-1001839380031, 'General')

Cómo cerrar el Tema General

Descripción

tg_close_general_forum_topic(platform_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

/cerrar el chat del Tema General/
answer = tg_close_general_forum_topic(-1001839380031)

Cómo reabrir un Tema General previamente cerrado

Descripción

tg_reopen_general_forum_topic(platform_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

/reabrir el chat del Tema General/
answer = tg_reopen_general_forum_topic(-1001839380031)

Cómo ocultar el Tema General

Descripción

tg_hide_general_forum_topic(platform_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

El chat del Tema General se puede cerrar para los participantes del Tema (pueden leer pero no escribir) y ocultar de la lista de chats general de Telegram para los nuevos usuarios.

Ejemplo de código para copiar

/ocultar el chat del Tema General/
answer = tg_hide_general_forum_topic(-1001839380031)

Cómo mostrar el Tema General o restaurar su visibilidad

Descripción

tg_unhide_general_forum_topic(platform_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del tema dentro de Telegram *
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

¡Importante!

Esta función no reabre el Tema General; solo lo hace visible.

Ejemplo de código para copiar

/mostrar el chat del Tema General/
answer = tg_unhide_general_forum_topic(-1001839380031)

Cómo crear un nuevo tema en Telegram

Descripción

tg_create_forum_topic(platform_id, name, icon, icon_color)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** name nombre del nuevo tema
icon ID del emoji que se establecerá para el tema. Se pasa como una cadena. Solo puedes usar emojis de la lista obtenida por la función tg_get_forum_icon.
icon_color color del emoji de la lista: 7322096, 16766590, 13338331, 9367192, 16749490, 16478047. No todos los emojis admiten cambios de color.
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

El color establecido no se puede cambiar; el color solo se puede asignar al crear el tema.

Cuando se ejecuta, la función devolverá una respuesta que contiene los parámetros del nuevo tema, incluido el ID del tema (necesario para varias funciones).

Ejemplo de código para copiar

Para crear un chat de tema adicional
answer = tg_create_forum_topic(-1001839380031, 'second_bot_topic', None, 7322096)

Para guardar el ID del chat de tema adicional creado
answer={"ok":true,"result":{"message_thread_id":254,"name":"second_bot_topic","icon_color":7322096}}/
idtema1=answer['result']['message_thread_id']

Cómo editar un tema. Cómo renombrar y/o cambiar el emoji de un tema

Descripción

tg_edit_forum_topic(platform_id, message_thread_id, name, icon)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** message_thread_id ID del chat de tema adicional
name nuevo nombre del tema
icon ID del emoji que se establecerá para el tema. Se pasa como una cadena. Solo puedes usar emojis de la lista obtenida por la función tg_get_forum_icon.
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

answer = tg_edit_forum_topic(-1001839380031, 254)

Cómo cerrar un tema seleccionado

Descripción

Cerrar un tema significa hacerlo de solo lectura; no se permite escribir en un tema cerrado.

tg_close_forum_topic(platform_id, message_thread_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** message_thread_id ID del chat de tema adicional
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

answer = tg_close_forum_topic(-1001839380031, 254)

Cómo reabrir un tema previamente cerrado

Descripción

tg_reopen_forum_topic(platform_id, message_thread_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** message_thread_id ID del chat de tema adicional
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

answer = tg_reopen_forum_topic(-1001839380031, 254)

Cómo eliminar un tema y todos sus mensajes

Descripción

tg_delete_forum_topic(platform_id, message_thread_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** message_thread_id ID del chat de tema adicional
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

answer = tg_delete_forum_topic(-1001839380031, 254)

Cómo desanclar todos los mensajes en un tema

Descripción

tg_unpin_topic_messages(platform_id, message_thread_id)

Parámetros:

Parámetro Descripción
**!** platform_id ID del chat dentro de Telegram *
**!** message_thread_id ID del chat de tema adicional
bot_name

parámetro opcional: nombre del bot.

Al trabajar con temas, puedes especificar qué bot debe ejecutar la función. Esto es útil si tu proyecto utiliza varios bots de Telegram. Encuentra el nombre del bot en la sección "Canales", en el campo "ID del grupo".

Ejemplo de código para copiar

answer = tg_unpin_topic_messages(-1001839380031, 254)

Cómo obtener la lista de emojis para un Tema de Telegram

Descripción

Cómo obtener la lista de emojis

tg_get_forum_icon() – esta función devuelve una lista de emojis disponibles para usar como iconos de temas del foro. El resultado debe asignarse a una variable, ya que devuelve un diccionario donde cada clave es un emoji y su valor correspondiente es el identificador único del emoji (id).

Parámetros: ninguno.

El contenido de la lista de emojis

Para obtener la lista de emojis para un chat de Tema, envía el comando al chat correspondiente.

La función devolverá la lista de emojis en su respuesta. Esto significa que la variable answer contendrá un diccionario como su valor.

{'📰': '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'}

Ejemplo de código para copiar
answer = tg_get_forum_icon()