Cómo iniciar un bot Telegram con PHP

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

Si estás leyendo esto, sabes que los robots de chat son una de las mayores tendencias tecnológicas de 2016.

La revolución bot no es sólo acerca de la inteligencia artificial. Un bot puede ser una herramienta en tu mensajero con una interfaz de chat simple que se puede utilizar para ampliar la funcionalidad de sitios o servicios o incluso puede ser una aplicación independiente. Los robots son más baratos de desarrollar y más fáciles de instalar, y otra gran característica es que los mensajeros se pueden utilizar en todo tipo de dispositivos—ordenadores portátiles, teléfonos inteligentes y tabletas. Es por eso que todo el mundo está loco por los bots ahora.

Y el mayor mensajero con una API de bot abierta es Telegram.

Qué vamos a hacer

En este artículo vamos a crear un simple cronómetro Telegram bot. Te mostraré cómo crear tu bot, conectarte con analytics, escribir algún código y, finalmente, agregar tu bot a una tienda de bot.

Por cierto, ya he preparado una demostración, por lo que puedes probarlo simplemente añadiendo @stopwatchbot a tu lista de contactos de Telegram.

Crear un Bot con BotFather

El primer paso para crear un bot es registrar la cuenta de tu bot en Telegram. Y hay un bot para eso, llamado BotFather. Sólo tienes que añadirlo a tu lista de contactos y podrás crear y configurar robots de Telegram , simplemente escribiendo el comando /newbot y siguiendo las instrucciones de BotFather.

Después de registrar su nuevo bot, recibirá un mensaje de felicitación con un token de autorización. Usaremos este símbolo pronto para autorizar un bot y enviar solicitudes a la API de Bot.

Más tarde, puedes usar BotFather para añadir descripciones o fotos a los perfiles de tus bots, regenerar tokens, establecer listas de comandos para usar, eliminar cuentas, etc. Para obtener una lista completa de comandos, solo tienes que escribir /help en un chat para obtener una lista de los comandos de BotFather.

Conéctese con Botan Analytics

No hay un análisis interno en la API de Telegram Bots, pero es importante saber cuántos usuarios tiene, cómo actúan y qué comandos activan más. Por supuesto, podemos recopilar esta información usando nuestro propio motor, pero si queremos enfocarnos en la funcionalidad de bot, no métricas, solo necesitamos usar una solución lista para usar.

Y hay una herramienta simple para conectar su bot a la analítica, llamada Botan. Está basado en Yandex AppMetric y completamente gratuito. Usando Botan, puede segmentar su audiencia, obtener información sobre los perfiles de usuario, obtener el comando más utilizado y obtener bellos gráficos directamente en su mensajero, como esto:

Para empezar, necesita registrar su bot en Botan y obtener un token. Y otra vez, puedes hacerlo con un bot, BotanioBot:

Simplemente haga clic en la tecla "Add bot" en el teclado de diálogo, escriba el nick de su bot, y obtendrá su token de pista de bot. Ahora Botanio está listo para rastrear sus eventos de bot, y puede obtener estadísticas de usuarios, sesiones, retención y eventos directamente en su mensajero.

Crear y registrar un Webhook SSL

En Telegram hay dos maneras de obtener mensajes de sus usuarios: sondeos largos y webhooks.

Básicamente, con el sondeo largo, es necesario solicitar nuevos mensajes de la API y con webhooks está configurando una devolución de llamada que llamará la API de telegrama si llega un mensaje nuevo de un usuario. Yo prefiero usar webhooks porque se parece a la comunicación en tiempo real, por lo que en este artículo vamos a utilizar este método también. Ahora tenemos que elegir una URL de devolución de llamada para nuestro webhook, que debe ser alcanzado bajo el protocolo HTTPS, y tenemos que configurarlo realmente seguro, así que ocultar su script en una ruta secreta, como dice el manual:

Si desea asegurarse de que la solicitud Webhook proviene de Telegram, le recomendamos que utilice una ruta secreta en la URL, ej. https://www.example.com/<token> . Puesto que nadie sabe el token de tu bot, puedes estar seguro de que somos nosotros.

Si su certificado SSL es de confianza, todo lo que necesita hacer es abrir esta URL en su navegador:

1	https://api.telegram.org:443/bot[token]/setwebhook?url=[webhook]

De lo contrario, deberá generar un certificado auto-firmado. Aquí hay un ejemplo del comando en Linux para él:

1	openssl req -newkey rsa:2048 -sha256 -nodes -keyout /path/to/certificate.key -x509 -days 365 -out /path/to/certificate.crt -subj "/C=IT/ST=state/L=location/O=description/CN=yourdomain.com"

Y no olvide abrir el puerto SSL:

1	sudo ufw allow 443/tcp

Para obtener el certificado comprobado y configurar su dominio webhook en confianza, debe cargar su certificado de clave pública:

