Conversas omnicanal com a Vonage, a Postmark e a Hookdeck

Em um único dia, posso alternar entre SMS para conversar com um amigo, o WhatsApp para trocar novidades com a família, o Facebook Messenger para coordenar uma atividade comunitária e o e-mail para o trabalho. E o canal de comunicação preferido pode variar dependendo da pessoa, da hora do dia, da localização geográfica, da geração e da cultura. Não seria ótimo se houvesse um único aplicativo de comunicação que todos pudessem usar e que funcionasse bem em todos os canais de comunicação!

Conversas omnicanal — que permitem que uma conversa transite entre diferentes meios de comunicação — são uma possibilidade, mas há muito poucos guias que mostrem como colocá-las em prática. Portanto, neste tutorial, vamos explicar passo a passo como criar uma solução OmniText para possibilitar uma conversa por SMS usando a API de mensagens da Vonage Messages API e e-mail por meio da API de e-mail da Postmark. Também usaremos o Hookdeck, uma plataforma de mensagens assíncronas sem servidor, para receber webhooks e integrar o Vonage e o Postmark por meio de suas APIs.

Se você quiser apenas experimentar o OmniText, pode baixar o código, juntamente com instruções simplificadas, no repositório do OmniText no GitHub.

Visão geral do OmniText

Antes de apresentarmos um guia passo a passo para configurar e implementar a solução, segue aqui uma visão geral de como o OmniText funciona.

O Hookdeck baseia-se no conceito de conexões, que conectam uma entrada conhecida como fonte a uma saída chamada destino. Para dar suporte a uma conversa que envolva SMS e e-mail, precisamos de duas conexões que:

1. Receber um SMS e acionar o envio de um e-mail

2. Receber um e-mail e acionar um SMS

Connections in Hookdeck

Nesta configuração, ofereceremos suporte a uma única conversa entre um número de telefone e um endereço de e-mail. Para oferecer suporte a várias conversas com essa abordagem, seria necessário criar duas conexões para cada conversa. Conforme mencionado acima, é perfeitamente possível oferecer suporte a várias conversas, mas esse assunto não é abordado neste artigo.

Ambas as conexões utilizarão o Hookdeck transformações.

• A inbound-sms conexão transforma a carga útil do webhook de SMS recebido da Messages API da Vonage em uma carga útil usada para enviar um e-mail com o Postmark.

• A inbound-email conexão transforma o conteúdo do e-mail recebido do Postmark em uma estrutura exigida pela Messages API do Vonage para enviar um SMS

Ao enviar um e-mail, também vale a pena observar que, embora seja possível usar assuntos de e-mail e subendereçamento para permitir que um único endereço de e-mail faça parte de várias conversas, isso é um problema muito mais complexo no caso de números de telefone e mensagens SMS. Portanto, nesta solução, um número de telefone só pode estar associado a uma única conversa.

Pré-requisitos

Antes de começar, crie contas gratuitas nos serviços necessários para a solução OmniText e anote as respectivas credenciais e informações adicionais:

• Vonage: anote sua chave de API e seu segredo de API. Você também precisará adquirir um número de telefone para enviar e receber mensagens SMS.

• Carimbo postal: anote o token da API do seu servidor em Servidores > {Nome do seu servidor} > Tokens de API e o e-mail recebido em Servidores > {Nome do seu servidor} > Fluxo de entrada padrão > Configurações > Entrada > E-mail . Consulte a documentação do Postmark documentação sobre como configurar um servidor de entrada para obter mais detalhes. Além disso, lembre-se de “Verify sua assinatura” no Postmark, o que significa verificar seu endereço de e-mail.

• Hookdeck: basta criar a conta

Receber um SMS e acionar um e-mail

Vamos começar criando uma conexão que suporte o seguinte fluxo:

1. Um usuário envia um SMS para o seu número de telefone da API da Vonage

2. A API da Vonage aciona um webhook de SMS para o Hookdeck

3. O Hookdeck recebe os webhooks de SMS por meio de uma URL de origem e converte o conteúdo do SMS para um formato que pode ser usado para enviar um e-mail com o Postmark

4. O Hookdeck faz uma solicitação HTTP para uma URL de destino, o endpoint da API de e-mail da Postmark, para enviar um e-mail

5. Um segundo usuário recebe o e-mail

