Enviar mensagens SMS e MMS em C# e .NET
Neste tutorial, mostraremos como usar o Programmable SMS da Twilio para enviar mensagens SMS e MMS do seu aplicativo .NET Framework ou .NET Core.
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 .NET 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, você precisa se inscrever em uma conta da Twilio e adquirir um número de telefone da Twilio.
Se você é novo na Twilio, pode se inscrever em uma conta de avaliação gratuita para começar. Depois de se conectar, acesse o Console e obtenha o Account SID (SID da conta) e seu 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 C# e .NET 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.
O pacote NuGet da Twilio para .NET ajuda a criar uma nova instância do recurso Message, especificando os parâmetros To, From e Body da mensagem. Vamos criar um novo projeto .NET e adicionar o pacote NuGet da Twilio.
Vá para a seção apropriada abaixo com base no fato de você estar trabalhando com o Visual Studio ou com a ferramenta de linha de comando dotnet
.
Criar um novo projeto com o Visual Studio
Abra o Visual Studio, selecione o menu "File" (Arquivo) e escolha "New" (Novo), "Project..." (Projeto...) e selecione "Console App (.NET Framework)" (aplicativo de console .NET Framework) ou "Console App (.NET Core)" (aplicativo de console .NET Core).
Em seguida, selecione "Tools" (Ferramentas), "NuGet Package Manager" (Gerenciador de pacotes NuGet) e "Package Manager Console" (Console do gerenciador de pacotes) no menu principal do Visual Studio e digite este comando:
Install-Package Twilio
Agora você está pronto para avançar para escrever o código.
Criar um novo projeto com a CLI do .NET
Execute estes comandos para criar um novo projeto .NET e instalar o pacote Twilio NuGet:
mkdir TwilioSend
cd TwilioSend
dotnet new console
dotnet add package Twilio
Escrever o código em C# para enviar um SMS
Agora, abra o arquivo Program.cs
e substitua‐o pelo 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 a configuração para mantê‐las secretas antes de implantar na produção. Escrevemos publicações no blog sobre como proteger os segredos do usuário em um aplicativo da Web .NET Core e em um aplicativo de console .NET Core que deve fornecer algumas boas orientações.
Se você estiver trabalhando com o .NET Framework, os aplicativos ASP.NET devem usar o sistema de configuração integrado para ASP.NET no .NET Framework. Outros tipos de aplicativos .NET podem usar variáveis de ambiente.
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 dois parâmetros 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 inclui o conteúdo do SMS que enviaremos.
Depois de atualizar o exemplo de código, você pode testá‐lo executando‐o no Visual Studio (com o botão "play" (reproduzir) do triângulo verde) ou com o .NET CLI:
dotnet run
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:
{"sid": "SMxxxxxxxxxxxxxxx",
"date_created": "Thu, 09 Aug 2018 17:26:08 +0000",
"date_updated": "Thu, 09 Aug 2018 17:26:08 +0000",
"date_sent": null,
"account_sid": "ACxxxxxxxxxxxxxxxx",
"to": "+15558675310",
"from": "+15017122661",
"messaging_service_sid": null,
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
"status": "queued",
"num_segments": "1",
"num_media": "0",
"direction": "outbound-api",
"api_version": "2010-04-01",
"price": null,
"price_unit": "USD",
"error_code": null,
"error_message": null,
"uri": "/2010-04-01/Accounts/ACxxxxxxxxx/Messages/SMxxxxxxxxxxxx.json",
"subresource_uris": {
"media": "/2010-04-01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"
}
}
Você pode acessar qualquer um desses atributos a partir do seu código .NET, como fizemos quando imprimimos o message.Sid
.
Tente adicionar uma declaração de registro como Console.WriteLine(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.
{"sid": "SMxxxxxxxxxxxxxxx",
"date_created": "Thu, 09 Aug 2018 17:26:08 +0000",
"date_updated": "Thu, 09 Aug 2018 17:26:08 +0000",
"date_sent": null,
"account_sid": "ACxxxxxxxxxxxxxxxx",
"to": "+15558675310",
"from": "+15017122661",
"messaging_service_sid": null,
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
"status": "queued",
"num_segments": "1",
"num_media": "0",
"direction": "outbound-api",
"api_version": "2010-04-01",
"price": null,
"price_unit": "USD",
"error_code": null,
"error_message": null,
"uri": "/2010-04-01/Accounts/ACxxxxxxxxx/Messages/SMxxxxxxxxxxxx.json",
"subresource_uris": {
"media": null
}
}
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 C#.
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 = new List<string>
{
"+15558675310",
"+14158141829",
"+15017122661"
};
foreach (var number in numbersToMessage)
{
var message = MessageResource.Create(
body: "Hello from my Twilio number!",
from: new Twilio.Types.PhoneNumber("+15017122662"),
to: new Twilio.Types.PhoneNumber(number)
);
Console.WriteLine($"Message to {number} has been {message.Status}.");
}
Isso criará uma nova Instância de mensagem para cada número de telefone na lista.
Você pode enviar quantas mensagens desejar o mais rápido possível e a Twilio as colocará na fila para entrega no limite de taxa prescrito.
Você pode achar útil organizar seus logs de contas e mensagens em Serviços de mensagens separados. Consulte nosso guia sobre como configurar e enviar mensagens de um serviço de mensagens para obter mais dicas.
Enviar uma mensagem contendo mídia (MMS) em C# e .NET
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. Observe que esse parâmetro aceita uma lista na qual você pode enviar várias imagens. Neste exemplo, queremos enviar apenas uma, então usamos o método auxiliar Promoter.ListOfOne
do namespace Twilio.Converters
.
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:
"subrecurso_uris": {"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.NET para ver onde a imagem está armazenada. Adicione a seguinte linha ao final do seu arquivo Program.cs
para ver seu URI de mídia recém‐provisionado:
Console.WriteLine(message.SubresourceUris["media"]);
Salve o arquivo e execute o projeto. Em alguns segundos, você deve receber uma mensagem de texto com uma imagem!
O que vem a seguir?
Você acaba de enviar com êxito algumas mensagens com a API do Programmable SMS da Twilio e o pacote NuGet da Twilio.
Confira esses recursos detalhados para levar sua mensagem programática a um novo patamar:
- 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.
- Mergulhe 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.