Envio de mensagens SMS com o Amazon SNS - AWS SDK for JavaScript
O cenárioTarefas de pré-requisitoObter atributos do SMSDefinir atributos do SMSVerificar se um número de telefone cancelou o recebimentoListar números de telefone que cancelaram o recebimentoPublicar uma mensagem SMS

O Guia de referência da API do AWS SDK for JavaScript V3 descreve em detalhes todas as operações da API para o AWS SDK for JavaScript versão 3 (V3).

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Envio de mensagens SMS com o Amazon SNS

JavaScript code example that applies to Node.js execution

Este exemplo de código Node.js mostra:

  • Como obter e definir as preferências de mensagens SMS para Amazon SNS.

  • Como verificar um número de telefone para definir se ele não permite o recebimento de mensagens SMS.

  • Como obter uma lista de números de telefone que cancelaram o recebimento de mensagens SMS.

  • Como enviar uma mensagem SMS.

O cenário

Você pode usar o Amazon SNS para enviar mensagens de texto ou mensagens SMS para dispositivos habilitados para SMS. Você pode enviar uma mensagem diretamente para um número de telefone, ou enviar uma mensagem para vários números de telefone de uma só vez inscrevendo esses números em um tópico e enviando sua mensagem para o tópico.

Neste exemplo, você usa uma série de módulos do Node.js para publicar mensagens de texto SMS do Amazon SNS em dispositivos habilitados para SMS. Os módulos do Node.js usam o SDK para JavaScript para publicar mensagens SMS usando estes métodos da classe de cliente SNS:

Tarefas de pré-requisito

Para configurar e executar este exemplo, você deve primeiro concluir estas tarefas:

  • Configure o ambiente do projeto para executar estes exemplos do Node TypeScript e instale os módulos do AWS SDK for JavaScript e de terceiros necessários. Siga as instruções no GitHub.

  • Crie um arquivo de configurações compartilhado com as credenciais de usuário. Para obter mais informações sobre como fornecer um arquivo de credenciais compartilhado, consulte Arquivos de configuração e credenciais compartilhados no Guia de referência de ferramentas e SDKs da AWS.

Importante

Esses exemplos demonstram como importar/exportar objetos e comandos do serviço de cliente usando o ECMAScript6 (ES6).

Obter atributos do SMS

Use o Amazon SNS para especificar as preferências para o uso de mensagens SMS, por exemplo, como suas entregas serão otimizadas (para fins de custo ou confiabilidade), o limite de gastos mensais, como as entregas de mensagens serão registradas e a assinatura em relatórios diários de uso de SMS. Essas preferências são recuperadas e definidas como atributos de SMS para Amazon SNS.

Neste exemplo, use um módulo do Node.js para obter os atributos de SMS atuais no Amazon SNS.

Crie um diretório libs e um módulo do Node.js com o nome de arquivo snsClient.js. Copie e cole o código abaixo nele, o que cria o objeto de cliente do Amazon SNS. Substitua REGION pela sua região da AWS.

import { SNSClient } from "@aws-sdk/client-sns";

// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});

Esse código de exemplo pode ser encontrado aqui no GitHub.

Crie um módulo do Node.js com o nome de arquivo get-sms-attributes.js.

Configure o SDK conforme mostrado anteriormente, incluindo o download dos clientes e pacotes necessários. Crie um objeto contendo os parâmetros para obter atributos de SMS, incluindo os nomes dos atributos individuais a serem obtidos. Para obter detalhes sobre os atributos de SMS disponíveis, consulte SetSMSAttributes na Referência de API do Amazon Simple Notification Service.

Esse exemplo usa o atributo DefaultSMSType, que controla se serão enviadas mensagens SMS como Promotional, o que otimiza a entrega de mensagens para gerar custos mais baixos, ou como Transactional, que otimiza a entrega de mensagens para gerar a mais alta confiabilidade. Passe os parâmetros para o método SetTopicAttributesCommand da classe de cliente SNS. Para chamar o método SetSMSAttributesCommand, crie uma função assíncrona que invoca um objeto de serviço de cliente do Amazon SNS, passando o objeto dos parâmetros.

nota

Substitua ATTRIBUTE_NAME pelo nome do atributo.

import { GetSMSAttributesCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";

export const getSmsAttributes = async () => {
  const response = await snsClient.send(
    // If you have not modified the account-level mobile settings of SNS,
    // the DefaultSMSType is undefined. For this example, it was set to
    // Transactional.
    new GetSMSAttributesCommand({ attributes: ["DefaultSMSType"] }),
  );

  console.log(response);
  // {
  //   '$metadata': {
  //     httpStatusCode: 200,
  //     requestId: '67ad8386-4169-58f1-bdb9-debd281d48d5',
  //     extendedRequestId: undefined,
  //     cfId: undefined,
  //     attempts: 1,
  //     totalRetryDelay: 0
  //   },
  //   attributes: { DefaultSMSType: 'Transactional' }
  // }
  return response;
};

Para executar o exemplo, digite o seguinte no prompt de comando.

node get-sms-attributes.js

Esse código de exemplo pode ser encontrado aqui no GitHub.

Definir atributos do SMS

Neste exemplo, use um módulo do Node.js para obter os atributos de SMS atuais no Amazon SNS.

Crie um diretório libs e um módulo do Node.js com o nome de arquivo snsClient.js. Copie e cole o código abaixo nele, o que cria o objeto de cliente do Amazon SNS. Substitua REGION pela sua região da AWS.

import { SNSClient } from "@aws-sdk/client-sns";

// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});

Esse código de exemplo pode ser encontrado aqui no GitHub.

Crie um módulo do Node.js com o nome de arquivo set-sms-attribute-type.js. Configure o SDK conforme mostrado anteriormente, incluindo a instalação dos clientes e pacotes necessários. Crie um objeto contendo os parâmetros para definir atributos de SMS, incluindo os nomes dos atributos individuais a serem definidos e os valores para cada um. Para obter detalhes sobre os atributos de SMS disponíveis, consulte SetSMSAttributes na Referência de API do Amazon Simple Notification Service.

Este exemplo define o atributo DefaultSMSType para Transactional, que otimiza a entrega de mensagens para gerar a mais alta confiabilidade. Passe os parâmetros para o método SetTopicAttributesCommand da classe de cliente SNS. Para chamar o método SetSMSAttributesCommand, crie uma função assíncrona que invoca um objeto de serviço de cliente do Amazon SNS, passando o objeto dos parâmetros. 

import { SetSMSAttributesCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";

/**
 * @param {"Transactional" | "Promotional"} defaultSmsType
 */
export const setSmsType = async (defaultSmsType = "Transactional") => {
  const response = await snsClient.send(
    new SetSMSAttributesCommand({
      attributes: {
        // Promotional – (Default) Noncritical messages, such as marketing messages.
        // Transactional – Critical messages that support customer transactions,
        // such as one-time passcodes for multi-factor authentication.
        DefaultSMSType: defaultSmsType,
      },
    }),
  );
  console.log(response);
  // {
  //   '$metadata': {
  //     httpStatusCode: 200,
  //     requestId: '1885b977-2d7e-535e-8214-e44be727e265',
  //     extendedRequestId: undefined,
  //     cfId: undefined,
  //     attempts: 1,
  //     totalRetryDelay: 0
  //   }
  // }
  return response;
};

Para executar o exemplo, digite o seguinte no prompt de comando.

node set-sms-attribute-type.js

Esse código de exemplo pode ser encontrado aqui no GitHub.

Verificar se um número de telefone cancelou o recebimento

Neste exemplo, use um módulo do Node.js para verificar um número de telefone e determinar se ele cancelou o recebimento de mensagens SMS.

Crie um diretório libs e um módulo do Node.js com o nome de arquivo snsClient.js. Copie e cole o código abaixo nele, o que cria o objeto de cliente do Amazon SNS. Substitua REGION pela sua região da AWS.

import { SNSClient } from "@aws-sdk/client-sns";

// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});

Esse código de exemplo pode ser encontrado aqui no GitHub.

Crie um módulo do Node.js com o nome de arquivo check-if-phone-number-is-opted-out.js. Configure o SDK como mostrado anteriormente. Crie um objeto contendo o número de telefone a ser verificado como parâmetro.

Este exemplo define o parâmetro PhoneNumber para especificar o número de telefone a ser verificado. Passe o objeto para o método CheckIfPhoneNumberIsOptedOutCommand da classe de cliente SNS. Para chamar o método CheckIfPhoneNumberIsOptedOutCommand, crie uma função assíncrona que invoca um objeto de serviço de cliente do Amazon SNS, passando o objeto dos parâmetros.

nota

Substitua PHONE_NUMBER pelo número de telefone.

import { CheckIfPhoneNumberIsOptedOutCommand } from "@aws-sdk/client-sns";

import { snsClient } from "../libs/snsClient.js";

export const checkIfPhoneNumberIsOptedOut = async (
  phoneNumber = "5555555555",
) => {
  const command = new CheckIfPhoneNumberIsOptedOutCommand({
    phoneNumber,
  });

  const response = await snsClient.send(command);
  console.log(response);
  // {
  //   '$metadata': {
  //     httpStatusCode: 200,
  //     requestId: '3341c28a-cdc8-5b39-a3ee-9fb0ee125732',
  //     extendedRequestId: undefined,
  //     cfId: undefined,
  //     attempts: 1,
  //     totalRetryDelay: 0
  //   },
  //   isOptedOut: false
  // }
  return response;
};

Para executar o exemplo, digite o seguinte no prompt de comando.

node check-if-phone-number-is-opted-out.js

Esse código de exemplo pode ser encontrado aqui no GitHub.

Listar números de telefone que cancelaram o recebimento

Neste exemplo, use um módulo do Node.js para obter uma lista de telefones que cancelaram o recebimento de mensagens SMS.

Crie um diretório libs e um módulo do Node.js com o nome de arquivo snsClient.js. Copie e cole o código abaixo nele, o que cria o objeto de cliente do Amazon SNS. Substitua REGION pela sua região da AWS.

import { SNSClient } from "@aws-sdk/client-sns";

// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});

Esse código de exemplo pode ser encontrado aqui no GitHub.

Crie um módulo do Node.js com o nome de arquivo list-phone-numbers-opted-out.js. Configure o SDK como mostrado anteriormente. Crie um objeto vazio como parâmetro.

Passe o objeto para o método ListPhoneNumbersOptedOutCommand da classe de cliente SNS. Para chamar o método ListPhoneNumbersOptedOutCommand, crie uma função assíncrona que invoca um objeto de serviço de cliente do Amazon SNS, passando o objeto dos parâmetros. 

import { ListPhoneNumbersOptedOutCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";

export const listPhoneNumbersOptedOut = async () => {
  const response = await snsClient.send(
    new ListPhoneNumbersOptedOutCommand({}),
  );
  console.log(response);
  // {
  //   '$metadata': {
  //     httpStatusCode: 200,
  //     requestId: '44ff72fd-1037-5042-ad96-2fc16601df42',
  //     extendedRequestId: undefined,
  //     cfId: undefined,
  //     attempts: 1,
  //     totalRetryDelay: 0
  //   },
  //   phoneNumbers: ['+15555550100']
  // }
  return response;
};

Para executar o exemplo, digite o seguinte no prompt de comando.

node list-phone-numbers-opted-out.js

Esse código de exemplo pode ser encontrado aqui no GitHub.

Publicar uma mensagem SMS

Neste exemplo, use um módulo do Node.js para enviar uma mensagem SMS a um número de telefone.

Crie um diretório libs e um módulo do Node.js com o nome de arquivo snsClient.js. Copie e cole o código abaixo nele, o que cria o objeto de cliente do Amazon SNS. Substitua REGION pela sua região da AWS.

import { SNSClient } from "@aws-sdk/client-sns";

// The AWS Region can be provided here using the `region` property. If you leave it blank
// the SDK will default to the region set in your AWS config.
export const snsClient = new SNSClient({});

Esse código de exemplo pode ser encontrado aqui no GitHub.

Crie um módulo do Node.js com o nome de arquivo publish-sms.js. Configure o SDK conforme mostrado anteriormente, incluindo a instalação dos clientes e pacotes necessários. Crie um objeto contendo os parâmetros Message e PhoneNumber.

Ao enviar uma mensagem SMS, especifique o número de telefone usando o formato E.164. E.164 é um padrão para a estrutura de número de telefone usada para telecomunicações internacionais. Números de telefone que seguem esse formato podem ter um máximo de 15 dígitos, e eles são prefixados com o caractere de mais (+) e o código do país. Por exemplo, um número de telefone dos EUA no formato E.164 seria exibido como +1001XXX5550100.

Este exemplo define o parâmetro PhoneNumber para especificar o número de telefone ao qual a mensagem deve ser enviada. Passe o objeto para o método PublishCommand da classe de cliente SNS. Para chamar o método PublishCommand, crie uma função assíncrona que invoca um objeto de serviço do Amazon SNS, passando o objeto dos parâmetros.

nota

Substitua TEXT_MESSAGE pela mensagem de texto e PHONE_NUMBER pelo número de telefone.

import { PublishCommand } from "@aws-sdk/client-sns";
import { snsClient } from "../libs/snsClient.js";

/**
 * @param {string | Record<string, any>} message - The message to send. Can be a plain string or an object
 *                                                 if you are using the `json` `MessageStructure`.
 * @param {*} phoneNumber - The phone number to send the message to.
 */
export const publish = async (
  message = "Hello from SNS!",
  phoneNumber = "+15555555555",
) => {
  const response = await snsClient.send(
    new PublishCommand({
      Message: message,
      // One of PhoneNumber, TopicArn, or TargetArn must be specified.
      PhoneNumber: phoneNumber,
    }),
  );
  console.log(response);
  // {
  //   '$metadata': {
  //     httpStatusCode: 200,
  //     requestId: '7410094f-efc7-5f52-af03-54737569ab77',
  //     extendedRequestId: undefined,
  //     cfId: undefined,
  //     attempts: 1,
  //     totalRetryDelay: 0
  //   },
  //   MessageId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  // }
  return response;
};

Para executar o exemplo, digite o seguinte no prompt de comando.

node publish-sms.js

Esse código de exemplo pode ser encontrado aqui no GitHub.