Toot con Laravel, Vonage y Mastodon

Es posible que haya oído hablar de Mastodon en los últimos meses, dados los cambios que se están produciendo en el mundo de las redes sociales, pero ¿qué es y qué puedo hacer con él?

En este artículo, voy a utilizar Vonage, Laravel, y Expose para recibir un SMS entrante enviado desde su teléfono a 'toot' a cabo en una cuenta de Mastodon.

¿Qué es Mastodon?

Mastodon es una plataforma de medios sociales de código abierto. En términos de comportamiento e interfaz de usuario, es muy similar a Twitter (el equivalente a un "tweet" es un "toot", por ejemplo). Sin embargo, hay grandes diferencias: he mencionado que es de código abierto, pero también funciona como una red "descentralizada". Este aspecto es lo que la hace única: la idea es que puedas crear tu propia instancia de Mastodon, que está conectada a "el Fediverso" (es decir, todos los demás servidores Mastodon). El resultado final es que tú, como usuario, puedes elegir una instancia de Mastodon para registrarte, pero puedes ver el contenido de todos los demás usuarios de la plataforma.

Para sorpresa de probablemente nadie, la tasa de registro de Mastodon ha sido fenomenal: sólo en noviembre de 2022, dio la bienvenida a un millón de nuevos usuarios.

Supongo que es bastante poético que la mascota de Mastodon sea un Mastodonte, pariente lejano del elefante, dado que, en primer lugar, soy el especialista en PHP del equipo de relaciones con los desarrolladores de Vonage y, en segundo lugar, un usuario del servidor de la comunidad PHP de Mastodon. servidor PHP de Mastodon. Así que vamos a empezar: en primer lugar queremos un poco de andamiaje Laravel para disparar una solicitud a la API de Mastodon para crear un nuevo post.

Arrancar Laravel

No tiene mucho sentido escribir un párrafo entero sobre cómo instalar Laravel cuando la documentación es bastante completaasí que vamos a trabajar en la construcción de un comando para disparar una solicitud de API Mastodon. Usa la consola para crear un nuevo comando:

php artisan make:command PostToMastodonCommand

En el nuevo comando, voy a editar la firma (que es el nombre del comando a ejecutar desde la consola) y la descripción.

protected $signature = 'app:post-to-mastodon';

protected $description = 'Post a default message to Mastodon';

Para probar la ejecución, voy a escribir una cadena de marcador de posición y luego volcarlo cuando se ejecuta un comando. Este es el aspecto del método handle() método:

public function handle(): void  
{  
    $exampleMessage = "Hey! I'm writing a blog post on integrating Mastodon, Vonage, and Laravel.  
    If you see this, I've just fired an artisan command to the API. Nice.";  
  
    $this->info($exampleMessage);
}

Ejecute el comando en su terminal:

php artisan app:post-to-mastodon

Sale el mensaje en el terminal. Nada particularmente especial aquí, pero ahora es el momento de configurar Mastodon.

Configuración Mastodon

Vamos a configurar Mastodon para Laravel usando las convenciones de Laravel: lo único que realmente necesitamos para enviar un Toot es un token de acceso (las claves API para operaciones más avanzadas requieren pares de claves completos o rotación de claves porque el acceso se ha configurado vía. OAuth).

Nuestra primera parada es conseguir la clave de acceso. En tu Mastodon. Dirígete a tu panel de preferencias mientras estás conectado. Usted debe ser capaz de ver una Development pestaña:

Crear una nueva aplicación con acceso de lectura en el ámbito (esto viene por defecto). Una vez creada, lo que buscas está bajo Your access token:

Este es el valor que necesitaremos en la aplicación. Cópialo y vuelve a tu código.

En su archivo de configuración de Laravel, cree un nuevo archivo llamado mastodon.php y escribe el siguiente código:

<?php  
  
return [  
  
    /*  
    |----------------------------------------------------------------
    | Mastodon    
    |----------------------------------------------------------------
    |
    |
    */    
    
    'access_token' => env('MASTODON_ACCESS_TOKEN')  
];

La configuración ahora leerá su token de acceso de su archivo .env así que copia el archivo Laravel .env.example (si aún no lo has hecho) y crea tu archivo .env archivo. Allí, añadir nuestra nueva variable de entorno:

MASTODON_ACCESS_TOKEN=2sd09g-0h9hs-09ts-0risd-f9j4-s9d0g9s-0h8

Disparar un Toot con el mando

Nuestra última parte es conectar la variable config en el comando y enviarlo a nuestra instancia Mastodon. En el PostToMastodonCommand añade el siguiente código:

$response = Http::asForm()->withToken(config('mastodon.access_token'))->post('https://mymastodon.social/api/v1/statuses', [  
    'status' => $exampleMessage  
]);  
  
$this->info($response->body());

La fachada Http de Laravel nos da una forma bastante fluida de enviar la petición sin tener que trastear con la configuración de un cliente como Guzzle directamente. Desglosando la petición, tenemos los siguientes componentes:

• asForm(): La API de Mastodon para este punto final requiere que los datos de la solicitud se envíen como multipart/form-data.

• withToken() es una función que añade automáticamente un Bearer token al Authorization de la solicitud.

• config(mastodon.access_token) recupera nuestro token del archivo de configuración recién creado

• post() es el tipo de petición HTTP que necesitamos realizar

Dispara el comando en la consola:

y con suerte, obtendrá una respuesta HTTP200 de vuelta, y su Toot debería aparecer en Mastodon.

¿Y si... enviamos un SMS a Toot?