1	curl \
2	-F "url=https://yourdomain.com/path/to/script.php" \
3	-F "certificate=/path/to/certificate.key" \
4	"https://api.telegram.org/bot[token]/setwebhook"

Por último, obtendrá una respuesta JSON como ésta:

1	{"ok":true,"result":true,"description":"Webhook was set"}

Dice que el webhook fue establecido y estamos listos para arrancar el motor del bot.

Construir una base de datos

Ahora necesitamos construir una base de datos para nuestros temporizadores. ¿Qué necesitamos para almacenar? Cuando un usuario ordena que el cronómetro comience, tomaremos el ID del chat y guardaremos una fila con el ID de chat y el tiempo actual de Unix, que es el número de segundos entre ahora y el inicio de Unix Epoch, que es el 1 de enero de 1970 En UTC. En consecuencia, guardaremos una fila con el ID de chat y la marca de tiempo de entero de la hora actual de Unix.

Para mostrar el tiempo actual del cronómetro, obtendremos la marca de tiempo guardada y compararla con la marca de tiempo actual. La diferencia será el tiempo actual en segundos. Si el usuario detiene el temporizador, simplemente eliminaremos la fila con el ID de chat actual.

Así que vamos a crear una base de datos y una tabla para almacenar la información del cronómetro:

