Introdução

A SMS API da Vonage permite que você envie e receba mensagens de texto de e para usuários em todo o mundo, utilizando nossas APIs REST. Neste tutorial, vamos nos concentrar no envio e recebimento de mensagens SMS e no gerenciamento de recibos de entrega com o Next.js, utilizando a SMS API. O Next.js é um framework React para a criação de aplicativos web full-stack. Ele utiliza componentes React para o desenvolvimento da interface do usuário e incorpora recursos adicionais e otimizações por meio do Next.js. Se você estiver interessado em saber mais, acesse a documentação da SMS API da Vonage.

Resumo: Se você quiser pular essa parte e ir direto para a implantação, pode encontrar todo o código do aplicativo no GitHub.

Pré-requisitos

Este tutorial pressupõe que você tenha conhecimentos básicos sobre Git, Next.js, React e JavaScript. Antes de começar, certifique-se de ter o seguinte:

• Account da API da Vonage - Acesse o painel da API da Vonage para localizar sua chave de API e seu segredo de API, que podem ser encontrados na parte superior da página.

• Número virtual da Vonage - Alugue um número de telefone virtual para enviar ou receber mensagens e chamadas telefônicas.

• Node.js 18.17 ou posterior — O Node.js é um ambiente de execução de JavaScript de código aberto e multiplataforma.

• Plataforma de implantação, como Vercel, Netlify, etc. — Configuraremos webhooks para as URLs que recebem SMS de entrada e confirmações de entrega. Dessa forma, poderemos receber SMS e processar as confirmações de entrega.

Como enviar um SMS com o Next.js

Na primeira parte deste tutorial, vamos explorar como enviar mensagens de texto usando o Next.js. Usaremos a SMS API da Vonage para interagir com o Next.js. Para enviar um SMS com o Next.js e a SMS API da Vonage, siga estas instruções:

1. Como criar um novo projeto Next.js

2. Como declarar variáveis de ambiente

3. Como instalar o SDK do Vonage para Node.js

4. Como instalar a biblioteca de validação Zod

5. Como criar um formulário exclusivo para o servidor

6. Como executar o servidor de desenvolvimento

7. Como fazer a implantação no Vercel

1. Como criar um novo projeto Next.js

Para criar um aplicativo Next.js, execute:

Durante a instalação, você verá as seguintes instruções:

Neste tutorial, vamos usar o App Router e JavaScript; portanto, você pode escolher as mesmas respostas de acima. Após as instruções, create-next-app será criada uma pasta com o nome do seu projeto e as dependências necessárias serão instaladas.

2. Como declarar variáveis de ambiente

Recupere sua chave de API e seu segredo de API nas suas configurações da API; além disso, obtenha seu número virtual na página de Numberse crie um .env.local arquivo com as seguintes variáveis de ambiente:

VONAGE_API_KEY=your-vonage-api-key
VONAGE_API_SECRET=your-api-secret
VONAGE_VIRTUAL_NUMBER=your-virtual-number

Para alugar um número virtual da Vonage:

1. Faça login no painel do desenvolvedor.

2. No menu de navegação à esquerda, clique em Numbers e, em seguida, Comprar números.

3. Escolha os atributos de que você precisa e, em seguida, clique em Pesquisar.

   1. Neste tutorial, precisamos apenas da funcionalidade de SMS. Mas você também pode usar o mesmo número para adicionar outras funcionalidades de voz!

4. Clique no botão “Comprar” ao lado do número desejado e confirme sua compra.

5. Seu número virtual agora está listado em Seus números.

Veja alugue um número virtual.

3. Como instalar o SDK do Vonage para Node.js

Vamos usar o SDK do Vonage para Node.js. É muito fácil enviar um SMS com o Next.js.

Para instalar o SDK do Node.js, execute:

4. Como instalar a biblioteca de validação Zod

O Zod é uma biblioteca de declaração e validação de esquemas que prioriza o TypeScript. Vamos usá-la para verificar os valores após o envio do formulário. Mas isso não é obrigatório; você pode pular essa etapa se quiser.

Para instalar o Zod, execute:

5. Como criar um formulário exclusivo para o servidor

Crie uma nova pasta chamada lib dentro de /app. Em seguida, crie um novo send-sms.js arquivo dentro da lib pasta com o seguinte conteúdo:

"use server";

import { revalidatePath } from "next/cache";
import { Vonage } from "@vonage/server-sdk";

Após importar as dependências, inicialize a biblioteca do nó Vonage instalada anteriormente:

const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
});

