Toot avec Laravel, Vonage et Mastodon

Vous avez peut-être entendu parler de Mastodon ces derniers mois, compte tenu des changements qui se produisent dans le monde des médias sociaux, mais qu'est-ce que c'est et que puis-je faire avec ?

Dans cet article, je vais utiliser Vonage, Laravel et Expose pour recevoir un SMS entrant envoyé depuis votre téléphone pour le " tooter " sur un compte Mastodon.

Qu'est-ce que Mastodon ?

Mastodon est une plateforme de médias sociaux à code source ouvert.. En termes de comportement et d'interface utilisateur, elle est très similaire à Twitter (l'équivalent d'un "tweet" est un "toot", par exemple). Il y a cependant des différences majeures ; j'ai mentionné qu'il s'agit d'un logiciel libre, mais il fonctionne également comme un réseau "décentralisé". C'est cet aspect qui le rend unique : l'idée est que vous pouvez créer votre propre instance de Mastodon, qui est connectée à "l'univers fédéral" (c'est-à-dire tous les autres serveurs Mastodon). Le résultat final est que vous, en tant qu'utilisateur, pouvez choisir une instance Mastodon à laquelle vous inscrire, mais vous pouvez voir le contenu de tous les autres utilisateurs à travers la plateforme.

À la surprise de personne, le taux d'inscription à Mastodon a été phénoménal : rien qu'en novembre 2022, il a accueilli un million de nouveaux utilisateurs.

Je suppose qu'il est assez poétique que la mascotte de Mastodon soit un Mastodon, un parent éloigné de l'éléphant, étant donné que je suis d'une part le spécialiste PHP de l'équipe des relations avec les développeurs de Vonage, et d'autre part un utilisateur sur le serveur communautaire PHP de Mastodon. Commençons donc : tout d'abord, nous avons besoin d'un échafaudage Laravel pour envoyer une requête à l'API de Mastodon afin de créer un nouveau message.

Démarrer Laravel

Cela n'a pas beaucoup de sens d'écrire un paragraphe entier sur la façon d'installer Laravel quand la documentation est assez complèteNous allons donc travailler sur la construction d'une commande pour lancer une requête API Mastodon. Utilisez la console pour créer une nouvelle commande :

php artisan make:command PostToMastodonCommand

Dans la nouvelle commande, je vais modifier la signature (qui est le nom de la commande à exécuter depuis la console) et la description.

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

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

Pour tester l'exécution, je vais écrire une chaîne de caractères et la vider lors de l'exécution d'une commande. Voici à quoi ressemble la méthode handle() se présente comme suit :

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);
}

Exécutez la commande dans votre terminal :

php artisan app:post-to-mastodon

Le message s'affiche dans le terminal. Rien de particulier ici, mais il est temps de configurer Mastodon.

Configuration de Mastodon

Nous allons configurer Mastodon pour Laravel en utilisant les conventions de Laravel : la seule chose dont nous avons besoin pour envoyer un Toot est un jeton d'accès (les clés API pour des opérations plus avancées nécessitent des paires de clés complètes ou une rotation des clés parce que l'accès a été configuré via . OAuth).

La première étape consiste à obtenir la clé d'accès. Dans votre Mastodon. Allez dans votre panneau de préférences lorsque vous êtes connecté. Vous devriez pouvoir voir un Development onglet :

Créez une nouvelle application avec un accès en lecture dans le champ d'application (par défaut). Une fois créée, ce que vous recherchez est sous Your access token:

C'est la valeur dont nous aurons besoin dans l'application. Copiez-la, puis retournez à votre code.

Dans votre fichier de configuration Laravel, créez un nouveau fichier nommé mastodon.php et écrivez le code suivant :

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

La configuration va maintenant lire votre jeton d'accès depuis votre fichier .env donc copiez votre fichier Laravel .env.example (si ce n'est pas déjà fait) et créez votre fichier .env et créez votre fichier Dans ce fichier, ajoutez notre nouvelle variable d'environnement :

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

Tirer un coup de feu avec la commande

Notre dernière partie consiste à intégrer la variable de configuration dans la commande et à l'envoyer à notre instance de Mastodon. Dans le PostToMastodonCommand ajoutez le code suivant :

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

La façade Http de Laravel nous donne un moyen assez fluide d'envoyer la requête sans avoir à configurer directement un client tel que Guzzle. En décomposant la requête, nous avons les composants suivants :

• asForm(): L'API de Mastodon pour ce point de terminaison exige que les données de la demande soient envoyées sous forme de multipart/form-data.

• withToken() est une fonction astucieuse qui permet d'ajouter automatiquement un Bearer à l'élément Authorization de la requête.

• config(mastodon.access_token) récupère notre jeton dans le fichier de configuration nouvellement créé

• post() est le type de requête HTTP que nous devons effectuer

Envoyez la commande dans la console :

et avec un peu de chance, vous obtiendrez une réponse HTTP200 en retour, et votre Toot devrait apparaître dans Mastodon.

Et si nous envoyions plutôt un SMS à Toot ?