Acesse o painel do Hookdeck, selecione Conexõese clique no botão “+ Conexão” .

Na página “Criar conexão” , na seção Configurar uma fonte, chame a fonte inbound-sms.

Em Configurar um destino, defina o Nome como outbound-email.

Para o opção “Configurar um destino > URL do endpoint”, use o ponto de extremidade da API de e-mail da Postmark, https://api.postmarkapp.com/email.

Expandir Configurar um destino > Configuração avançada, selecione Chave de API no menu suspenso de autenticação, defina o Nome do parâmetro como X-Postmark-Server-Tokene use seu token de API do servidor Postmark como valor para Chave da API.

Authentication in Hookdeck for Postmark Request

Na seção seção “Definir regras de conexão” , clique em Transformar e, em seguida, “Criar nova transformação”, e você verá o editor de transformação no navegador.

Digite o seguinte na área de texto do código:

const smsToEmail = (request, context) => {
 const replyToEmail = process.env.REPLY_TO_EMAIL;
 const fromEmail = process.env.FROM_EMAIL;
 const toEmail = process.env.TO_EMAIL;
 const subject = process.env.SUBJECT;


 const domain = toEmail ? toEmail.replace(/.*@/, "") : "example.com";
 const conversationId = `<omnitext/conversation/1@${domain}>`;


 const postmarkSendEmailRequest = {
   From: fromEmail,
   To: toEmail,
   ReplyTo: replyToEmail,
   Subject: subject,
   TextBody: request.body.text,
   MessageStream: "outbound",


   Headers: [
     {
       Name: "Message-ID",
       Value: conversationId,
     },
   ],
 };


 request.body = postmarkSendEmailRequest;


 return request;
};


addHandler("transform", smsToEmail);

A maior parte do código está contida em uma função chamada smsToEmail. Aqui está uma explicação passo a passo do que o código faz:

Primeiro, você notará que o código de transformação recupera várias variáveis de ambiente usando a sintaxe process.env.VARIABLE_NAME. Isso utiliza as variáveis de ambiente de transformação do Hookdeck variáveis de ambiente de transformação do Hookdeck que são usadas para armazenar segredos.

Abra o menu suspenso e crie as seguintes variáveis usando os valores da seção Pré-requisitos:

• REPLY_TO_EMAIL: O e-mail do Postmark para garantir que as respostas por e-mail sejam encaminhadas ao Postmark e acionem um webhook

• FROM_EMAIL: Defina esse campo com o mesmo valor que REPLY_TO_EMAIL ou o e-mail com o qual você se cadastrou no Postmark. Se quiser permitir o envio de e-mails a partir de outros domínios, você precisará confirmar seu domínio no Postmark. Isso pode ser útil para ajudar os clientes de e-mail a identificar o contato em uma agenda de endereços.

• TO_EMAIL: O endereço de e-mail da pessoa que está do lado de quem recebe a mensagem na conversa.

• SUBJECT: O assunto a ser usado no e-mail. Você pode torná-lo mais dinâmico, se quiser.

Depois que as variáveis de ambiente forem recuperadas dentro de smsToEmail, uma conversationId variável recebe um valor com conteúdo e formato que garantem que os e-mails sejam mantidos na mesma sequência de mensagens dentro de um cliente de e-mail (para mais informações, consulte o artigo de suporte do Postmark sobre encadeamento de mensagens e esta publicação sobre envio de e-mails encadeados no Rails).

Em seguida, a carga útil da API de e-mail é criada e atribuída à postmarkSendEmailRequest variável. Os principais pontos a serem observados nessa carga são:

• TextBody é definido como o texto enviado na mensagem SMS

• MessageStream está configurado para outbound para informar ao Postmark que o fluxo transacional (de saída) deve ser usado para enviar o e-mail

• O Headers contêm um cabeçalho chamado Message-ID com o valor atribuído a partir do conversationId. Conforme mencionado, isso é usado para ajudar os clientes de e-mail a agrupar mensagens.

request.body recebe o valor da carga útil do e-mail do Postmark, postmarkSendEmailRequest. Esse valor é então utilizado na solicitação subsequente enviada ao destino da conexão, o endpoint da API de e-mail do Postmark.

O valor transformado request é retornado pela função e utilizado na solicitação à API do Postmark, conforme definido no destino da conexão. A addHandler chamada instrui o Hookdeck a chamar o smsToEmail sempre que um transform dever ser processado.

