Author: Bronwen Zande
This article discusses the basics of the using the Alerts SDK and provides some simple helper methods help you write your first alert messages
There are two different types of Live Alerts:
- Alerts based on RSS feeds. Everything you need to know about this type of alert can be found at http://signup.alerts.live.com/brochure/index.jsp
- Alerts based on an SDK. This article concentrates on the Alerts SDK.
After you've applied for you alert pin and password by following the steps at http://msdn2.microsoft.com/en-us/library/bb259769.aspx you're ready to begin. Note: To use alerts you need a fixed IP address.
To show some of the simple functions of alerts I've created a simple ASPX page that allows me to:
- signup
- create a group
- add a user to a group
- send a message to a user
- send a message to a group.
The code for this looks like:
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
<title>Alert Signup</title>
</head>
<body>
<form id="form1" runat="server">
<div>
<asp:TextBox ID="txtEmail" runat="server"></asp:TextBox>
<asp:Button ID="btnSignup" runat="server" Text="Signup for Alerts" OnClick="btnSignup_Click" />
<asp:Label ID="Label1" runat="server" Text="Enter your liveid email to signup for alerts"></asp:Label>
<br />
<asp:TextBox ID="txtGroup" runat="server"></asp:TextBox>
<asp:Button ID="btnGroup" runat="server" Text="Add to Group" OnClick="btnGroup_Click" />
<asp:Label ID="Label2" runat="server" Text="Enter the group you want to be added to"></asp:Label><br />
<asp:TextBox ID="txtMessage" runat="server" Height="167px" Width="306px"></asp:TextBox>
<br />
<asp:Button ID="btnSendToGroup" runat="server" Text="Send to Group" OnClick="btnSendToGroup_Click" />
<asp:Button ID="btnUser" runat="server" Text="Send to User" OnClick="btnSendToUser_Click" /></div>
<asp:Label ID="ErrorMessage" runat="server" />
</form>
</body>
</html>
AlertSignup
Here we take something to uniquely identifier a user. If the user is a new user we then take them to a signup page using the InitiateSignup method.
RecAlertsRequestResponse response =
alertsService.InitiateSignup(createRequestHeader(), createRequestID(), userID, returnURL,
ConfigurationManager.AppSettings["TransportType"]);
switch (response.response.statusCode)
{
case 0:
result = response.URL;
break;
case 326:
// user exists
break;
default:
throw new Exception(
string.Format("Error code: {0}. Error Message: {1}", response.response.statusCode,
response.response.statusReason));
}
Creating a Group and assigning Users
You can create your own groups by calling the AddGroup method.
RecServicesRequestResponse response =
alertsService.AddGroup(createRequestHeader(), createRequestID(), group, group);
RecServicesRequestResponse response =
alertsService.ChangeSubscription(createRequestHeader(), createRequestID(), user, groups, "add", user, 0,
"en-us", "en-us");
Sending Messages
When you send a message to either a list of contacts or a contact group, depending on their delivery preferences, they will be presented with one/all of:
Toast Message with a summary of the message
Messenger history of alerts
Email to their liveid mail address or mobile phone
Sending a message to a user
To send a single message to a single or list of users use the Deliver Method
Live.Alerts.Message.RecServicesRequestResponse response =
messageService.Deliver(createMessageHeader(), createMessageID(), message);
To send a message to a predefined group use the GroupDeliver method
Live.Alerts.Message.RecServicesRequestResponse response =
messageService.GroupDeliver(createMessageHeader(), createMessageID(), message);
using System;
using System.Collections.Generic;
using System.Configuration;
using SoulSolutions.AlertsTest.Live.Alerts.Message;
using SoulSolutions.AlertsTest.Live.Alerts.Subscription;
using RecAlertsRequestResponse=SoulSolutions.AlertsTest.Live.Alerts.Subscription.RecAlertsRequestResponse;
using RecServicesContact=SoulSolutions.AlertsTest.Live.Alerts.Message.RecServicesContact;
using RecServicesHeader=SoulSolutions.AlertsTest.Live.Alerts.Message.RecServicesHeader;
using RecServicesIdentification=SoulSolutions.AlertsTest.Live.Alerts.Message.RecServicesIdentification;
using RecServicesRequestResponse=SoulSolutions.AlertsTest.Live.Alerts.Subscription.RecServicesRequestResponse;
namespace SoulSolutions.AlertsTest
{
public class AlertsHelper
{
public static string CheckUserSignup(string userID, string returnURL)
{
string result = string.Empty;
AlertsWebServicesService alertsService = new AlertsWebServicesService();
RecAlertsRequestResponse response =
alertsService.InitiateSignup(createRequestHeader(), createRequestID(), userID, returnURL,
ConfigurationManager.AppSettings["TransportType"]);
switch (response.response.statusCode)
{
case 0:
result = response.URL;
break;
case 326:
// user exists
break;
default:
throw new Exception(
string.Format("Error code: {0}. Error Message: {1}", response.response.statusCode,
response.response.statusReason));
}
return result;
}
public static void AddUserToGroup(string user, string group)
{
AlertsWebServicesService alertsService = new AlertsWebServicesService();
RecServicesRequestResponse response =
alertsService.AddGroup(createRequestHeader(), createRequestID(), group, group);
switch (response.response.statusCode)
{
case 0:
addUserToGroup(alertsService, group, user);
break;
}
}
private static void addUserToGroup(AlertsWebServicesService alertsService, string group, string user)
{
string[] groups = new string[1];
groups[0] = group;
RecServicesRequestResponse response =
alertsService.ChangeSubscription(createRequestHeader(), createRequestID(), user, groups,
"add", user, 0, "en-us", "en-us");
switch (response.response.statusCode)
{
case 0:
break;
}
}
public static void SendGroupRequest(RecServicesGroupMessage message, string sendtoTransport)
{
MessageWebServicesService messageService = new MessageWebServicesService();
Live.Alerts.Message.RecServicesRequestResponse response =
messageService.GroupDeliver(createMessageHeader(), createMessageID(), message);
switch (response.response.statusCode)
{
case 0:
// success
break;
default:
throw new Exception(
string.Format("Error code: {0}. Error Message: {1}", response.response.statusCode,
response.response.statusReason));
}
}
public static void SendSingleRequest(RecServicesMessage message, string sendtoTransport)
{
MessageWebServicesService messageService = new MessageWebServicesService();
Live.Alerts.Message.RecServicesRequestResponse response =
messageService.Deliver(createMessageHeader(), createMessageID(), message);
switch (response.response.statusCode)
{
case 0:
// success
break;
default:
throw new Exception(
string.Format("Error code: {0}. Error Message: {1}", response.response.statusCode,
response.response.statusReason));
}
}
public static List<RecServicesContact> CreateMessageContacts(List<string> to)
{
List<RecServicesContact> result = new List<RecServicesContact>();
foreach (string person in to)
{
result.Add(CreateMessageContact(person));
}
return result;
}
private static RecServicesContact CreateMessageContact(string to)
{
RecServicesContact contact = new RecServicesContact();
contact.from = ConfigurationManager.AppSettings["AlertFrom"];
contact.to = to;
contact.transport = ConfigurationManager.AppSettings["TransportType"];
return contact;
}
public static RecServicesMessage CreateMessage(string content, string emailMessage,
string messengerMessage,
string mobileMessage,
List<RecServicesContact> contacts)
{
RecServicesMessage message = new RecServicesMessage();
message.content = content;
message.emailMessage = emailMessage;
message.messengerMessage = messengerMessage;
message.mobileMessage = mobileMessage;
message.contacts = contacts.ToArray();
return message;
}
public static RecServicesGroupMessage
CreateGroupMessage(string groupName, string content, string emailMessage,
string messengerMessage, string mobileMessage,
List<RecServicesContact> contacts)
{
RecServicesGroupMessage message = new RecServicesGroupMessage();
message.content = content;
message.emailMessage = emailMessage;
message.messengerMessage = messengerMessage;
message.mobileMessage = mobileMessage;
message.fromContacts = contacts.ToArray();
message.groupName = groupName;
return message;
}
private static RecServicesIdentification createMessageID()
{
RecServicesIdentification recID = new RecServicesIdentification();
recID.PINID = Convert.ToInt32(ConfigurationManager.AppSettings["AlertPIN"]);
recID.PW = ConfigurationManager.AppSettings["AlertPassword"];
return recID;
}
private static RecServicesHeader createMessageHeader()
{
string messageID = Guid.NewGuid().ToString();
RecServicesHeader recHeader = new RecServicesHeader();
recHeader.version = "1.0";
DateTime now = DateTime.Now;
recHeader.timestamp = String.Format("{0}T{1}", now.ToString("yyyy-MM-dd")
, now.ToString("HH:mm:sszzz"));
recHeader.messageID =
string.Format("{0}.{1}.{2}", now.ToString("yyyy-MM-dd"), messageID,
Convert.ToInt32(ConfigurationManager.AppSettings["AlertPIN"]));
return recHeader;
}
private static Live.Alerts.Subscription.RecServicesIdentification createRequestID()
{
Live.Alerts.Subscription.RecServicesIdentification recID =
new Live.Alerts.Subscription.RecServicesIdentification();
recID.PINID = Convert.ToInt32(ConfigurationManager.AppSettings["AlertPIN"]);
recID.PW = ConfigurationManager.AppSettings["AlertPassword"];
return recID;
}
private static Live.Alerts.Subscription.RecServicesHeader createRequestHeader()
{
string messageID = Guid.NewGuid().ToString();
Live.Alerts.Subscription.RecServicesHeader recHeader =
new Live.Alerts.Subscription.RecServicesHeader();
recHeader.version = "1.0";
DateTime now = DateTime.Now;
recHeader.timestamp = String.Format("{0}T{1}", now.ToString("yyyy-MM-dd"),
now.ToString("HH:mm:sszzz"));
recHeader.messageID =
string.Format("{0}.{1}.{2}", now.ToString("yyyy-MM-dd"), messageID,
Convert.ToInt32(ConfigurationManager.AppSettings["AlertPIN"]));
return recHeader;
}
}
}