Sveve 1.0.0

This repository contains two packages:

• Sveve A .NET client for the Sveve sms REST API.
• Sveve.AspNetCore Receive sms and delivery reports from Sveve in a .NET API.

Sveve

The Sveve package contains a client for the Sveve REST API.
It is built on netstandard2.0 and therefore supports most .NET environments.

SveveClient

To communicate with Sveve, create a SveveClient:

var client = new SveveClient(new SveveClientOptions
{
    Username = "username",
    Password = "password"
});

Send sms

await client.SendAsync(new Sms("99999999", "Drink water!"));

Sveve limits each account to 5 concurrent requests.
To send multiple messages in a single request, pass an IEnumerable<Sms> instead of a single Sms to SendAsync:

await client.SendAsync([
    new Sms("44444444", "Drink water!"), 
    new Sms("99999999", "You too!")]);

Schedule sms

var sms = new Sms("+47 949 49 494", "A friendly reminder to drink water")
{
    SendTime = DateTimeOffset.Now.AddDays(1);
};
await client.SendAsync(sms);

Repeat sms

Sveve supports repeating messages, but be careful with this one.
Use the SendRepeat class to specify a repetition:

var sms = new Sms("+47 999 99 999", "Am I annoying now?");

// Never repeat the sms. This is the default behaviour.
sms.Repeat = SendRepeat.Never;

// Send the sms once every hour and NEVER stop. ( Please dont )
sms.Repeat = SendRepeat.Hourly();

// Send the sms every two days until the sms has been sent three times.
sms.Repeat = SendRepeat.Daily(days:2).Times(3);

// Send the sms once every month for a year.
sms.Repeat = SendRepeat.Monthly().Until(DateTime.Now.AddYears(1));

await client.SendAsync(sms);

Sender

If the receivers phone supports it and Sender is specified, it will be used as display name for the sender.

To set the default Sender for all messages sent by client:

var client = new SveveClient(new SveveClientOptions
{
    Username = "...",
    Password = "...",
    Sender = "MyCompany"
});

You can also specify a sender on the individual sms:

var sms = new Sms("44444444", "Badabing badabom")
{
    Sender = "MyCompany"
};

Replies

await client.SendAsync(new Sms("444 44 444", "Hello, how are you?")
{
    ReplyAllowed = true
});

This allows the receiver to reply to the sms.
To handle the replies, see Sveve.AspNetCore.

If you have already sent a sms and want to send another to the same thread on the users phone:

// Send the first sms and keep the id.
var response = await client.SendAsync(new Sms("444 44 444", "Hello, how are you?")
{
    ReplyAllowed = true
});

// remember the sms id.
int messageId = response.MessageId("44  44444 4");

// Send another sms to the same conversation/thread on the users phone.
await client.SendAsync(new Sms("44444444", "Pleace don't ignore me :(")
{
    ReplyTo = messageId
});

To receive messages, see Sveve.AspNetCore.

Testing

Test sms are sent to Sveve but not delivered to the receiver.

Test-mode can be enabled for a single sms:

var sms = new Sms("99999999", "Not actually sent") { Test = true };

or for the entire SveveClient:

var client = new SveveClient(new SveveClientOption
{
    Username = "username",
    Password = "password",
    Test = true
});

Groups

Sveve allows you to manage named collections of recipients called groups.
All the groups on your account can be listed with

List<string> groupNames = await client.GroupsAsync();

To work with an individual group, use

SveveGroup group = client.Group("my-group");

// AddMemberAsync creates the group if it does not
// already exist.
await group.AddMemberAsync("99999999", name:"Some Member");

// Does nothing if the group does not exist
// or the member is not in the group.
await group.RemoveMemberAsync("44444444");

// Send sms to Some Member and every other member of my-group.
await client.SendAsync("my-group", "Hello!");

When you are done with a group, you can delete it using

// Does nothing if the group does not exist.
await group.DeleteAsync();

or move all the members from the original group to another group.

SveveGroup myGroup = client.Group("my-group");

// another-group is created if it does not already exist.
await myGroup.MoveToAsync("another-group");

// my-group is now empty.

Admin

To send messages from Sveve, you need sms units. Sms units are bought in advance. To check the remaining amount of sms units on your account call

int remaining = await client.RemainingSmsUnitsAsync();

If you need more sms units, you can buy them in fixed size bulks like this:

await client.PurchaseSmsUnitsAsync(SmsUnitOrder.Bulk500);

Logs and metrics

The client produces logs and metrics all of which are prefixed by Sveve.

Sveve.AspNetCore

The Sveve.AspNetCore package contains everything you need to receive incoming sms and delivery reports from Sveve in a .NET API.

To receive sms and reports, first configure your API, then configure Sveve.

Configure your API

In Program.cs register your consumers on the IServiceCollection. Consumers are registered using

// Consume delivery reports
builder.Services.AddSveveDeliveryConsumer<MyDeliveryConsumer>();

// Consume incoming messages
builder.Services.AddSveveSmsConsumer<MySmsConsumer>();

// Consume all Sveve notifications
builder.Services.AddSveveConsumer<MyConsumer>();

After the app has been build, add an endpoint Sveve can call with notifications:

app.MapSveveConsumerEndpoint("api/sveve");

Configure Sveve

Once your API is configured to consume notifications from Sveve, you need to tell Sveve where to deliver the reports.

Grab the full URL to your Sveve consumer endpoint and head over to Sveve and sign in.
Once there, add the consumer URL to all callbacks:
The endpoint works for both GET and POST

Delivery reports

When a sms sent by you has been delivered or failed to deliver, Sveve will notify you and all the registered ISveveDeliveryConsumers will be invoked with the appropriate callback.

Here is an example delivery report consumer.

class MyConsumer(ILogger logger) : ISveveDeliveryConsumer
{
    public Task SmsDelivered(
        OutgoingSms sms, 
        CancellationToken cancellationToken)
        => Task.CompletedTask;

    public Task SmsFailed(
        OutgoingSms sms, 
        SmsDeliveryError error, 
        CancellationToken cancellationToken)
    {
        logger.LogWarning(
            "Failed to deliver sms to {PhoneNumber}. Reason: {Reason}",
            sms.ReceiverPhoneNumber, error.Description);
        return Task.CompletedTask;
    }
}

Incoming messages

When someone sends you a message, Sveve will notify you and all the registered ISveveSmsConsumers will be invoked with the appropriate callback.

Here is an example sms consumer.
When a user replies to a sms, we reply to them with a joke made by some gpt model.

class MyConsumer(GptModel gpt, SveveClient sveve) : ISveveSmsConsumer
{
    public async Task SmsReceived(
        IncomingSmsReply sms, 
        CancellationToken cancellationToken)
    {
        var joke = await gpt.PromptAsync(
            "You are a very funny comedian who loves to make people laugh." +
            "Make a joke about this: " + sms.Message);
            
        var reply = new Sms(sms.SenderPhoneNumber, "Joke: " + joke)
        {
            // Ensure SMS is added to the same thread
            // as the message the user replied to:
            ReplyTo = sms.MessageId
        };
        
        await sveve.SendAsync(reply, cancellationToken);
    }
    
    public Task SmsReceived(
        IncomingSmsToCode sms,
        CancellationToken cancellationToken)
        => Task.CompletedTask;
    
    public Task SmsReceived(
        IncomingSmsToDedicatedPhoneNumber sms,
        CancellationToken cancellationToken)
        => Task.CompletedTask;
}

Logs and metrics

The consumers produces logs and metrics all of which are prefixed by Sveve.