Enviar mensagens SMS e MMS em Node.js

Neste tutorial, mostraremos como usar o Programmable SMS da Twilio para enviar mensagens SMS e MMS do seu aplicativo Node.js.

Embora você possa enviar mensagens SMS somente de texto em praticamente qualquer lugar do planeta, o envio de mídia está disponível atualmente apenas nos EUA e no Canadá. Saiba mais neste artigo de suporte.

As amostras de código neste tutorial usam a biblioteca auxiliar Node da Twilio. Vamos começar!

Se você tiver uma conta e um número de telefone da Twilio com recursos de SMS, está tudo pronto! Sinta-se à vontade para ir direto para o código.

Antes de enviar mensagens da API da Twilio, você precisará de uma conta da Twilio e um número de telefone ativado pela Twilio.

Se você é novo na Twilio, pode se inscrever em uma conta de avaliação gratuita para começar.

Depois de se inscrever e selecionar um projeto (o modelo "Learn and Explore" (Aprender e explorar) funcionará para este tutorial), acesse o Console e obtenha o Account SID (SID da conta) e o Auth Token (Token de autenticação). Você precisará desses valores para os exemplos de código abaixo.

Obter um número de telefone com recursos de SMS (e MMS)

O envio de mensagens requer um número de telefone da Twilio com recursos de SMS. Se você não possui atualmente um número de telefone da Twilio com recursos de SMS, precisará adquirir um. Depois de navegar até a página Buy a Number (Comprar um número), marque a caixa "SMS" e clique em "Search" (Pesquisar):

Se você mora nos EUA ou no Canadá e também deseja enviar mensagens MMS, pode selecionar a caixa "MMS". Ao visualizar os resultados da pesquisa, você pode ver os ícones do recurso na lista de números disponíveis:

Click Buy Button to Purchase an SMS-capable Number

Encontre um número que você goste e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.

Se estiver usando uma conta de avaliação, você precisará verificar seu número de telefone pessoal pelo console para poder testar o envio de SMS para você mesmo. Saiba mais sobre como trabalhar com sua conta de avaliação gratuita.

Agora que você tem um número de telefone da Twilio, pode começar a enviar mensagens para dispositivos móveis.

Enviar uma mensagem SMS em Node.js pela API REST

Para enviar uma mensagem SMS da sua conta da Twilio, você precisará fazer um HTTP POST para o recurso Message da Twilio.

A biblioteca auxiliar da Twilio para Node.js ajuda a criar uma nova instância do recurso Message, especificando os parâmetros To, From e Body da mensagem.

Se você ainda não tiver a biblioteca auxiliar Node instalada, poderá instalá‐la usando npm:

npm install twilio

Ele instalará o módulo twilio para que os scripts Node.js no diretório atual possam usá‐lo.

Agora, crie um arquivo chamado sms.js e inclua o seguinte código.

Loading Code Sample...

Example JSON response

Enviar um SMS usando a API do Programmable SMS

Substitua os valores do espaço reservado accountSid e authToken por seus valores exclusivos. Você pode encontrá‐las no Console da Twilio.

Observação: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê-las secretas antes de implantar na produção. Confira nossa publicação no blog "Como trabalhar com variáveis de ambiente no Node.js" para obter orientação.

Você informará à Twilio qual número de telefone usar para enviar essa mensagem substituindo o número from pelo número de telefone da Twilio que você comprou anteriormente.

Em seguida, especifique‐se como o destinatário da mensagem substituindo o número to pelo número de telefone do seu celular. Os parâmetros from e to devem usar a formatação E.164 ("+" e um código de país, por exemplo +16175551212).

Também incluímos o parâmetro body, que contém o conteúdo do SMS que enviaremos.

Depois de atualizar o exemplo de código, você pode testá‐lo executando‐o na linha de comando:

node sms.js

Em apenas alguns instantes você deve receber um SMS!

Se estiver usando uma conta de avaliação, você notará que todas as mensagens enviadas sempre começarão com "Sent from a Twilio trial account (Enviado de uma conta de avaliação da Twilio)". Depois de atualizar sua conta, você não verá mais esta mensagem. Saiba mais sobre o envio de mensagens SMS e MMS a partir de uma conta de avaliação.

Vamos ver o que acontece nos bastidores quando você envia esta solicitação para a Twilio.

Resposta da Twilio

Quando a Twilio receber sua solicitação para enviar um SMS pela API REST, ela verificará se você incluiu um número de telefone válido da Twilio no campo From. A Twilio enfileirará o SMS ou retornará esse erro HTTP em resposta à sua solicitação.

Supondo que sua solicitação não tenha gerado um erro, a resposta HTTP da Twilio incluirá o SID da nova mensagem. Esse identificador exclusivo nos ajudará a fazer referência a esta mensagem mais tarde. No código acima, imprimimos esse SID no terminal.

A resposta JSON da Twilio inclui uma quantidade robusta de dados sobre sua mensagem. Um exemplo de resposta pode ser assim:

