C-sharp Samples

The following C# code fragments are designed to illustrate how to accomplish a particular task; they generally do not include robust error handling.

Basic Authentication

For every service accessed it is necessary to create the service and attach your credentials to that service as per the following example. The following sample assumes that only the Contact Management and Platform Management services are required. The authentication outlined assumes the WS-Security framework as discussed in the section entitled Integration Requirements.

ContactManagementService contactService = new ContactManagementService();
PlatformManagementService platformService = new PlatformManagementService();
contactService.Url = "https://serviceX.soundbite.com/SOAPAPI/ContactManagementService";
platformService.Url = "https://serviceX.soundbite.com /SOAPAPI/PlatformManagementService";

UsernameToken userToken = new UsernameToken("user", "pwd", PasswordOption.SendPlainText);

contactService.RequestSoapContext.Security.Tokens.Add(userToken);
contactService.RequestEncoding = System.Text.Encoding.UTF8;

platformService.RequestSoapContext.Security.Tokens.Add(userToken);
platformService.RequestEncoding = System.Text.Encoding.UTF8;

Simple invocation

The simplest method supported is the showSystemInfo() method which returns basic information about the version of the platform and other static data.

Response response = platformService.showSystemInfo();
for (int i = 0; i < response.Data.Length; i++)
{
Console.WriteLine("\t" +
((api.Attribute) response.Data[i]).Name + " = " +
((api.Attribute) response.Data[i]).Value);
}

Error/Warning Handling

All methods potentially return both a set of errors and a set of warnings. In general clients should rely on the associated code from the Error/Warning and create their own text to relay to their customers in their language of choice. These codes will remain constant over time and come from the finite set defined in the Error/Warning section. The message provided with the Error/Warning is for convenience/development only.

Response response = platformService.showSystemInfo();
if (response.Errors != null || response.Warnings != null)  {
if (response.Errors != null)
for (int i = 0; i < response.Errors.Length; i++)
Console.WriteLine("Error: " + response.Errors[i].Message);
if (response.Warnings != null)
for (int i = 0; i < response.Warnings.Length; i++)
Console.WriteLine("Warning: " + response.Warnings[i].Message);
}

Create and populate a List

Lists exist in their own right independent of the presence of any contacts in that list. In the following example the list is assumed not to exist and is initially created and then a set of contacts are added to that list.

// Setup the Account (use the account number provided by Professional Services)
Org account = new Org();
account.Type = "Account";
account.InternalId = 400000034;

// Setup the List
List list = new List();
list.Name = "Truancy Notification";
list.Type = "Standard";
list.BaseEntity1 = account;

// Create a new empty list
Response response;
response = contactService.createList(list, account);
list = (List)response.Data[0];

// Add contacts to the list
response = contactService.addToListUsingString(list, "B124908, 617.875.9182", "");

Create a Script

This fragment creates a new script based on a pre-existing template by replacing a prompt with new content. It assumes the existence of the account object created in the 'Create and populate a List' example.

// Load a byte array with the contents of the new prompt
byte[][] promptContent = new byte[][] { loadPrompt("new.wav") };

// Create a new script based on a template and a new prompt file
Script scriptTemplate = new Script();
scriptTemplate.ExternalId = "BasicAlertTemplate";
Response response = campaignService.createScript(
                scriptTemplate,
                "AlertBoston",
                new string[] { "message" },
                promptContent,
                account);
Script script = (Script)response.Data[0];

// Load prompt contents based on file specified
private byte[] loadPrompt(string name)
{
BinaryReader dataIn = null;

try
{
dataIn = new BinaryReader(new FileStream(name, FileMode.Open));
return dataIn.ReadBytes(MAX_PROMPT_SIZE);
}
    catch (Exception e)
    {
Console.WriteLine("PROBLEM: Failed to load prompt file" + e.Message);
return null;
}
finally
{
if (dataIn != null)
dataIn.Close();
}
}

Setting an attribute on a domain object

Many of the domain objects have a set of attributes in addition to the core properties. This sample illustrates setting one of these attributes as part of the object creation.

// Create a list – make sure the list auto-expires at the end of the day
List list = new List();
list.Name = "Truancy Notification";
list.Type = "Standard";
list.BaseEntity1 = account;
api.Attribute expireAfterHours = new api.Attribute();
expireAfterHours.Name = "expireAfterHours";
expireAfterHours.Value = "0";
list.Attributes = new api.Attribute[] { expireAfterHours };
Response response = contactService.createList(list, account);
list = (List)response.Data[0];

Initiate simple SubCampaign (i.e. outreach to customers)

To initiate outreach to a set of customers (defined by list) with a particular interaction (defined by script) use the createSubCampaign method. The behavior of this SubCampaign can be adjusted by using a prototype SubCampaign method (see overrides below).

// Select the existing campaign (i.e. Strategy) for all calling
campaign = new Campaign();
campaign.Name = "200808";
campaign.ExternalId = "200808";

// Specify the name of the Campaign to use and the name of this SubCampaign
SubCampaign overrides = new SubCampaign();
overrides.Campaign = campaign;
overrides.Name = "MySimpleOutreach";

// Initiate calling on the new SubCampaign
response = campaignService.createSubCampaign(overrides, list, script, account);
SubCampaign subCampaign = (SubCampaign)response.Data[0];

Monitor status of an existing SubCampaign

With a handle to an existing SubCampaign it is possible to monitor the status using showSubCampaignState. This will return detailed information about the progress of a particular SubCampaign.

XXXX – BROKEN delivercount etc are attributes!!!!

Response response = campaignService.showSubCampaignState(subCampaign);
SubCampaignState subCampaignState = (SubCampaignState)response.Data[0];
Console.WriteLine("SubCampaign: " + subCampaign.Name + ", State: " + subCampaignState.state);
Console.WriteLine("\tdelivered: " + subCampaignState.deliveredCount +
 ", failed: " + subCampaignState.failedCount);
Console.WriteLine("\tfiltered: " + subCampaignState.filteredCount +
 ", not attempted: " + subCampaignState.notAttemptedCount);

Manage an existing SubCampaign

With a handle to an existing SubCampaign it is possible to manage (i.e. pause, resume, stop, start) using changeSubCampaignState.

response = campaignService.showSubCampaignState(subCampaign);
SubCampaignState subCampaignState = (SubCampaignState)response.Data[0];
// Pause the SubCampaign
subCampaignState.state = "Paused";
response = campaignService.changeSubCampaignState(subCampaignState);

Retrieve results from a SubCampaign

To retrieve results from a SubCampaign use createReportRequest with the Type of the report determining the style of results required. This will queue an asynchronous request to generate a results set; once this request is complete the results can be downloaded.

ReportRequest reportRequest = new ReportRequest();
reportRequest.Type = "All Attempts";
reportRequest.BaseEntity1 = subCampaign;
reportRequest.Frequency = "Now";

// Request a detailed report for the SubCampaign
Response response = reportService.createReportRequest(reportRequest, account);

Job job = (Job) response.Data[0];
JobState jobState = new JobState();

// Wait for queued job to complete
do {
response = platformService.showJobStateUsingJob(job);
jobState = (JobState)response.Data[0];
Thread.Sleep(30000);
} while (jobState.State.Equals("Pending") || jobState.State.Equals("Running"));

// Job is completed now retrieve results
response = platformService.showJobResultAsString(job);
String result = ((JobResult)response.Data[0]).StringResult;