const from = process.env.VONAGE_VIRTUAL_NUMBER;

Em seguida, inicialize a biblioteca do nó Vonage; vamos criar uma função assíncrona chamada sendSMS:

export async function sendSMS(prevState, formData) {
  try {
    const vonage_response = await vonage.sms.send({
      to: formData.get("number"),
      from,
      text: formData.get("text"),
    }); 

    revalidatePath("/");
    return {
      response:
        vonage_response.messages[0].status === "0"
          ? `🎉 Message sent successfully.`
          : `There was an error sending the SMS. ${
              // prettier-ignore
              vonage_response.messages[0].error-text
            }`,
    };
  } catch (e) {
    return {
      response: `There was an error sending the SMS. The error message: ${e.message}`,
    };
  }
}

Para enviar uma mensagem SMS usando a SMS API, utilizaremos o vonage.messages.send método da biblioteca Vonage para Node.js. Esse método aceita objetos como parâmetros que contêm informações sobre o destinatário, o remetente e o conteúdo. A SMS API possui dois tipos de resposta (vonage_response), sendo uma de mensagem enviada e a outra de erro. Consulte Respostas de SMS.

Exemplo de resposta para a mensagem “Enviado”:

{
   "message-count": "1",
   "messages": [
      {
         "to": "447700900000",
         "message-id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "status": "0",
         "remaining-balance": "3.14159265",
         "message-price": "0.03330000",
         "network": "12345",
         "client-ref": "my-personal-reference",
         "account-ref": "customer1234"
      }
   ]
}

Exemplo de resposta para o erro:

{
   "message-count": "1",
   "messages": [
      {
         "status": "2",
         "error-text": "Missing to param"
      }
   ]
}

Vamos invalidar um segmento inteiro da rota com revalidatePath, o que permite limpar os dados armazenados em cache sob demanda para um caminho específico. Ele não retorna nenhum valor. Consulte revalidatePath.

Para uma validação mais avançada no lado do servidor, use a biblioteca Zod. Se você a utilizar, o send-sms.js arquivo deve ficar assim:

"use server";

import { revalidatePath } from "next/cache";
import { Vonage } from "@vonage/server-sdk";
import { z } from "zod";

const vonage = new Vonage({
  apiKey: process.env.VONAGE_API_KEY,
  apiSecret: process.env.VONAGE_API_SECRET,
});

const from = process.env.VONAGE_VIRTUAL_NUMBER;

const schema = z.object({
  number: z
    .string()
    .regex(new RegExp(/^\d{10,}$|^(\d{1,4}-)?\d{10,}$/), "Invalid Number!"),
  text: z.string().min(1, "Type something, please!").max(140, "Too long text!"),
});

export async function sendSMS(prevState, formData) {
  try {
    const data = schema.parse({
      number: formData.get("number"),
      text: formData.get("text"),
    });

    const vonage_response = await vonage.sms.send({
      to: data.number,
      from,
      text: data.text,
    }); 

    revalidatePath("/");
    return {
      response:
        vonage_response.messages[0].status === "0"
          ? `🎉 Message sent successfully.`
          : `There was an error sending the SMS. ${
              // prettier-ignore
              vonage_response.messages[0].error-text
            }`,
    };
  } catch (e) {
    return {
      response: `There was an error sending the SMS. The error message: ${e.message}`,
    };
  }
}

Para a interface do usuário, crie um novo send-form.jsx arquivo dentro de /app com o seguinte conteúdo:

"use client";

import { sendSMS } from "@/app/lib/send-sms";
import { useFormStatus, useFormState } from "react-dom";

const initialState = {
  response: null,
};

function SubmitButton() {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      aria-disabled={pending}
      className="border rounded-md hover:bg-slate-50 p-2 flex justify-center items-center"
    >
      {pending ? (
        <>
          <div class="border-gray-300 h-5 w-5 animate-spin rounded-full border-2 border-t-blue-600 mr-2" />
          Sending...
        </>
      ) : (
        "Send"
      )}
    </button>
  );
}

export function SendForm() {
  const [state, formAction] = useFormState(sendSMS, initialState);

  return (
    <form action={formAction} className="flex flex-col gap-y-2">
      <label htmlFor="number">Phone number:</label>
      <input
        name="number"
        id="number"
        type="number"
        placeholder="909009009099"
        autoComplete="off"
        className="border rounded p-2"
        required
      />
      <label htmlFor="text">Message:</label>
      <textarea
        name="text"
        id="text"
        rows={4}
        cols={40}
        placeholder="Hello from Next.js App!"
        className="border rounded p-2"
        required
      />
      <SubmitButton />
      <p aria-live="polite">{state?.response}</p>
    </form>
  );
}