Il n'y a absolument aucun raisonnement derrière cela, si ce n'est "pourquoi pas ?". Nous pourrions envoyer un texte à un numéro et lui demander d'en égrener le contenu si nous le souhaitions... alors, faisons-le !

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.

Vous aurez besoin de deux choses : premièrement, une nouvelle application créée dans le tableau de bord, et deuxièmement un numéro Vonage lié à l'application.

Allez à l'onglet Applications dans votre tableau de bord Vonage, et cliquez sur Créer une application :

Notre nouvelle application va utiliser l'API Messages pour recevoir des SMS, qui déclencheront ensuite des webhooks que notre application Laravel pourra écouter. Basculez la capacité Messages et remplissez les champs Inbound URL/StatusURL avec un placeholder pour le moment ; nous y reviendrons prochainement.

Nous aurons besoin d'un numéro pour connecter les messages entrants aux webhooks de l'application. Créez votre application, et vous devriez voir l'option de Buy more Numbers. C'est ce processus qui vous permet de sélectionner un numéro, de l'acheter, puis de le lier à l'application. Votre résultat final dans le tableau de bord de l'application devrait ressembler à ceci :

Routage de notre application Laravel

L'URL spécifiée dans le champ 'InboundURL' du tableau de bord est l'endroit où notre webhook va être envoyé, mais nous n'avons pas encore ouvert de route dans notre Application Laravel.

Le webhook est conçu pour interagir avec notre application au niveau de l'API plutôt qu'au niveau du routage web (qui consisterait à charger des pages, des tableaux de bord, etc.) Pour cette raison, nous voulons que notre nouvelle route soit dans routes/api.php. Ouvrez ce fichier, puis ajoutez la route :

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

Attendez, IncomingSMSController n'existe pas encore ! Vous avez raison : créons-le dans le terminal :

Notre nouveau contrôleur va gérer la demande de webhook entrante, puis utiliser le code existant que nous avons utilisé pour envoyer un Toot à Mastodon. Le contrôleur ressemble à ceci :

<?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);  
    }}

Ce que nous faisons ici, c'est remplacer le message fictif que nous avons envoyé à Mastodon dans la commande initiale par le contenu du texte du SMS entrant.

Il y a une pièce manquante importante ici : Vonage a besoin d'une URL en direct pour envoyer ce webhook. Alors, comment faire ?

Dans les exemples précédents, j'ai eu recours à ngrok comme une excellente application tunnel pour exposer votre pile locale à l'internet. Cependant, j'ai récemment commencé à utiliser quelque chose d'autre

Expose à la rescousse !

Expose de Beyond Code se comporte essentiellement de la même manière que ngrok ; il s'agit d'une application tunnel qui permet à votre application web locale d'être exposée à l'internet. Vous pouvez l'installer de plusieurs façonsVous pouvez l'installer de plusieurs façons, mais la façon la plus simple est sans doute de le faire via. composer require global:

Vous devrez ajouter l'exécutable au chemin d'accès de votre système d'exploitation. consultez la documentation ici pour savoir comment faire.

Expose devra être configuré avec un jeton d'accès - vous pouvez suivre les étapes ici pour créer un jeton et l'attribuer à votre copie.

Nous devons procéder en deux étapes : tout d'abord, démarrer le serveur local dans votre application Laravel :

Ensuite, nous lançons Expose qui nous donnera un domaine pour notre application (le serveur intégré de Laravel utilise par défaut le port 8000) :

Si tout va bien, vous devriez maintenant voir le tableau de bord Expose :

Vous pouvez voir qu'il y a une URL de tableau de bord : Expose exécute une interface utilisateur sur le port 4040. Si vous vous y rendez, vous obtiendrez un ensemble d'outils de débogage assez intéressants :

Nous garderons cette fenêtre afin de voir notre webhook arriver. Notre dernier élément de configuration consiste à prendre notre nouvelle URL HTTPS publique et à la coller dans les paramètres de l'application dans le tableau de bord de Vonage :

La seule chose importante pour notre cas d'utilisation est que l'URL entrante corresponde à la route Laravel que nous avons définie. L'URL de statut n'est pas importante ici car elle est destinée à des intégrations plus profondes qui sont à l'écoute de tous les changements, des échecs de livraison et des problèmes de réseau.

Txt me !

Tout est connecté : envoyez un SMS avec ce que vous voulez afficher dans Mastodon, et regardez notre installation faire son travail !

Et voici notre toot !

Conclusion

L'API de Mastodon est entièrement ouverte par conception, sans "fonctionnalités premium" en raison de la nature du logiciel qui est d'abord un logiciel libre. En gardant cela à l'esprit, il n'y a pratiquement aucune limite à ce que vous pouvez faire ici - je voulais que ce soit une brève introduction, mais en termes de preuve de concept, j'ai déjà obtenu des transcriptions vocales utilisant l'API Voice de Vonage pour également Toot out des enregistrements.

Vous avez pensé à quelque chose d'autre que vous pourriez faire avec Laravel, Mastodon et Vonage ? Contactez-moi, je suis toujours prêt à expérimenter. Joignez-vous à la conversation sur notre Communauté Vonage Slack ou sur sur Twitter.