Schedule surprise messages with Twilio SMS for a mystical date

December 01, 2022
Written by
Néstor Campos
Opinions expressed by Twilio contributors are their own
Reviewed by

How to schedule surprise messages  with Twilio SMS  for a mystical date

Imagine that you want to give a fantastic dinner to your loved ones a great New Year's Eve dinner, but you want to keep it a surprise for as long as possible. So you decide to start sending them different SMS messages with a series of clues on different days to maintain the "mystique" of this surprise.

In this article, you will create a console application to send scheduled SMS messages with Twilio that are sent at a specific time/date.


You will need the following for your development environment:

You can find the source code of this tutorial in this GitHub repository.

Configure Twilio

Get your Twilio Credentials

To interact with Twilio, you will need an account with credits (it can be with trial credits for this tutorial), and you'll need to get your Twilio  Account SID and Auth Token to use the Twilio SDK. Sign in to the Twilio Console and find your Account SID and Auth Token on the home page of your Twilio Account.

Twilio Console home page showing Account SID and Auth Token.

Copy them in a safe place because you will use them later.

If you have a trial account, you can only send messages to verified numbers on the account.

Buy a number

You'll need to have a Twilio Phone Number to send SMS messages.

In order to buy one, in the Twilio Console, you need to go to the left side menu, select the "Phone Numbers" option, then "Manage" to finally click "Buy a number".

Left side menu specifying the "Buy a number" option in the "Phone Numbers" category.

If you can't find the Phone Numbers product in the navigation menu, click on "Explore Products" and find the "Phone Numbers" product under the "Super Network" category.

In the filters on the displayed screen, select a country that has the SMS option available, for example, the USA.

Form to filter Twilio Phone Numbers to buy, with the phone country options, and the available functions, SMS, MMS, Fax and Voice.

Select one of the available numbers by clicking on the "Buy" option.

List of phone numbers available to buy with the filters applied in the form.

A screen will be displayed indicating the properties of your phone number before buying it. Here, you can verify that the ability to send SMS is available. Click on "Buy" and then click "Buy <phone number>".

Modal with the phone number to buy, with monthly cost and available capacities.

Footer of the modal with the phone number to buy, with the "Buy <number>" button to confirm it.

Finally, a screen will be displayed with the confirmation of your new phone number available to use.

Confirmation screen of the phone number purchased.

Create a Messaging Service to schedule messages

Next, you will need to create a Messaging Service where you can associate your phone number with the service and then use the service to schedule messages.

You can also send SMS straight from Twilio Phone Numbers without using a Messaging Service, however, later in this post, you'll use message scheduling which requires a Messaging Service.