Você pode usar o useFormStatus hook para exibir um status de carregamento quando um formulário estiver sendo enviado ao servidor. Outro hook, o useFormState, permite que você atualize o estado com base no resultado da ação do formulário.

Por fim, você pode importar o send-form.jsx arquivo para dentro do page.js dentro da pasta /app.

import { SendForm } from "./send-form";

export default function Home() {
  return (
    <main className="mx-auto max-w-3xl my-3 p-3 border border-slate-300 shadow rounded-lg divide-y divide-solid">
      <header className="flex flex-row p-3 items-center justify-between">
        <img src="/vonage.svg" alt="Vonage" />
        <h2 className="text-lg font-medium">Send SMS with the Vonage APIs</h2>
      </header>
      <section className="pt-3">
        <SendForm />
      </section>
    </main>
  );
}

Observação: Você pode encontrar o arquivo vonage.svg no repositório de exemplos.

6. Como executar o servidor de desenvolvimento

Na primeira etapa desta seção, criamos um diretório chamado vonage-send-sms. Agora, vamos cd acessá-lo pelo terminal:

cd vonage-send-sms

Em seguida, execute o seguinte comando:

npm run dev

Este comando inicia o servidor de desenvolvimento da sua aplicação Next.js na porta 3000. Para visualizar sua página inicial, acesse http://localhost:3000 no seu navegador. Deverá ficar assim:

Next.js test form to send SMS

7. Como fazer a implantação no Vercel

Usaremos o Vercel para implantar nosso aplicativo neste tutorial, mas você também pode implantar seu projeto com o Netlify. O Vercel oferece várias opções para implantar seu projeto, como Git, Vercel CLI, etc. O método mais popular para criar uma implantação no Vercel é enviar o código para repositórios Git; portanto, usaremos o Git com o GitHub. Você pode começar a usá-lo gratuitamente.

Crie um Account no GitHub

Para começar a usar o GitHub, crie um account gratuito no GitHub.com e confirme seu endereço de e-mail.

Envie seu projeto para o GitHub

Antes da implantação, vamos enviar nossa aplicação Next.js para o GitHub. O repositório pode ser compartilhado com todos ou mantido como privado. Você não precisa incluir um arquivo README nem nenhum outro arquivo.

Para enviar para o GitHub, execute estes comandos, substituindo <username> pelo seu nome de usuário no GitHub:

git remote add origin https://github.com/<username>/vonage-send-sms.git
git push -u origin main

Confira este guia no GitHub se precisar de ajuda para enviar seu aplicativo.

Crie um Account no Vercel

Para começar a usar o Vercel, acesse https://vercel.com/signup para criar um Account no Vercel. Escolha “Continuar com o GitHub” e siga as etapas do processo de cadastro.

Vercel Sign Up Page

Importe seu vonage-send-sms repositório

Depois de se cadastrar no Vercel e enviar seu aplicativo para o GitHub, você pode importar seu repositório para o Vercel. Basta conceder acesso ao seu repositório ou a “Todos os repositórios” nesta etapa. Você pode fazer isso aqui: https://vercel.com/import/git.

Vercel New Project Page

Você também pode implantar o repositório de exemplo que criamos para você nesta etapa em uma única ação, usando o botão “Implantar”, se desejar. Mas não se esqueça de definir as chaves das variáveis de ambiente.

Quando a implantação estiver concluída, você receberá alguns URLs. Clique em um dos links para acessar o formulário do Vonage Send SMS em sua versão ativa. É bem simples!

Depois que você implantar seu aplicativo, o Vercel implantará todas as atualizações por padrão.

Para enviar SMS para alguns países (como a Turquia), os números virtuais devem estar em conformidade com as regulamentações específicas de cada país. Confira os recursos e restrições específicos de cada país para obter mais informações.

2. Como receber SMS e recibos de entrega de SMS com o Next.js

Quando você faz uma solicitação bem-sucedida à SMS API, ela envia um array de objetos de mensagem, sendo que cada mensagem apresenta o status 0 para indicar sucesso. No entanto, isso não garante que seus destinatários tenham recebido a mensagem. Para receber confirmações de entrega em nosso aplicativo Next.js, precisamos fornecer um endpoint de webhook para que a Vonage os envie.

1. Criar um endpoint de webhook

2. Crie um manipulador para solicitações POST

3. Adicionar uma resposta ao manipulador

4. Configurar as definições da API

