Pré-requisitos
Para acompanhar e entender o tutorial, é necessário ter um conhecimento básico dos apps Node.js e Express.js. Além disso, conclua as etapas básicas do nosso guia de introdução na documentação do WhatsApp. Se você for um provedor de soluções empresariais (BSP), siga nosso guia para BSPs e garanta que seu app passe no processo de análise.
Tenha preparados estes três itens:
- Um ID do WhatsApp Business.
- Um ID de número de telefone ou um ID de telefone de teste.
- Seu token de usuário do sistema com as permissões necessárias abaixo:
(whatsapp_business_management, whatsapp_business_messaging e business_management).
Se a expectativa para ver o app final for muito grande, confira o código do projeto final.
Como criar um app básico
Para esta demonstração, você usará este servidor Node.js e Express.js de esqueleto básico junto com as dependências necessárias e as funções de esqueleto já criadas.
O tutorial também tem um pacote de solicitação para realizar solicitações HTTP conforme seu app se comunica com uma API. Há duas variáveis no arquivo .env do app:
META_AUTH_TOKEN e MESSAGING_PRODUCT.
Após a configuração do servidor, você poderá ir diretamente para a criação da API.
Carregar uma imagem para uma mensagem de mídia
Antes de poder enviar mensagens baseadas em mídia usando o WhatsApp, você precisa carregar mídias para o WhatsApp acessar posteriormente. Os arquivos de mídia carregados no WhatsApp permanecem por 30 dias, a menos que sejam excluídos.
Você precisa criar uma nova rota POST dentro do arquivo routes/media.js que você pode usar para gerenciar sua mídia. Conforme a documentação, você precisa passar quatro itens:
- ID do número de telefone, que você passa como parâmetro.
- O arquivo que você deseja carregar, que você passa como dados de formulário.
- Tipo de arquivo de carregamento, que você gera usando a função auxiliar.
- Produto de mensagens, que você recebe do arquivo .env.
No entanto, quando você cria uma chamada à API, só precisa de um arquivo e um ID de número de telefone. Os campos restantes você gera usando as funções auxiliares.
Você usa o pacote npm formidable para processar os dados de formulário. A API do WhatsApp Business tem algumas limitações de tipos e tamanhos específicos, que você pode consultar na seção Tipos de mídia aceitos na parte inferior da Documentação de mídia. Há duas funções auxiliares no arquivo helper/validations.js do projeto de esqueleto para lidar com essas limitações.
Para carregar uma imagem, você precisa inicializar um novo formulário formidable. Usando o objeto de formulário, analise o arquivo e execute algumas validações usando as funções auxiliares. Em seguida, execute uma solicitação POST com os dados do formulário e um token de autenticação válido usando a solicitação.
exports.uploadMedia = async (req, res) => { let form = new formidable.IncomingForm(); form.keepExtensions = true; form.parse(req, async (err, fields, files) => { if (err) { return res.status(400).json({ error: "Media could not be uploaded", }); } if (!files.file) { return res.status(400).json({ error: "Media File is required", }); } let isFileValidSize = validateMediaSize(files.file.size, files.file.type); if (!isFileValidSize) { return res.status(400).json({ error: `Media File size should be less than ${mediaLimits( files.file.type )}`, }); } request.post( { url: `https://graph.facebook.com/v13.0/${req.params.id}/media`, formData: { file: { value: fs.createReadStream(files.file.path), options: { filename: files.file.name, contentType: files.file.type, }, }, type: files.file.type, messaging_product: process.env.MESSAGING_PRODUCT, }, headers: { Authorization: `Bearer ${process.env.META_AUTH_TOKEN}`, "content-type": "multipart/form-data", }, }, function (err, resp, body) { if (err) { console.log("Error!"); } else { res.json(JSON.parse(body)); } } ); }); };Após adicionar essa função, você poderá testar essa rota usando o Postman. É assim que deve ficar o objeto final na interface do Postman:
Depois de clicar em Enviar, você receberá o ID da mídia carregada como resposta da API.
Anote o ID da mídia carregada, pois vamos usá-lo mais adiante neste tutorial. Se você estiver criando um app com uma camada de dados, poderá armazenar esse ID no seu banco de dados para uso posterior. Outra opção é seu app de front-end armazenar o ID temporariamente nas variáveis ou no estado.
Como enviar uma mensagem de mídia
Agora, use o ID de mídia que você recuperou na etapa anterior para enviar uma mensagem de mídia ao cliente. Conforme a Referência de API, você deve enviar cinco itens à API para conseguir enviar a mensagem de mídia ao cliente:
- ID do número de telefone passado como parâmetros
- Número de telefone do cliente enviado no corpo da solicitação
- Tipo de mídia enviado no corpo da solicitação
- ID de mídia enviado no corpo da solicitação
- Tipo de destinatário, uma pessoa nesse caso
A função fica assim:
exports.sendMediaMessage = async (req, res) => { const { id, to, type } = req.body; if (!id || !to || !type) { return res.status(400).json({ error: "Required Fields: to, type and id", }); } request.post( { url: `https://graph.facebook.com/v13.0/${req.params.id}/messages`, headers: { Authorization: `Bearer ${process.env.META_AUTH_TOKEN}`, "content-type": "application/json", }, body: `{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "${to}", "type": "${type}", "${type}": { "id": "${id}", }, }`, }, function (err, resp, body) { if (err) { console.log("Error!"); } else { res.json(JSON.parse(body)); } } ); };Se você executar esse ponto de extremidade no Postman, com os detalhes e argumentos necessários, o resultado ficará assim.
Depois de enviar, você verá a seguinte saída no Postman, que também inclui o ID da mensagem.
Visualização de itens de mídia
É possível recuperar a URL de mídia facilmente com a operação GET e o ID de mídia obtido ou armazenado.
exports.getMediaUrl = async (req, res) => { request.get( { url: `https://graph.facebook.com/v13.0/${req.params.id}`, headers: { Authorization: `Bearer ${process.env.META_AUTH_TOKEN}`, }, }, function (err, resp, body) { if (err) { console.log("Error!"); } else { res.json(JSON.parse(body)); } } ); };É assim que a solicitação e a resposta do Postman ficam depois de se obter o item de mídia com sucesso.
Como excluir mídias
Para excluir uma mídia, você usará o mesmo ponto de extremidade da API do WhatsApp para solicitações de mídia com a operação DELETE.
exports.deleteMedia = async (req, res) => { request.delete( { url: `https://graph.facebook.com/v13.0/${req.params.id}`, headers: { Authorization: `Bearer ${process.env.META_AUTH_TOKEN}`, }, }, function (err, resp, body) { if (err) { console.log("Error!"); } else { res.json(JSON.parse(body)); } } ); };Após a exclusão bem-sucedida da mídia, a API enviará a seguinte resposta:
Saiba mais sobre a Plataforma do WhatsApp Business
Este tutorial é só um exemplo do que você pode fazer com a Plataforma do WhatsApp Business. Enquanto planeja o próximo projeto, confira a Documentação da Plataforma do WhatsApp Business para ter um entendimento completo das funcionalidades e limitações de mídia.
Tenha em mente o seguinte:
- A mídia carregada dura apenas trinta dias
- As URLs de download geradas duram apenas cinco minutos
- Sempre salve o ID da mídia quando carregar um arquivo
Eis uma lista dos tipos de mídia aceitos. Consulte mais informações em Tipos de mídia aceitos.
- Áudio (<16 MB) – Formatos ACC, MP4, MPEG, AMR e OGG
- Documentos (<100 MB) – Formatos de texto, PDF, Office e Open Office
- Imagens (<5 MB) – Formatos JPEG e PNG
- Vídeo (<16 MB) – Formatos MP4 e 3GP
- Figurinhas (<100 KB) – Formato WebP
Conclusão
Ao usar as mensagens de mídia avançada da Plataforma do WhatsApp Business, você cria oportunidades para engajar seus clientes. Criar um app baseado em API permite coletar e formar uma biblioteca de mídia que os usuários podem usar para enviar mensagens de forma consistente e eficiente, reduzindo trabalhos repetitivos.
Acesse o Portal de desenvolvedores do WhatsApp e comece a criar seu app hoje mesmo para ver o que mais está disponível.
