Use o Toot com Laravel, Vonage e Mastodon

Talvez você tenha ouvido falar do Mastodon nos últimos meses, devido às mudanças que estão ocorrendo no mundo das redes sociais, mas o que é isso e o que posso fazer com ele?

Neste artigo, vou usar o Vonage, o Laravel e o Expose para receber uma mensagem SMS enviada do seu celular e publicá-la em uma conta do Mastodon.

O que é o Mastodon?

O Mastodon é uma plataforma de mídia social de código aberto. Em termos de funcionamento e interface do usuário, é muito semelhante ao Twitter (o equivalente a um “tweet” é um “toot”, por exemplo). Há, no entanto, diferenças significativas; já mencionei que é de código aberto, mas também funciona como uma rede “descentralizada”. É esse aspecto que a torna única: a ideia é que você possa criar sua própria instância do Mastodon, conectada ao “Fediverso” (ou seja, a todos os outros servidores do Mastodon). O resultado final é que você, como usuário, pode escolher uma instância do Mastodon para se cadastrar, mas pode ver o conteúdo de todos os outros usuários em toda a plataforma.

Para surpresa de provavelmente ninguém, a taxa de cadastros no Mastodon tem sido fenomenal: só em novembro de 2022, a plataforma recebeu um milhão de novos usuários.

Acho que é bem poético que o mascote do Mastodon seja um mastodonte, um parente distante do elefante, considerando que, em primeiro lugar, sou o especialista em PHP na Equipe de Relações com Desenvolvedores da Vonage e, em segundo lugar, sou usuário do servidor da comunidade PHP do Mastodon servidor comunitário do Mastodon. Então, vamos começar: primeiro, precisamos de um scaffolding do Laravel para enviar uma solicitação à API do Mastodon para criar uma nova postagem.

Inicializando o Laravel

Não faz muito sentido escrever um parágrafo inteiro sobre como instalar o Laravel quando a documentação já é bastante completa; então, vamos nos concentrar em criar um comando para enviar uma solicitação à API do Mastodon. Use o console para criar um novo comando:

php artisan make:command PostToMastodonCommand

No novo comando, vou editar a assinatura (que é o nome do comando a ser executado no console) e a descrição.

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

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

Para testar a execução, vou escrever uma string provisória e, em seguida, exibi-la ao executar um comando. Veja como fica o 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);
}

Execute o comando no seu terminal:

php artisan app:post-to-mastodon

A mensagem aparece no terminal. Nada de muito especial aqui, mas agora é hora de configurar o Mastodon.

Configuração do Mastodon

Vamos configurar o Mastodon para o Laravel usando as convenções do Laravel: a única coisa de que realmente precisamos para enviar um Toot é um token de acesso (as chaves de API para operações mais avançadas exigem pares completos de chaves ou a rotação de chaves, pois o acesso foi configurado via OAuth).

Nosso primeiro passo é obter a chave de acesso. No seu Mastodon, acesse o painel de preferências enquanto estiver conectado. Você deverá ver uma Development aba:

Crie uma nova aplicação com acesso de leitura no escopo (essa é a configuração padrão). Depois de criada, o que você está procurando está em Your access token:

Esse é o valor de que precisaremos no aplicativo. Copie-o e, em seguida, volte ao seu código.

No seu arquivo de configuração do Laravel, crie um novo arquivo chamado mastodon.php e escreva o seguinte código:

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

A configuração agora lerá seu token de acesso do seu .env arquivo; portanto, copie o arquivo Laravel incluído .env.example (se ainda não tiver feito isso) e crie seu .env arquivo. Nele, adicione nossa nova variável de ambiente:

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

Envie um Toot com o comando

Nossa última etapa é vincular a variável de configuração ao comando e enviá-lo para nossa instância do Mastodon. No PostToMastodonCommand handler, adicione o seguinte código:

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

A fachada Http do Laravel nos oferece uma maneira bastante simples de enviar a solicitação sem precisar se preocupar em configurar diretamente um cliente como o Guzzle. Analisando a solicitação, temos os seguintes componentes:

• asForm(): A API do Mastodon para esse endpoint exige que os dados da solicitação sejam enviados como multipart/form-data.

• withToken() é uma função bacana para adicionar automaticamente um Bearer token à Authorization da solicitação.

• config(mastodon.access_token) recupera nosso token do arquivo de configuração recém-criado

• post() é o tipo de solicitação HTTP que precisamos fazer

Execute o comando no console:

E, com sorte, você receberá uma resposta HTTP 200, e seu Toot deverá aparecer no Mastodon.

E se a gente... enviasse um SMS para o Toot, em vez disso?

