.NET Wrapper for Text Messaging API
TxtSignalOutboundTextService.cs
- This is the high-level service class for TXT Signal's API. It provides strongly-typed methods to do exactly what the API provides. Not all of the API methods available have been wrapped, so you may need to extend this class some to fit your needs.
< Previous |
Home |
Next >
#region Using Statements
using System;
using System.Collections.Generic;
using System.Text;
using TxtSignal.CoreServices;
using System.Xml;
using System.Net;
using System.Configuration;
#endregion
namespace TxtSignal
{
/// <summary>
/// ******************************************************************
/// * *
/// * This code was written by your good friends at SplashTone.com. *
/// * This code is offered freely in the spirit of knowledge sharing.*
/// * If you find good use out of it, check out our site and maybe *
/// * drop us a line (support@splashtone.com)! *
/// * *
/// * SplashTone.com is a site for booking bands online. *
/// * SplashTone.com is run by OpenBracketLLC.com. *
/// * *
/// ******************************************************************
///
/// Provides an outbound text messaging interface to the TXT Signal
/// text messaging service API.
/// </summary>
public class TxtSignalOutboundTextService
{
#region Members and Constructors
private TxtSignalService _service;
private string _groupName;
public TxtSignalOutboundTextService() :
this(ConfigurationManager.AppSettings["TxtSignal.Options.GroupName"])
{ }
public TxtSignalOutboundTextService(string groupName)
{
_service = new TxtSignalService();
_groupName = groupName;
}
#endregion
#region Properties
/// <summary>
/// Gets the TXT Signal group name to send API calls with.
/// </summary>
private string TxtSignalGroupName
{
get
{
return _groupName;
}
}
#endregion
#region API Method Calls
/// <summary>
/// Creates a team for sending bulk messages to.
/// </summary>
/// <param name="teamName">The team name to create in our TXT Signal account.</param>
public void CreateTeam(string teamName)
{
_service.ActionType = TxtSignalActionType.CreateTeam;
_service.Parameters["group"] = TxtSignalGroupName;
_service.Parameters["team_name"] = teamName;
Submit();
}
/// <summary>
/// Determines if a team exists with this name.
/// </summary>
/// <param name="teamName">The team name to check in our TXT Signal account.</param>
public bool DoesTeamExist(string teamName)
{
try
{
_service.ActionType = TxtSignalActionType.QueryTeam;
_service.Parameters["group"] = TxtSignalGroupName;
_service.Parameters["team_name"] = teamName;
Submit();
XmlNode xItem = _service.ResponseXml.SelectSingleNode("txtsig_response/content[@type='response']/item[@type='team']");
XmlNode xTeamName = null;
if (xItem != null)
xTeamName = xItem.SelectSingleNode("element[@name='team_name']");
if (xTeamName != null && xTeamName.InnerText.Trim().Equals(teamName))
return true;
return false;
}
catch (WebException ex)
{
if (ex.Message.Equals("TXT Signal responded with success = 'false'"))
return false;
throw ex;
}
}
/// <summary>
/// Removes a team so that bulk messages can no longer be sent to this team.
/// </summary>
/// <param name="teamName">The name of the team to remove.</param>
public void DeleteTeam(string teamName)
{
// NOTE: Currently TXT Signal's API is not returning a valid response for this
// call and a NullReferenceException is being thrown.
// The team is indeed deleted, but the API sends back a mal-formed response.
_service.ActionType = TxtSignalActionType.DeleteTeam;
_service.Parameters["group"] = TxtSignalGroupName;
_service.Parameters["team_name"] = teamName;
Submit();
}
/// <summary>
/// Adds a user to this team. If contactID > 0, this method will do the job of creating the
/// contact before adding them to the team.
/// </summary>
/// <param name="contactID">The contactID on file for this user, or -1.</param>
/// <param name="cellCarrier">The cell phone carrier of this user.</param>
/// <param name="cellNumber">The cell phone number of this user.</param>
/// <param name="teamName">The name of the team to add this user to.</param>
/// <param name="firstName">Contact's first name.</param>
/// <param name="lastName">Contact's last name.</param>
/// <returns>The contactID for the new user. When contactID is > 0, this is simply the
/// value that was passed into this method.</returns>
public int AddUserToTeam(int contactID, TxtSignalCellCarrier cellCarrier,
string cellNumber, string teamName, string firstName, string lastName)
{
string[] teams = new string[0];
if (teamName != null)
teams = new string[] { teamName };
if (contactID <= 0)
{
return CreateContact(cellCarrier, cellNumber, firstName, lastName,
teams, true);
}
else
{
UpdateContact(contactID, cellCarrier, cellNumber, firstName, lastName,
teams, new string[] { }, true);
return contactID;
}
}
/// <summary>
/// Removes a contact from a team so that they no longer receive bulk messages that are
/// sent to this team.
/// </summary>
/// <param name="contactID">The contact to remove from the team.</param>
/// <param name="teamName">The team to remove this contact from.</param>
/// <param name="cellCarrier">The new cell phone carrier for this contact.</param>
/// <param name="cellNumber">The new cell number for this contact.</param>
/// <param name="firstName">Contact's first name.</param>
/// <param name="lastName">Contact's last name.</param>
public void RemoveUserFromTeam(int contactID, TxtSignalCellCarrier cellCarrier,
string cellNumber, string teamName, string firstName, string lastName)
{
string[] teams = new string[] { teamName };
UpdateContact(contactID, cellCarrier, cellNumber, firstName, lastName,
new string[] { }, teams, true);
}
/// <summary>
/// Updates information for a contact including the ability to disable text messaging
/// for this contact altogether.
/// </summary>
/// <param name="contactID">The contact to remove from the team.</param>
/// <param name="cellCarrier">The new cell phone carrier for this contact.</param>
/// <param name="cellNumber">The new cell number for this contact.</param>
/// <param name="enableReceivingOfMessages">True to enable all text messages, false to
/// disable text messing to this contact.</param>
/// <param name="firstName">Contact's first name.</param>
/// <param name="lastName">Contact's last name.</param>
public void UpdateUser(int contactID, TxtSignalCellCarrier cellCarrier, string cellNumber,
bool enableReceivingOfMessages, string firstName, string lastName)
{
UpdateContact(contactID, cellCarrier, cellNumber, firstName, lastName,
new string[] { }, new string[] { }, enableReceivingOfMessages);
}
/// <summary>
/// Obtains a list of the valid cell carriers that can be used for a contact's carrier.
/// </summary>
/// <returns>A list of internal_name - > friendly_name for cell phone carriers.</returns>
public Dictionary<string, string> ListAvailableCellCarriers()
{
_service.ActionType = TxtSignalActionType.QueryCarriers;
Submit();
Dictionary<string, string> lstCarriers = new Dictionary<string, string>();
XmlNodeList xCarriers = _service.ResponseXml.SelectNodes("txtsig_response/content/item[@type='carriers']/element");
foreach (XmlNode xCarrier in xCarriers)
{
XmlAttribute xInternalName = xCarrier.Attributes["name"];
lstCarriers[xInternalName.InnerText] = xCarrier.InnerText.Trim();
}
return lstCarriers;
}
/// <summary>
/// Sends a bulk message to all the contacts that belong to this team.
/// </summary>
/// <param name="teamName">The team to send the message to.</param>
/// <param name="messageBody">The message contents to send .</param>
public void SendMessageToTeam(string teamName, string messageBody)
{
_service.ActionType = TxtSignalActionType.SendMessage;
_service.Parameters["broadcast_type"] = "team";
_service.Parameters["group"] = TxtSignalGroupName;
_service.Parameters["has_teams"] = "<team>" + teamName + "</team>";
_service.Parameters["message"] = "<![CDATA[" + messageBody + "]]>";
_service.Parameters["send_now"] = "1";
Submit();
}
/// <summary>
/// Creates a TXT Signal contact from this information.
/// </summary>
/// <param name="cellCarrier">The contact's cell phone carrier.</param>
/// <param name="cellNumber">The cell number to send messages to.</param>
/// <param name="firstName">The first name of the user.</param>
/// <param name="lastName">The last name of the user.</param>
/// <param name="teamsToAddTo">The list of teams to add this user to on creation.</param>
/// <param name="enableReceivingOfMessages">True to enable all text messages, false to
/// disable text messing to this contact.</param>
/// <returns>The created contact ID for this user.</returns>
public int CreateContact(TxtSignalCellCarrier cellCarrier, string cellNumber,
string firstName, string lastName, string[] teamsToAddTo,
bool enableReceivingOfMessages)
{
_service.ActionType = TxtSignalActionType.CreateContact;
AddContactDetails(cellCarrier, cellNumber, firstName, lastName, teamsToAddTo,
new string[] { }, enableReceivingOfMessages);
Submit();
return ParseIDValueFromResponse("contact", "contact_id", true);
}
/// <summary>
/// Updates a TXT Signal contact with new information. This is also the method for
/// adding a contact to teams or removing them from teams.
/// </summary>
/// <param name="contactID">The ID of the contact to update.</param>
/// <param name="cellCarrier">The contact's cell phone carrier.</param>
/// <param name="cellNumber">The cell number to send messages to.</param>
/// <param name="firstName">The first name of the user.</param>
/// <param name="lastName">The last name of the user.</param>
/// <param name="teamsToAddTo">The list of teams to add this user to on creation.</param>
/// <param name="teamsToRemoveFrom">The list of teams to remove this user from.</param>
/// <param name="enableReceivingOfMessages">True to enable all text messages, false to
/// disable text messing to this contact.</param>
public void UpdateContact(int contactID, TxtSignalCellCarrier cellCarrier, string cellNumber,
string firstName, string lastName, string[] teamsToAddTo, string[] teamsToRemoveFrom,
bool enableReceivingOfMessages)
{
_service.ActionType = TxtSignalActionType.UpdateContact;
AddContactDetails(cellCarrier, cellNumber, firstName, lastName, teamsToAddTo,
teamsToRemoveFrom, enableReceivingOfMessages);
_service.Parameters["contact_id"] = contactID.ToString();
Submit();
}
/// <summary>
/// Completely removes a user from the messaging system. This shouldn't be done in most cases,
/// instead call UpdateUser and disable texting.
/// </summary>
/// <param name="contactID">The ID of the user to remove.</param>
public void DeleteUser(int contactID)
{
_service.ActionType = TxtSignalActionType.DeleteContact;
_service.Parameters["group"] = TxtSignalGroupName;
_service.Parameters["contact_id"] = contactID.ToString();
Submit();
}
#endregion
#region Helper API Methods Calls
/// <summary>
/// After an API call is made, this method can be called to see if a specific ID
/// value is returned from TXT Signal. This ID value will be something like
/// contact_id, team_id, etc.
/// </summary>
/// <param name="throwErrorWhenNotFound">If true, this method will throw an error
/// if the ID value should be expected. If false, this method will fail silently, assuming
/// that the ID value was an optional response.</param>
/// <returns>The contactID parsed, or -1 if none was found.</returns>
private int ParseIDValueFromResponse(string xmlAttTypeName, string xmlAttIDName, bool throwErrorWhenNotFound)
{
XmlNode xItem = _service.ResponseXml.SelectSingleNode("txtsig_response/content[@type='response']/item[@type='" + xmlAttTypeName + "']");
if (xItem == null)
{
if (throwErrorWhenNotFound)
throw new XmlException("TXT Signal xml response did not have the appropriate " + xmlAttTypeName + " node");
else
return -1;
}
XmlNode xID = xItem.SelectSingleNode("element[@name='" + xmlAttIDName + "']");
if (xID == null)
{
if (throwErrorWhenNotFound)
throw new XmlException("TXT Signal xml response did not have the appropriate element node for " + xmlAttIDName);
else
return -1;
}
int newIDValue;
if (!int.TryParse(xID.InnerText, out newIDValue))
{
if (throwErrorWhenNotFound)
throw new XmlException("TXT Signal xml response did not have an integer id: '" + xID.InnerText + "'");
else
return -1;
}
return newIDValue;
}
/// <summary>
/// This helper method adds the basic contact parameters when dealing with API
/// calls involving TXT Signal contacts.
/// </summary>
/// <param name="cellCarrier">The contact's cell phone carrier.</param>
/// <param name="cellNumber">The cell number to send messages to.</param>
/// <param name="firstName">The first name of the user.</param>
/// <param name="lastName">The last name of the user.</param>
/// <param name="teamsToAddTo">The list of teams to add this user to on creation.</param>
/// <param name="teamsToRemoveFrom">The list of teams to remove this user from.</param>
/// <param name="enableReceivingOfMessages">True to enable all text messages, false to
/// disable text messing to this contact.</param>
private void AddContactDetails(TxtSignalCellCarrier cellCarrier, string cellNumber,
string firstName, string lastName, string[] teamsToAddTo, string[] teamsToRemoveFrom,
bool enableReceivingOfMessages)
{
StringBuilder sAddTeams = new StringBuilder();
StringBuilder sDelTeams = new StringBuilder();
foreach (string team in teamsToAddTo)
sAddTeams.Append("<team>" + team + "</team>");
foreach (string team in teamsToRemoveFrom)
sDelTeams.Append("<team>" + team + "</team>");
_service.Parameters["group"] = TxtSignalGroupName;
if (sAddTeams.Length > 0)
_service.Parameters["add_teams"] = sAddTeams.ToString();
if (sDelTeams.Length > 0)
_service.Parameters["del_teams"] = sDelTeams.ToString();
_service.Parameters["cell_carrier"] = _service.GetCellCarrier(cellCarrier);
_service.Parameters["cell_number"] = cellNumber.Replace("-", "");
_service.Parameters["receive_messages"] = (enableReceivingOfMessages ? "1" : "0");
_service.Parameters["first_name"] = firstName;
_service.Parameters["last_name"] = lastName;
}
/// <summary>
/// Submits the API service call that has been prepared.
/// </summary>
private void Submit()
{
_service.Submit();
}
#endregion
}
}
< Previous |
Home |
Next > Send any comments or questions here and we will do our best to respond!
support@splashtone.com.
Bored? Check out
our blog.