No hay absolutamente ningún razonamiento detrás de esto, aparte de "¿por qué no?". Nosotros podríamos enviar un mensaje de texto a un número y hacer que éste escupiera el contenido si quisiéramos... así que, ¡hagámoslo!

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Aquí necesitarás dos cosas: en primer lugar, una nueva aplicación creada en el panel y, en segundo lugar, un número de Vonage vinculado a la aplicación.

Ve a la pestaña Applications en tu panel de Vonage y haz clic en Crear aplicación:

Nuestra nueva aplicación va a utilizar el Messages API para recibir mensajes SMS, que luego se disparará webhooks para nuestra aplicación Laravel para escuchar. Active la Messages y rellena la URL de entrada/StatusURL con un marcador de posición por el momento.

Necesitaremos un número para conectar los mensajes entrantes a los webhooks de la aplicación. Crea tu aplicación, y entonces deberías ver la opción de Buy more Numbers. Es en este proceso donde puedes seleccionar un número, comprarlo y luego vincularlo a la aplicación. El resultado final en el panel de control de la aplicación debería ser el siguiente:

Enrutamiento de nuestra aplicación Laravel

La URL especificada en el campo 'InboundURL' del dashboard es donde nuestro webhook va a ser enviado, pero aún no hemos abierto una ruta en nuestra Aplicación Laravel.

El webhook está diseñado para interactuar con nuestra aplicación a nivel de API en lugar de la ruta web (que sería para cargar páginas, cuadros de mando, etc.). Por esta razón, queremos que nuestra nueva ruta esté en routes/api.php. Ábrelo y añade la ruta:

Route::post('/incoming', IncomingSMSController::class);

Espera, IncomingSMSController ¡todavía no existe! Tendrías razón: vamos a crearlo en el terminal:

Nuestro nuevo controlador va a manejar la solicitud webhook entrante, y luego usar el código existente que utilizamos para disparar un Toot a Mastodon. El controlador se parece a esto:

<?php  
  
namespace App\Http\Controllers;  
  
use Illuminate\Http\Request;  
use Illuminate\Support\Facades\Http;  
use Symfony\Component\HttpFoundation\Response;  
  
class IncomingSMSController extends Controller  
{  
    public function __invoke(Request $request)  
    {        $body = json_decode($request->getContent(), true, 512, JSON_THROW_ON_ERROR);  
        $message = $body['text'];  
  
        $response = Http::asForm()->withToken(config('mastodon.access_token'))->post('https://mymastodon.social/api/v1/statuses', [  
            'status' => $message  
        ]);  
  
        return response($response->body(), Response::HTTP_CREATED);  
    }}

Por lo tanto, lo que estamos haciendo aquí es reemplazar el mensaje de marcador de posición que enviamos a Mastodon originalmente en el comando con el contenido del texto SMS entrante.

Aquí falta una pieza importante: Vonage necesita una URL activa a la cual enviar el webhook. Entonces, ¿cómo lo hacemos?

En ejemplos anteriores que he escrito, he recurrido a ngrok como una excelente aplicación túnel para exponer tu pila local a Internet. Sin embargo, recientemente he empezado a usar algo más

Expose al rescate

Expose de Beyond Code se comporta esencialmente igual que ngrok; es una aplicación de túnel que permite exponer su aplicación web local a Internet. Puede instalarlo de varias maneras, pero podría decirse que la forma más sencilla será a través de. composer require global:

Deberás añadir el ejecutable a la ruta de tu sistema operativo. consulta la documentación aquí para ver cómo hacerlo.

Expose necesitará configurarse con un token de acceso - puedes seguir los pasos aquí para crear un token y asignarlo a tu copia.

Tenemos que seguir dos pasos: en primer lugar, enciende el servidor local en tu aplicación Laravel:

Y en segundo lugar, iniciamos Expose que nos dará un dominio para nuestra aplicación (el servidor incorporado de Laravel por defecto es 8000 como puerto):

Si todo va bien, debería ver el panel de control de Expose:

Puede ver que hay una URL de panel de control: Expose ejecuta una interfaz de usuario en el puerto 4040. Si navegas hasta ella, se te presentará un conjunto bastante bueno de herramientas para depurar:

Mantendremos esta ventana para que podamos ver nuestro webhook entrando. Nuestra configuración final es tomar nuestra nueva URL HTTPS pública y pegarla nuevamente en la configuración de la aplicación en el panel de Vonage:

Lo único importante aquí para nuestro caso de uso es que la URL de entrada coincida con la ruta Laravel que hemos definido. La URL de estado no es importante aquí ya que esto es para integraciones más profundas que escuchan cualquier cambio, fallos de entrega y problemas de red.

¡Txt me!

Todo está conectado: envíe un SMS con lo que desea mostrar en Mastodon y vea cómo funciona nuestro sistema.

¡Y aquí está nuestro toque!

Conclusión

La API de Mastodon es totalmente abierta por diseño, sin "características premium" debido a la naturaleza del software, que es FOSS primero. Teniendo esto en cuenta, no hay prácticamente ningún límite a lo que puedes hacer aquí - quería que esto fuera una breve introducción, pero en términos de prueba de concepto ya tengo transcripciones de voz utilizando la Voice API de Vonage para también Toot out grabaciones.

¿Se te ocurre algo más que puedas hacer con Laravel, Mastodon y Vonage? Contáctame, siempre estoy dispuesto a experimentar. Únete a la conversación en nuestro Slack de la comunidad de Vonage o contáctanos en Twitter.