Clique Confirmar, nomeie a transformação vonage-sms-to-postmark-emaile clique em Confirmar para voltar à página de configuração da conexão.

Em Definir nome da conexão, digite sms-to-email. Por fim, clique em +Criar para criar a conexão.

Successful Connection Created

Copie a URL de origem da caixa de diálogo exibida e acesse o painel das APIs da Vonage.

No painel da API da Vonage, selecione o Applications à esquerda e clique em + Criar um novo aplicativo.

Dê um nome ao seu aplicativo sms-to-email. Na seção seção “Recursos” , as Mensagense cole a URL de origem do Hookdeck no campo URL de entrada e URL de status . Por fim, clique em Gerar novo aplicativo.

Add Hookdeck webhook to Messages API Application

Na próxima tela, você verá seu número de telefone da Vonage. Vincule-o à aplicação que acabou de criar clicando em “Vincular”.

Link Your Messages API to Your Number

Agora, envie um SMS para o seu número da Vonage.

Test Your First Working OmniText

Volte ao painel do Hookdeck e, assim que o Hookdeck receber o webhook de SMS, a interface do usuário será atualizada para exibir o evento de webhook recebido da seguinte forma:

Hookdeck Successful Event Fired

Clique “Ver todos os eventos” e selecione o evento na tabela para ver mais detalhes.

Detailed Hookdeck Events Dashboard

Em seguida, verifique seu e-mail:

Successful SMS to Email

É isso aí. A funcionalidade de envio de SMS para e-mail já está em funcionamento.

Receber um e-mail e acionar um SMS

Agora, para criar a conexão que sustenta o fluxo, da mesma forma que antes, mas na ordem inversa:

1. Um usuário envia um e-mail para um endereço de e-mail associado ao Postmark

2. O Postmark aciona um webhook de e-mail recebido

3. O Hookdeck recebe o webhook de e-mail recebido e converte a carga útil de uma mensagem SMS enviada pela SMS API do Voange

4. O Hookdeck faz uma solicitação HTTP para uma URL de destino, o endpoint da Messages API do Vonage, para enviar um SMS

5. Um segundo usuário recebe a mensagem SMS

Como antes, acesse o painel do Hookdeck, selecione Conexões e clique na botão “+ Conexão” .

Na página “Criar conexão” , na seção seção “Configurar uma fonte” , atribua à fonte o Nome inbound-email.

Em Configurar um destino, use o Nome outbound-sms e defina a URL do ponto de extremidade para o ponto de extremidade da Messages API do Vonage, https://api.nexmo.com/v1/messages.

Expandir Configurar um destino > Configuração avançada, selecione Autenticação Básica na seção menu suspenso e use sua chave de API da Vonage como Nome de usuário e o segredo da API da Vonage como sua Senha.

Vonage API Authentication in Hookdeck

Na seção seção “Definir regras de conexão” , clique em Transformar e, em seguida, “Criar nova transformação”e, como antes, você verá o editor de transformação no navegador.

Copie e cole o seguinte código de transformação no editor:

const emailToSms = (request, context) => {
 const toNumber = process.env.TO_NUMBER;
 const fromNumber = process.env.FROM_NUMBER;


 const vonageRequestPayload = {
   message_type: "text",
   text: request.body.StrippedTextReply || request.body.TextBody,
   to: toNumber,
   from: fromNumber,
   channel: "sms",
 };
 request.body = vonageRequestPayload;


 return request;
};


addHandler("transform", emailToSms);

A maior parte do código está em uma função. Desta vez, chamada emailToSms.

Como antes, comece definindo as seguintes variáveis de ambiente por meio do menu suspenso :

• TO_NUMBER: O número de telefone do destinatário da mensagem SMS

• FROM_NUMBER: O número de telefone da Vonage usado para enviar o SMS

Os números de telefone devem ser formatados com o código internacional do país, mas sem nenhum + ou 00 no início

O restante do código faz o seguinte:

É vonageRequestPayload variável é criada e contém a carga útil da solicitação da Messages API. A message_type tem o valor de text, e a channel tem o valor de sms para indicar que uma mensagem SMS será enviada. A text propriedade é o conteúdo do SMS, e o valor é definido como request.body.StrippedTextReply ou, se não estiver preenchido, o request.body.TextBody. O StrippedTextReply é o corpo do e-mail de uma resposta contendo apenas a parte da nova mensagem, e não toda a conversa por e-mail.