Não há absolutamente nenhum motivo para isso, a não ser “por que não?”. Nós poderíamos enviar uma mensagem de texto para um número e fazer com que ele reproduza o conteúdo, se quiséssemos... então, vamos fazer isso!

Você precisará de duas coisas: primeiro, um novo aplicativo criado no painel de controle; e, segundo, um número da Vonage vinculado ao aplicativo.

Acesse a Applications aba no seu Painel da Vonage e clique em “Criar Application”:

Nosso novo aplicativo utilizará a Messages API para receber mensagens SMS, que, por sua vez, acionarão webhooks para que nosso aplicativo Laravel os monitore. Ative a Messages recurso e preencha os campos URL de entrada/StatusURL com um espaço reservado por enquanto; voltaremos a isso em breve.

Precisaremos de um número para conectar as mensagens recebidas aos webhooks do aplicativo. Crie seu aplicativo e, em seguida, você deverá ver a opção para Buy more Numbers. É nesse processo que você pode selecionar um número, comprá-lo e, em seguida, vinculá-lo ao aplicativo. O resultado final no painel do aplicativo deve ficar assim:

Roteamento em nossa aplicação Laravel

A URL especificada no campo “InboundURL” no painel é para onde nosso webhook será enviado, mas ainda não abrimos uma rota em nossa aplicação Laravel.

O webhook foi projetado para interagir com nosso aplicativo no nível da API, e não por meio do roteamento da web (que serviria para carregar páginas, painéis etc.). Por esse motivo, queremos que nossa nova rota fique em routes/api.php. Abra esse arquivo e adicione a rota:

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

Espere aí, IncomingSMSController isso ainda não existe! Você está certo: vamos criá-lo no terminal:

Nosso novo controlador vai processar a solicitação de webhook recebida e, em seguida, utilizar o código já existente que usamos para publicar um Toot no Mastodon. O controlador tem a seguinte aparência:

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

Então, o que estamos fazendo aqui é substituir a mensagem provisória que enviamos originalmente ao Mastodon no comando pelo conteúdo da mensagem de SMS recebida.

Falta aqui um elemento importante: a Vonage precisa de uma URL ativa para a qual enviar esse webhook. Então, como fazemos isso?

Nos exemplos anteriores que escrevi, recorri ao ngrok como um excelente aplicativo de tunelamento para expor sua pilha local à internet. No entanto, recentemente comecei a usar outra coisa

Expose ao resgate!

O Expose from Beyond Code funciona basicamente da mesma forma que o ngrok; é um aplicativo de túnel que permite que sua aplicação web local seja exposta à internet. Você pode instalá-lo de várias maneiras, mas, sem dúvida, a maneira mais simples será por meio de. composer require global:

É recomendável adicionar o executável ao caminho do seu sistema operacional — consulte a documentação aqui para saber como fazer isso.

O Expose precisará ser configurado com um token de acesso — você pode seguir as etapas descritas aqui para criar um token e atribuí-lo à sua instância.

Precisamos seguir duas etapas: primeiro, iniciar o servidor local no seu aplicativo Laravel:

E, em segundo lugar, iniciamos o Expose, que nos fornecerá um domínio para nosso aplicativo (o servidor integrado do Laravel usa a porta 8000 por padrão):

Se tudo correr bem, você deverá ver agora o painel do Expose:

Você pode ver que há uma URL do painel: o Expose executa uma interface de usuário na porta 4040. Se você acessar essa URL, encontrará um conjunto bastante interessante de ferramentas para depuração:

Vamos manter essa janela aberta para podermos ver quando nosso webhook chegar. O último passo da configuração é pegar nossa nova URL pública HTTPS e colá-la nas configurações do aplicativo no Painel do Vonage:

O único aspecto importante aqui para o nosso caso de uso é que a URL de entrada corresponda à rota do Laravel que definimos. A URL de status não é relevante neste contexto, pois se destina a integrações mais avançadas que monitoram eventuais alterações, falhas na entrega e problemas de rede.

Manda uma mensagem pra mim!

Tudo está interligado: envie um SMS com o que você quer exibir no Mastodon e veja nossa configuração entrar em ação!

E aqui está o nosso “toot”!

Conclusão

A API do Mastodon é totalmente aberta por padrão, sem “recursos premium”, devido à natureza do software, que prioriza o FOSS. Levando isso em conta, praticamente não há limites para o que você pode fazer aqui — eu queria que esta fosse uma breve introdução, mas, em termos de prova de conceito, já consegui transcrições de voz usando a Voice API da Vonage para também publicar gravações no Toot.

Pensou em mais alguma coisa que você poderia fazer com o Laravel, o Mastodon e o Vonage? Me manda uma mensagem, estou sempre disposto a experimentar. Venha participar da conversa na nossa Slack da Comunidade Vonage ou entre em contato conosco no Twitter.