5. Receber um SMS e gerenciar os comprovantes de entrega

1. Criar um endpoint de webhook

Crie uma nova pasta chamada webhook dentro /app. Em seguida, crie mais uma nova pasta chamada status dentro da webhook pasta. Depois disso, crie um novo route.js arquivo dentro da status pasta. A estrutura de pastas deve ficar assim:

.
└── vonage-send-sms
    └── app
        ├── webhook
        │   └── status
        │       └── route.js
        ├── page.js
        └── layout.js

Como faremos exatamente o mesmo para capturar as mensagens SMS recebidas, vamos criar outra pasta chamada inbound com o route.js arquivo na webhook pasta:

.
└── vonage-send-sms
    └── app
        ├── webhook
        │   ├── status
        │   │   └── route.js
        │   └── inbound
        │       └── route.js
        ├── page.js
        └── layout.js

2. Criar um manipulador para solicitações POST

Vamos criar um manipulador para solicitações POST em /webhook/status para lidar com os recibos de entrega e em /webhook/inbound para lidar com mensagens SMS recebidas. Em seguida, registraremos o corpo da solicitação no console:

export async function POST(request) {
    const res = await request.json();
    console.log("The request from Vonage: ", JSON.stringify(res, null, 2));
}

No momento, você pode verificar o status da mensagem nos registros e também adicionar esse status à sua base de dados ou a outro sistema.

3. Adicione uma resposta ao manipulador

A Vonage presumirá que você não recebeu a mensagem e continuará reenviando-a pelas próximas 24 horas. Dessa forma, o endpoint do webhook deve enviar um 200 OK ou 204 No Content resposta:

export async function POST(request) {
    const res = await request.json();
    console.log("The request from Vonage: ", JSON.stringify(res, null, 2));

    return new Response("ok", {
      status: 200,
    });
}

4. Configurar as definições da API

Seu endpoint de webhook já está pronto para ser implantado no Vercel, no Netlify ou no seu próprio servidor. Após implantar seu aplicativo, preencha cada campo acrescentando /webhook/inbound e /webhook/status à URL de SMS de entrada e à URL de recibos de entrega nas configurações da API.

Configure SMS API Setting

5. Receber um SMS e gerenciar os comprovantes de entrega

Para visualizar os comprovantes de entrega e as mensagens SMS recebidas no Vercel:

1. Escolha seu aplicativo Next.js no painel do Vercel.

2. Acesse a visão geral do seu projeto e selecione a aba “Logs”.

3. A partir daqui, você pode visualizar, filtrar e pesquisar os registros de execução.

Vercel Runtime Logs

Agora, envie uma mensagem SMS por meio do seu aplicativo Next.js e você deverá conseguir ver as solicitações da Vonage nos logs de execução.

A resposta da Vonage será mais ou menos assim:

{
  "msisdn": "905423247231",
  "to": "***9512387",
  "network-code": "28603",
  "messageId": "4a3cf988-570f-4cdb-95be-179f89c64498",
  "price": "0.02380000",
  "status": "failed",
  "scts": "2311031929",
  "err-code": "1",
  "api-key": "******",
  "message-timestamp": "2023-11-03 19:29:32"
}

Veja Entendendo o comprovante de entrega.

Para ver como as mensagens SMS recebidas aparecem no log do console, envie uma mensagem SMS do seu celular para o seu número da Vonage:

{
  "msisdn": "905423247231",
  "to": "***9512387",
  "messageId": "2B00000018726238",
  "text": "Hi! This is test message from Emre!",
  "type": "text",
  "keyword": "HI!",
  "api-key": "******",
  "message-timestamp": "2023-11-03 19:55:15"
}

Veja Anatomia de uma mensagem recebida.

Conclusão

Agora que você já sabe como enviar e receber mensagens SMS e obter confirmações de entrega com a SMS API da Vonage e o Next.js, considere ampliar esse projeto respondendo às mensagens SMS recebidas ou adicionando elementos interativos mais complexos.

Como sempre, fique à vontade para entrar em contato no Slack dos desenvolvedores da Vonage ou Twitter para quaisquer dúvidas ou comentários. Obrigado pela leitura e espero poder me conectar com vocês na próxima vez.

Se você gostou deste post, entre em contato com o Emre! Ele está procurando emprego há muito tempo :)

Outros recursos

• Ativar chamadas de vídeo em um aplicativo Next.js usando a Video API da Vonage

• Exibir notificações de SMS no navegador com Next.JS, Ably e Vercel

• Next.js Ações e mutações no servidor

• Next.js Manipuladores de rota