A request.body recebe o valor da vonageRequestPayload variável, e a solicitação é devolvida para ser usada na solicitação ao destino da conexão, o endpoint da Messages API do Vonage. A addHandler chamada instrui o Hookdeck a chamar o emailToSms sempre que um transform dever ser processado.

Clique Confirmar, nomeie a transformação postmark-email-to-vonage-sms e clique em Confirmar para voltar à página de configuração da conexão.

Em Definir nome da conexão, digite email-to-sms. Por fim, clique em +Criar para criar a conexão.

Email to SMS Connection Created

Copie a URL de origem da caixa de diálogo, acesse o painel do Postmark e vá para Servidores > {Nome do seu servidor} > Fluxo de entrada padrão > Configurações . Role a página para baixo até a seção Webhook de entrada , cole a URL no campo Webhook de entrada e Salve as alterações.

Postmark Webhook Connecting to Hookdeck

Envie um e-mail para o endereço de e-mail de recebimento do Postmark. Você pode fazer isso respondendo ao e-mail que recebeu na etapa anterior.

Successful Programmatic Email Thread Reply

Depois de enviar o e-mail, volte ao painel do Hookdeck e você verá que o evento do webhook foi recebido do Postmark.

Hookdeck Successful Email to SMS Event

Clique “Ver todos os eventos”, selecione o evento na tabela e verifique os detalhes do webhook de entrada do Postmark.

Hookdeck Email to SMS Events Detailed

Verifique suas mensagens SMS para ver o corpo do e-mail contido na mensagem SMS:

Successful Email to SMS

Você também pode tentar responder novamente por SMS para garantir que a conversa seja exibida em forma de thread no seu cliente de e-mail:

Successful SMS reply to Email Thread

Então, no seu e-mail, você deve ver a conversa:

Successful Threading in Email From SMS

Conclusão

Neste tutorial, abordamos a criação de uma conexão no Hookdeck que recebe um webhook de SMS da Messages API do Vonage, transformando a carga útil em uma solicitação à API de e-mail do Postmark e enviando o corpo da mensagem SMS como o corpo de um e-mail. Em seguida, criamos uma segunda conexão no Hookdeck que recebe um webhook de e-mail do Postmark. Transformamos a carga útil em uma solicitação para a Messages API do Vonage e enviamos o corpo do e-mail como o conteúdo de uma mensagem SMS. Em todos os casos, as credenciais da API são armazenadas com segurança no Hookdeck.

E com isso, você acaba de criar uma solução de conversação omnicanal, que integra SMS e e-mail.

O repositório do OmniText no GitHub contém o código que mostra como criar scripts para configurar as conexões no Hookdeck. Fique à vontade para experimentar isso como uma forma alternativa de trabalhar com o Hookdeck.

Este artigo explicou como usar o painel do Hookdeck para implementar a funcionalidade necessária para dar suporte a uma única conversa entre um número de telefone e um e-mail predefinidos. No entanto, tudo o que fizemos pode ser realizado usando a API do Hookdeck. Criar novas conexões programaticamente é uma abordagem possível para dar suporte a múltiplas conversas; ou você pode armazenar uma tabela bidirecional de correspondência entre e-mail e SMS ao ocorrer algum tipo de evento de registro de conversa.

Se você está procurando uma solução low-code/no-code, dê uma olhada no Vonage API Studio.

Algumas outras coisas que você também pode experimentar com as tecnologias utilizadas neste artigo são:

• Adicionando verificação de webhooks aos webhooks de entrada do Postmark e do Vonage Messages

• Usando o CLI do Hookdeck para receber os webhooks em seu ambiente de desenvolvimento local (semelhante ao que o ngrok é mais conhecido por fazer)

• Criando uma segunda, terceira e enésima conversa. Fique à vontade para discutir possíveis soluções para isso criar uma issue no repositório do OmniText.

• Adicionar suporte a outros canais de mensagens, como WhatsApp, Facebook Messenger e Viber, usando a Messages API for Vonage

Seja lá o que você decidir fazer a seguir, queremos saber! Junte-se a nós no Slack da Comunidade de Desenvolvedores da Vonage ou mande uma mensagem para a gente no X, antes conhecido como Twitter.