{"accountSid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
 "apiVersion":"2010-04-01",
 "body":"This is the ship that made the Kessel Run in fourteen parsecs?",
 "dateCreated":"2018-09-11T17:29:05.000Z",
 "dateUpdated":"2018-09-11T17:29:05.000Z",
 "dateSent":null,"direction":"outbound-api",
 "errorCode":null,
 "errorMessage":null,
 "to":"+15558675310",
 "from":"+15017122661",
 "messagingServiceSid":null,"numMedia":"0",
 "numSegments":"1",
 "price":null,"priceUnit":"USD",
 "sid":"SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
 "status":"queued",
 "uri":"/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX7/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json",
 "subresourceUris":{
   "media": null
 }
}

Você pode acessar qualquer um desses atributos a partir do seu código Node.js, como fizemos quando registramos o message.sid.

Tente atualizar a instrução de registro existente em seu código para ser .then(message => console.log(message.status)). Salve o arquivo e execute o código novamente. Você deverá ver o status de sua mensagem, "queued", impresso em seu terminal.

Se você receber um erro em resposta da Twilio ou nunca receber a mensagem, consulte estas dicas de resolução de problemas de mensagens não entregues.

Se desejar rastrear o status de suas mensagens em tempo real, será necessário configurar um URL de StatusCallback. Saiba mais em nosso tutorial sobre como confirmar a entrega de mensagens em Node.js.

Enviar uma mensagem para vários destinatários

Se quiser enviar uma mensagem para vários destinatários, você poderá criar uma lista de destinatários (ou obter uma lista de um banco de dados) e percorrer cada número de telefone na lista:

var numbersToMessage = ["+15558675310", "+14158141829", "+15017122661"]

numbersToMessage.forEach(function(number){
  var message = client.messages.create({
    body: 'This is the ship that made the Kessel Run in fourteen parsecs?',
    from: '+16468635472',
    to: number
  })
  .then(message =>  console.log(message.status))
  .done();
});

Isso criará uma nova Instância de mensagem para cada número de telefone na lista.

A note on message rate limiting

As you send more messages via the API, Twilio will queue them up for delivery at your prescribed rate limit. API requests for messages that exceed the specified rates will be queued and executed as capacity is available.

If your application tries to enqueue more than 4 hours worth of outbound traffic (e.g., enqueuing more than 14,400 messages to Canada over one long code phone number), the API will start returning 429 errors.

If you need to enqueue a large volume of messages, you may find that it's helpful to leverage Twilio's Messaging Services. See our guide on how to set up and send messages from a messaging service in your language of choice for more tips.

Enviar uma mensagem contendo mídia (MMS) em Node.js

Embora você possa enviar mensagens SMS somente de texto em praticamente qualquer lugar do planeta, o envio de mídia está disponível atualmente apenas nos EUA e no Canadá.

Para incluir mídia em sua mensagem de texto com tecnologia Twilio, você precisa adicionar o código que escrevemos acima. Desta vez, precisamos adicionar o parâmetro mediaUrl.

Loading Code Sample...

Example JSON response

Envie uma mensagem com um URL de imagem

Novamente, atualize os parâmetros from e to para usar o número de telefone da Twilio e o telefone celular.

O novo parâmetro mediaUrl neste código informa a Twilio onde obter a mídia que queremos incluir. Este deve ser um URL acessível publicamente: A Twilio não poderá acessar nenhum URL oculto ou que exija autenticação.

Assim como quando você envia um SMS simples, a Twilio envia dados sobre a mensagem em resposta à sua solicitação. A resposta JSON conterá o SID exclusivo e o URI para seu recurso de mídia:

"subresourceUris": {"mídia": "/2010-04 01/Contas/ACxxxxxxxx/Mensagens/SMxxxxxxxxxxxxx/Mídia.json"}

Quando a API REST da Twilio cria seu novo recurso Message, ela salvará a imagem encontrada em mediaUrl especificado como um recurso de mídia. Uma vez criado, você pode acessar esse recurso a qualquer momento por meio da API.

Você pode imprimir esse valor a partir do seu código Node.js para ver onde a imagem está armazenada. Atualize o arquivo sms.js console.log para ver seu URI de mídia recém‐provisionado:

console.log(message.subresourceUris.media)

Salve o arquivo e execute o projeto. Em alguns segundos, você deve receber uma mensagem de texto com uma imagem e ver o novo URI de mídia impresso no console.

O que vem a seguir?

Você acaba de enviar com êxito algumas mensagens com a API Programmable SMS da Twilio e a biblioteca auxiliar Node.js.

Confira esses recursos detalhados para levar sua mensagem programática a um novo patamar:

Saiba como enviar um SMS durante uma chamada em andamento com Node.js e Express.
Monitore o status da mensagem para confirmar a entrega.
Saiba como responder a um SMS enviado para o número de telefone da Twilio.
Saiba como gerenciar o estado da mensagem para transformar mensagens individuais em uma verdadeira conversa por SMS.
Aprofunde‐se nos detalhes com nossa documentação de referência de API para mensagens.
Enviando mensagens de alto volume? Confira nossos serviços de mensagens.

Contribuidores:

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

Enviar um SMS usando a API do Programmable SMS

Envie uma mensagem com um URL de imagem

Precisa de ajuda?

Obrigado pelo seu feedback!

Obrigado pelo seu feedback!