In The Twilio Console click on "Messaging" (if you don't see it, click on "Explore Products", which will display the list with the available products, and there you will see "Messaging"). Then, click on "Services". Next, on the displayed page, click the "Create Messaging Service" button to create your service.

Messaging Services page explaining the functionality and with the "Creating Messaging Service" button

Enter a name that identifies what you will do with your service, select what you are going to use your service for in the available list, and finally click on "Create Messaging Service".

Messaging Service creation step, with the name of the service, the list of options on the use of the service and the button to create it.

Your service has been created. Now it is time to configure a sender, that is, a phone number from which you will send the messages.

You can only send so many messages per second with a single phone number or sender. With Messaging Services, you can add multiple senders to its Sender Pool, and instead of sending messages directly from a single sender, you can send them via the Messaging Service to increase the message throughput.

In addition to phone numbers, you can also add short codes, alpha senders, and WhatsApp numbers.

Second step in "Messaging Service Setup", to configure the Sender Pool with the option to add new senders (phone numbers, whatsapp numbers) with the "Add Senders" button, which can be used when sending messages through the Messaging Service created.

Click on the "Add Senders" button and in the modal, select the "Phone Number" option in the "Sender Type" dropdown, and finally click on "Continue".

Modal screen to add a sender, specifying that it will be a phone number

You will see the list of phone numbers available in your account (the one you just bought). Select the checkbox for that number, which appears in the first column, and then click "Add Phone Numbers".

List of phone numbers available as senders in your account to add them in the messaging service

Then, click "Set up integration", where you can configure what to do with incoming messages on your senders and the maximum time your messages can be queued before not being sent (like a timeout).

Select the "Drop the message" option since you won't be doing anything with incoming messages in this project.

Integration screen, with the "Drop the message" option for incoming messages and keeping the default value for the "Validity Period" field.

Then click the "Step 4: Add compliance info" button.

Footer of the integration form, with the button "Step 4: Add compliance info"

In this form, you should configure topics such as your business profile, among others, to ensure that your usage of messaging is compliant.

In this project, you will skip this step and click "Complete Messaging Service Setup" to finish the process.

Footer of the compliance step, with the "Complete Messaging Service Setup" button

After finishing the process, a modal screen will be displayed with the confirmation of this process. Click on the "View my new Messaging Service" button.

Modal confirmation screen of the messaging service created, with the options to view the service and try to send a message.

On the screen of your new service, you will see the "Messaging Service SID", which you should copy, since you will use it in your code to send the SMS messages.

Summary screen of the created service, with the name of the service and the unique SID that will be used in the project.

Alright, now that you've set up your Twilio Phone Number and Messaging Service for your project, it's time to set up a file hosting service and your .NET project.

Create a Console Project

You will need to create a console project using the .NET CLI. Open a terminal and run the following commands to create a folder that will contain your project:

mkdir TwilioSurpriseMessages
cd TwilioSurpriseMessages

Next, create the project with the command below:

dotnet new console

Add the API Key in the project

To add the Twilio Credentials to your project, you will use user secrets since it is a good option for local development that is easy to manage, more secure, and for good development practices.

To set user secrets for your project, run the following commands at the command line inside your project's root folder:

dotnet user-secrets init
dotnet user-secrets set "TwilioAccountSid" "<Twilio Account SID>"
dotnet user-secrets set "TwilioAuthToken" "<Twilio Auth Token>"
dotnet user-secrets set "TwilioMessagingServiceSid" "<Twilio Messaging Service SID>"

Replace <Twilio Account SID> with the Twilio Account SID, <Twilio Auth Token> with the Auth Token, and <Twilio Messaging Service SID> with the Messaging Service SID you copied earlier.

To load user secrets, you must add the Microsoft.Extensions.Configuration.UserSecrets NuGet package. Add the package using the following command:

dotnet add package Microsoft.Extensions.Configuration.UserSecrets

Install the Twilio library

Now, install the Twilio SDK to be able to send SMS messages.

dotnet add package Twilio

Configure the project

Now, in the Program.cs file, replace all existing code with the following:

using Twilio;
using Twilio.Types;
using Twilio.Rest.Api.V2010.Account;
using Microsoft.Extensions.Configuration;

The code above imports all the libraries you'll use in the project.

Next, you are going to add the code that loads the configuration from your user secrets, where you stored the Twilio credentials.

IConfigurationRoot configuration = new ConfigurationBuilder()

string twilioAccountSid = configuration["TwilioAccountSid"];
string twilioAuthToken = configuration["TwilioAuthToken"];
string twilioMessagingServiceSid = configuration["TwilioMessagingServiceSid"];

Schedule SMS messages

Next, you have to initialize the Twilio SDK with your credentials (Account SID and Auth Token), create the messages, and schedule them.

In particular, you are going to create 3 messages, one notifying your partner that there will be a surprise tomorrow, another indicating that at 6 pm they must be in a specific place, and finally, one at 11:59 pm telling them that it was an incredible day.

In the code below, it is indicated that the messages are sent a few minutes apart based on the current date for demonstration purposes. In reality, you should set a fixed UTC date with the DateTime class.

TwilioClient.Init(twilioAccountSid, twilioAuthToken);

var toNumber = new PhoneNumber("<to number>");
var firstMessageOptions = new CreateMessageOptions(toNumber)
    Body = "Hi, tomorrow is a special day. So be ready for a big surprise.",
    MessagingServiceSid = twilioMessagingServiceSid,
    SendAt = DateTime.UtcNow.AddMinutes(16),
    ScheduleType = MessageResource.ScheduleTypeEnum.Fixed

var firstMessage = MessageResource.Create(firstMessageOptions);

Console.WriteLine($"First Message SID: {firstMessage.Sid}");
Console.WriteLine($"First Message Status: {firstMessage.Status}");

// Send second message
var secondMessageOptions = new CreateMessageOptions(toNumber)
    Body = "Today is a special day, so at 6:00 p.m. wait at the corner of Y and X streets.",
    MessagingServiceSid = twilioMessagingServiceSid,
    SendAt = DateTime.UtcNow.AddMinutes(17),
    ScheduleType = MessageResource.ScheduleTypeEnum.Fixed

var secondMessage = MessageResource.Create(secondMessageOptions);

Console.WriteLine($"Second Message SID: {secondMessage.Sid}");
Console.WriteLine($"Second Message Status: {secondMessage.Status}");

// Send the third message
var thirdMessageOptions = new CreateMessageOptions(toNumber)
    Body = "It's 11:59 pm and has been a wonderful day and I hope you have enjoyed this wonderful dinner with me.",
    MessagingServiceSid = twilioMessagingServiceSid,
    SendAt = DateTime.UtcNow.AddMinutes(18),
    ScheduleType = MessageResource.ScheduleTypeEnum.Fixed

var thirdMessage = MessageResource.Create(thirdMessageOptions);

Console.WriteLine($"Third Message SID: {thirdMessage.Sid}");
Console.WriteLine($"Third Message Status: {thirdMessage.Status}");

Replace  <to number> with your personal phone number for testing.

Now, run your console project to send your SMS messages:

dotnet run

To run the project in Visual Studio Code, press Ctrl + F5 to run.

Command line output of sending the messages to Twilio printing their status and Id.

16 minutes later, you should receive three SMS messages similar to the following:

SMS messages received in the mobile phone after the testing

You will have started and ended with surprise messages for your partner, making a special day thanks to scheduled messages through Twilio.

Additional resources

Check out the following resources for more information on the topics and tools presented in this tutorial:

Twilio SDK for C# and .NET – You can explain all the options provided by the Twilio C# SDK.

How to Send Scheduled SMS with C# .NET and Twilio Programmable Messaging – This tutorial shows you how to schedule and cancel scheduled SMS.

Source Code to this tutorial on GitHub - You can find the source code for this project at this GitHub repository. Use it to compare solutions if you run into any issues.

Néstor Campos is a software engineer, tech founder, and Microsoft Most Value Professional (MVP), working on different types of projects, especially with Web applications.