CREATE TABLE IF NOT EXISTS `stopwatch` (
  `chat_id` int(10) unsigned NOT NULL,
  `timestamp` int(10) unsigned NOT NULL,
  PRIMARY KEY (`chat_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

Crear una clase de Stopwatch

Finalmente estamos listos para empezar a codificar. Vamos a crear una clase para trabajar con la base de datos en un archivo llamado stopwatch.php y comenzar con un constructor que establecerá dos variables privadas, donde almacenaremos el ID de chat y la conexión actual de MySQL:

class Stopwatch
{
    /** @var mysqli */
    private $mysqli;
    /** @var int */
    private $stopwatch_id;
    /**
     * Stopwatch constructor
     * @param mysqli $mysqli
     * @param $stopwatch_id
     */
    public function __construct(\mysqli $mysqli, $stopwatch_id)
    {
        $this->mysqli = $mysqli;
        $this->stopwatch_id = intval($stopwatch_id);
    }
}

Cuando el usuario inicia el temporizador, obtendremos el tiempo actual de Unix y lo guardaremos en una fila con el ID de chat, así que aquí está el método start():

public function start()
{
    $timestamp = time();
    $query = "
        INSERT INTO  `stopwatch` (`chat_id`, `timestamp`)
        VALUES ('$this->stopwatch_id', '$timestamp')
        ON DUPLICATE KEY UPDATE timestamp = '$timestamp'        
    ";
    return $this->mysqli->query($query);
}

Si el temporizador se detiene, debemos eliminar una fila de la base de datos:

/**
 * Delete row with stopwatch id
 * @return bool|mysqli_result
 */
public function stop()
{
$query = "
    DELETE FROM `stopwatch`
    WHERE `chat_id` = $this->stopwatch_id
    ";
    return $this->mysqli->query($query);
}

Y ahora para la parte principal de la clase. Cuando el usuario solicita el estado del temporizador, necesitamos encontrar la fila con el cronómetro de la conversación actual y calcular la diferencia en segundos entre la hora Unix guardada y la hora actual. Afortunadamente, el tiempo Unix es un entero, por lo que sólo podemos restar un valor de otro. Para formatear el valor resultante como un tiempo, usaremos la función gmdate.

/**
 * Find row with stopwatch id and return difference in seconds from saved Unix time and current time
 * @return string
 */
public function status()
{
    $query = "
        SELECT `timestamp` FROM  `stopwatch`
        WHERE `chat_id` = $this->stopwatch_id        
    ";
    $timestamp = $this->mysqli->query($query)->fetch_row();
    if (!empty($timestamp)) {
        return gmdate("H:i:s", time() - reset($timestamp));
    }
}

Como puede ver, si no hay valor en la base de datos, el método status() no devolverá nada y procesaremos un valor nulo como un temporizador detenido.

Elección de una biblioteca PHP

Hay muchas bibliotecas de PHP que existen para trabajar con la API de Telegram, pero, al menos en el momento de escribir este artículo, sólo hay una que admite tanto el contenedor de API Bot de Telegram como el seguimiento de Botan. Y se llama PHP Bot API Telegram.

Utilice Composer para instalar esta biblioteca:

1	composer require telegram-bot/api

Si no está interesado en el uso de análisis, pruebe Telegram Bot API PHP SDK con Lavarel integración o PHP Telegram Bot.

Iniciar la secuencia de comandos de Webhook

Y ahora empieza la parte principal—crearemos un script para procesar las devoluciones de llamada desde la API Bot de Telegram. Inicie un archivo llamado index.php e incluya la carga automática de Composer y una nueva clase Stopwatch. Abra una conexión MySQL, cree un nuevo cliente API de Telegram y ejecútelo:

require_once 'vendor/autoload.php';
require_once 'stopwatch.php';

// connect to database
$mysqli = new mysqli('database_host', 'database_user', 'database_password', 'database_name');
if (!empty($mysqli->connect_errno)) {
    throw new \Exception($mysqli->connect_error, $mysqli->connect_errno);
}

// create a bot
$bot = new \TelegramBot\Api\Client('bot_token', 'botanio_token');
// run, bot, run!
$bot->run();

Crear comandos

Ahora necesitamos configurar un bot para responder en comando /start. Este comando se utiliza para iniciar todos los bots de telegrama, y los usuarios recibirán nuestro mensaje de bienvenida cuando comience el primer chat.

1	$bot->command('start', function ($message) use ($bot) {
2	$answer = 'Howdy! Welcome to the stopwatch. Use bot commands or keyboard to control your time.';
3	$bot->sendMessage($message->getChat()->getId(), $answer);
4	});

Aquí, en el método command(), definimos un cierre para recibir un comando. Este cierre obtiene el ID del chat actual y envía un mensaje de bienvenida. Además, todos los comandos registrados se rastrean automáticamente como nombre de comando.

Para iniciar el cronómetro, definiremos el comando /go:

$bot->command('go', function ($message) use ($bot, $mysqli) {
    $stopwatch = new Stopwatch($mysqli, $message->getChat()->getId());
    $stopwatch->start();
    $bot->sendMessage($message->getChat()->getId(), 'Stopwatch started. Go!');
});

Esto creará una instancia de la clase Stopwatch e iniciará un temporizador llamando al método start() que ya hemos definido.

Para definir el comando /status, necesitamos hacer lo mismo. Simplemente llame al método status() y devuelva el resultado. Si el método devuelve nulo, dígale al usuario que el temporizador no se ha iniciado.

$bot->command('status', function ($message) use ($bot, $mysqli) {
    $stopwatch = new Stopwatch($mysqli, $message->getChat()->getId());
    $answer = $stopwatch->status();
    if (empty($answer)) {
        $answer = 'Timer is not started.';
    }
    $bot->sendMessage($message->getChat()->getId(), $answer);
});

Y si el usuario detiene el temporizador, necesitamos obtener el estado primero, mostrar el tiempo resultante y detener el temporizador utilizando el método stop().

$bot->command('stop', function ($message) use ($bot, $mysqli) {
    $stopwatch = new Stopwatch($mysqli, $message->getChat()->getId());
    $answer = $stopwatch->status();
    if (!empty($answer)) {
        $answer = 'Your time is ' . $answer . PHP_EOL;
    }
    $stopwatch->stop();
    $bot->sendMessage($message->getChat()->getId(), $answer . 'Stopwatch stopped. Enjoy your time!');
});

¡Eso es! Ahora puede cargar todos los archivos en el directorio webhook y probar su bot.

Adición de un teclado

Para sugerir al usuario cuáles comandos puede ejecutar, podemos agregar un teclado a un mensaje. Nuestro cronómetro puede estar funcionando o parado, y habrá dos para cada estado. Para mostrar un teclado al usuario, sólo necesitamos extender el método sendMessage():

1	$keyboard = new \TelegramBot\Api\Types\ReplyKeyboardMarkup([['/go', '/status']], null, true);
2
3	$bot->sendMessage($message->getChat()->getId(), $answer, false, null, null, $keyboards);
4	});

Ahora puedes agregar teclados a cada comando de tu bot. No voy a incluir un ejemplo completo aquí, pero se puede ver en las páginas del repositorio.

Cómo agregar su bot a una tienda

Bueno, ahora tenemos bot de trabajo, y queremos mostrarlo al mundo. La mejor manera es registrar el bot en un catálogo de bot. Por ahora, Telegram no tiene un catálogo oficial como este, pero hay algunos no oficiales, y el mayor es Storebot.me, donde miles de bots ya están registrados.

Y hay un ... bot para registrar tu bot en una tienda de bot! Agregue @storebot a su lista de contactos, escriba el comando /add y siga las instrucciones. Se le pedirá que introduzca el nombre de usuario, el nombre y la descripción del bot, elija una de las categorías estándar y confirme la propiedad del bot enviando su token.

Después de un tiempo, tu robot pasará el proceso de envío y aparecerá en los gráficos de Storebot. Ahora usted y sus usuarios pueden votar, encontrar y calificar a su bot en la tienda de bot para ayudarlo a subir a la parte superior de la tabla.

Conclusion

Hemos recorrido un largo camino, desde la creación de un bot bebé hasta su registro en una tienda para estar disponible para los usuarios reales. Como puede ver, hay muchas herramientas que existen para hacer su vida más fácil con la creación y propagación de su bot, y no necesita mucho código para iniciar un bot fácil. ¡Ahora usted está listo para hacer sus los propios!

Si tiene alguna pregunta, no dude en hacer preguntas en los comentarios al artículo.