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 você possa enviar mensagens SMS somente de texto em praticamente qualquer lugar do planeta, o envio de mídia está disponível atualmente apenas nos EUA e no Canadá. Saiba mais neste artigo de suporte.
As amostras de código neste tutorial usam a biblioteca auxiliar Node da Twilio. Vamos começar!
Inscreva‐se (ou faça login) na sua conta da Twilio
Se você tiver uma conta e um número de telefone da Twilio com recursos de SMS, está tudo pronto! Sinta-se à vontade para ir direto para o código.
Antes de enviar mensagens da API da Twilio, você precisará de uma conta da Twilio e um número de telefone ativado pela Twilio.
Se você é novo na Twilio, pode se inscrever em uma conta de avaliação gratuita para começar.
Depois de se inscrever e selecionar um projeto (o modelo "Learn and Explore" (Aprender e explorar) funcionará para este tutorial), acesse o Console e obtenha o Account SID (SID da conta) e o Auth Token (Token de autenticação). Você precisará desses valores para os exemplos de código abaixo.
Obter um número de telefone com recursos de SMS (e MMS)
O envio de mensagens requer um número de telefone da Twilio com recursos de SMS. Se você não possui atualmente um número de telefone da Twilio com recursos de SMS, precisará adquirir um. Depois de navegar até a página Buy a Number (Comprar um número), marque a caixa "SMS" e clique em "Search" (Pesquisar):
Se você mora nos EUA ou no Canadá e também deseja enviar mensagens MMS, pode selecionar a caixa "MMS". Ao visualizar os resultados da pesquisa, você pode ver os ícones do recurso na lista de números disponíveis:
Encontre um número que você goste e clique em "Buy" (Comprar) para adicioná‐lo à sua conta.
Se estiver usando uma conta de avaliação, você precisará verificar seu número de telefone pessoal pelo console para poder testar o envio de SMS para você mesmo. Saiba mais sobre como trabalhar com sua conta de avaliação gratuita.
Agora que você tem um número de telefone da Twilio, pode começar a enviar mensagens para dispositivos móveis.
Enviar uma mensagem SMS em Node.js pela API REST
Para enviar uma mensagem SMS da sua conta da Twilio, você precisará fazer um HTTP POST para o recurso Message da Twilio.
A biblioteca auxiliar da Twilio para Node.js ajuda a criar uma nova instância do recurso Message, especificando os parâmetros To, From e Body da mensagem.
Se você ainda não tiver a biblioteca auxiliar Node instalada, poderá instalá‐la usando npm:
npm install twilio
Ele instalará o módulo twilio
para que os scripts Node.js no diretório atual possam usá‐lo.
Agora, crie um arquivo chamado sms.js
e inclua o seguinte código.
Substitua os valores do espaço reservado accountSid
e authToken
por seus valores exclusivos. Você pode encontrá‐las no Console da Twilio.
Observação: não há problema em codificar suas credenciais ao começar, mas você deve usar variáveis de ambiente para mantê-las secretas antes de implantar na produção. Confira nossa publicação no blog "Como trabalhar com variáveis de ambiente no Node.js" para obter orientação.
Você informará à Twilio qual número de telefone usar para enviar essa mensagem substituindo o número from
pelo número de telefone da Twilio que você comprou anteriormente.
Em seguida, especifique‐se como o destinatário da mensagem substituindo o número to
pelo número de telefone do seu celular. Os parâmetros from
e to
devem usar a formatação E.164 ("+
" e um código de país, por exemplo +16175551212
).
Também incluímos o parâmetro body
, que contém o conteúdo do SMS que enviaremos.
Depois de atualizar o exemplo de código, você pode testá‐lo executando‐o na linha de comando:
node sms.js
Em apenas alguns instantes você deve receber um SMS!
Se estiver usando uma conta de avaliação, você notará que todas as mensagens enviadas sempre começarão com "Sent from a Twilio trial account (Enviado de uma conta de avaliação da Twilio)". Depois de atualizar sua conta, você não verá mais esta mensagem. Saiba mais sobre o envio de mensagens SMS e MMS a partir de uma conta de avaliação.
Vamos ver o que acontece nos bastidores quando você envia esta solicitação para a Twilio.
Resposta da Twilio
Quando a Twilio receber sua solicitação para enviar um SMS pela API REST, ela verificará se você incluiu um número de telefone válido da Twilio no campo From
. A Twilio enfileirará o SMS ou retornará esse erro HTTP em resposta à sua solicitação.
Supondo que sua solicitação não tenha gerado um erro, a resposta HTTP da Twilio incluirá o SID da nova mensagem. Esse identificador exclusivo nos ajudará a fazer referência a esta mensagem mais tarde. No có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
}
}
Você pode acessar qualquer um desses atributos a partir do seu código Node.js, como fizemos quando registramos o message.sid
.
Tente atualizar a instrução de registro existente em seu código para ser .then(message => console.log(message.status))
. Salve o arquivo e execute o código novamente. Você deverá ver o status de sua mensagem, "queued
", impresso em seu terminal.
Se você receber um erro em resposta da Twilio ou nunca receber a mensagem, consulte estas dicas de resolução de problemas de mensagens não entregues.
Se desejar rastrear o status de suas mensagens em tempo real, será necessá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 vários destinatários
Se quiser enviar uma mensagem para vários destinatários, você poderá criar uma lista de destinatários (ou obter uma lista de um banco de dados) e percorrer cada nú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 criará uma nova Instância de mensagem para cada nú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 mídia (MMS) em Node.js
Embora você possa enviar mensagens SMS somente de texto em praticamente qualquer lugar do planeta, o envio de mídia está disponível atualmente apenas nos EUA e no Canadá.
Para incluir mídia em sua mensagem de texto com tecnologia Twilio, você precisa adicionar o código que escrevemos acima. Desta vez, precisamos adicionar o parâmetro mediaUrl
.
Novamente, atualize os parâmetros from
e to
para usar o número de telefone da Twilio e o telefone celular.
O novo parâmetro mediaUrl
neste código informa a Twilio onde obter a mídia que queremos incluir. Este deve ser um URL acessível publicamente: A Twilio não poderá acessar nenhum URL oculto ou que exija autenticação.
Assim como quando você envia um SMS simples, a Twilio envia dados sobre a mensagem em resposta à sua solicitação. A resposta JSON conterá o SID exclusivo e o URI para seu recurso de mídia:
"subresourceUris": {"mídia": "/2010-04 01/Contas/ACxxxxxxxx/Mensagens/SMxxxxxxxxxxxxx/Mídia.json"}
Quando a API REST da Twilio cria seu novo recurso Message, ela salvará a imagem encontrada em mediaUrl
especificado como um recurso de mídia. Uma vez criado, você pode acessar esse recurso a qualquer momento por meio da API.
Você pode imprimir esse valor a partir do seu código Node.js para ver onde a imagem está armazenada. Atualize o arquivo sms.js
console.log
para ver seu URI de mídia recém‐provisionado:
console.log(message.subresourceUris.media)
Salve o arquivo e execute o projeto. Em alguns segundos, você deve receber uma mensagem de texto com uma imagem e ver o novo URI de mídia impresso no console.
O que vem a seguir?
Você acaba de enviar com êxito algumas mensagens com a API Programmable SMS da Twilio e a biblioteca auxiliar Node.js.
Confira esses recursos detalhados para levar sua mensagem programá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 nú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 documentação de referência de API para mensagens.
- Enviando mensagens de alto volume? Confira nossos serviços de mensagens.
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.