Introduction

The Outbound Notifications Campaigns (ONC) service allows external applications to register outbound notification campaigns within the system.
An outbound notification is nothing but a request to send a message to a target destination. The message could be delivered using 3 different methods: SMS, Voice Call, and email. In most cases the message is delivered using only one method (for example SMS) but it is possible to use two or all methods available to send the message. The recipient will simply receive the message from that many sources.
Methods

Name	Description
OpenAPISession	Opens a new API session
CloseAPISession	Closes an existing API session

GetCampaignListing	Returns a list containing the IDs of the active campaigns
GetCampaigns	Returns a list containing the active campaigns
AddCampaign	Adds a new campaign
GetCampaign	Returns general information about one campaign
UpdateCampaign	Updates general information about one campaign
DeleteCampaign	Deletes a campaign

GetCampaignContactsListing	Returns a list containing the IDs of all contacts within a campaign
GetCampaignContacts	Returns a list containing all contacts within a campaign
AddCampaignContact	Adds a contact to a campaign
UpdateCampaignContact	Updates a contact within a campaign
DeleteCampaignContact	Deletes a contact from a campaign

OpenAPISession Method

This method verifies the access credentials. If the credentials are valid a new API session is opened, otherwise an error code is returned.
The method must be invoked prior to any other method within the service. A session will expire after 20 minutes of inactivity, it is strongly recommended to close session explicitly by using the CloseAPISession method.
Method Signature:
OpenAPISessionResponse OpenAPISession(string accountId, string username, string password);
Parameters:

Parameter Name	Description
accountId	Id of the account
username	Username of the user account being authenticated
password	Password of the user account being authenticated

The method returns an object of type "OpenAPISessionResponse" that contains the following fields:

Field Name	Type	Description
ErrorCode	Integer	Error code describing the outcome of the operation (0 = Success)
Description	String	Message describing the error condition if applicable
SessionId	String	ID of the API session that was created (if successful, Empty otherwise).

CloseAPISession Method

This method closes an existing API session.
Method Signature:
CloseAPISessionResponse CloseAPISession(string sessionId);
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method

The method returns an object of type "CloseAPISessionResponse" that contains the following fields:

Field Name	Type	Description
ErrorCode	Integer	Error code describing the outcome of the operation (0 = Success)
Description	String	Message describing the error condition if applicable

Retrieving the active campaigns listing

This method returns a list containing the ID of all active campaigns.
Method Signature:
List<Guid> GetCampaignListing(string sessionId);
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method

The method returns a list containing the ID (global unique identifier) of each active campaign.
The list will be empty if no campaign is active.
The list will be null if there is an error while processing the request.

Retrieving the active campaigns

This method returns a list containing general information about all active campaigns.
Method Signature:
List<OutboundNotificationCampaignInfo> GetCampaigns(string sessionId)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method

The method returns a list containing objects of type "OutboundNotificationCampaignInfo".
The list will be empty if no active campaign is found.
The list will be null if there is an error while processing the request.
The OutboundNotificationCampaignInfo data type contains the following fields or properties:

Field Name	Type	Description
ID	Guid	ID of the campaign (global unique identifier)
CreationDateUtc	DateTime	Date and time the campaign was created (UTC)
ShortName	String	Name of the campaign
Description	String	Comments or description about the campaign
IsPaused	Boolean	Determines whether the campaign's execution is paused or not
ActiveFromDate	Date	Date the campaign is to start executing
ActiveFromTime	Time	Time the campaign is to start executing on daily basis
ActiveToDate	Date	Date the campaign is to end executing
ActiveToTime	Time	Time the campaign is to end executing on daily basis
OutboundSMSNotificationInfo	Custom	Encapsulates information to be used when delivering messages over SMS (see below for more details)
OutboundVoiceNotificationInfo	Custom	Encapsulates information to be used when delivering messages over voice (see below for more details)
OutboundEmailNotificationInfo	Custom	Encapsulates information to be used when delivering messages over email (see below for more details)
AllowAddingContactsFromExternalApps	Boolean	Determines whether agents can add contacts to the campaign or not (via CCA application)
SmsNotificationRequired	Boolean	Determines whether message delivery over SMS is mandatory when trying to add a contact via external application (such as CCA).
VoiceNotificationRequired	Boolean	Determines whether message delivery over voice is mandatory when trying to add a contact via external application (such as CCA).
EmailNotificationRequired	Boolean	Determines whether message delivery over email is mandatory when trying to add a contact via external application (such as CCA).
ProgressWSEndpoint	String	A url the service can use as progress indicator

The OutboundSMSNotificationInfo data type contains the following fields or properties:

Field Name	Type	Description
Enabled	Boolean	Determines whether the message delivery over SMS is enabled or not
FromNumber	String	Origination number contacts will see when receiving a message
TextToSend	String	Text to be sent to the contacts (unless otherwise specified at the contact level)

The OutboundVoiceNotificationInfo data type contains the following fields or properties:

Field Name	Type	Description
Enabled	Boolean	Determines whether the message delivery over voice is enabled or not
DialMsTimeout	Integer	Number of milliseconds to wait for an answer when dialing a target destination
CallingName	String	Origination name to be used when dialing a target destination
CallingNumber	String	Origination number to be used when dialing a target destination
TextToSpeak	String	Text to be spoken to the contact (unless otherwise specified at the contact level)
TTSVoiceName	String	Name of the voice to be used when speaking the message (this dictates the language as well)
MaxTextPlays	Integer	Maximum number of times the message is to be played after the call is answered
MaxDeliveryRetries	Integer	Maximum number of attempts to be made in order to deliver the message
RetryMinutesInterval	Integer	Minimum number of minutes to wait before attempting to deliver the message after a previous attempt has been made

The OutboundEmailNotificationInfo data type contains the following fields or properties:

Field Name	Type	Description
Enabled	Boolean	Determines whether the message delivery over Email is enabled or not
FromEmail	String	Origination email address (to be used as sender)
Subject	String	Text to be shown in the email's subject line
HtmlContent	String	Html text to be used as the email's body (unless otherwise specified at the contact level)

Adding a campaign

This method adds a new campaign.
Method Signature:
int AddCampaign(string sessionId, OutboundNotificationCampaignInfo campaign)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaign	General information about the campaign being added

The method returns an error code indicating whether the request was processed successfully (zero) or unsuccessfully (a number different than zero).

Retrieving a campaign

This method retrieves general information about a specific campaign.
Method Signature:
OutboundNotificationCampaignInfo GetCampaign(string sessionId, Guid campaignId)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaignId	ID of the campaign to be retrieved

The method returns null if the specified campaign ID is not valid, otherwise it returns an object of type OutboundNotificationCampaignInfo containing general information about the campaign.

Updating a campaign

This method updates general information about a specific campaign.
Method Signature:
int UpdateCampaign(string sessionId, OutboundNotificationCampaignInfo campaign)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaign	General information about the campaign being updated

The method returns an error code indicating whether the request was processed successfully (zero) or unsuccessfully (a number different than zero).

Deleting a campaign

This method deletes a specific campaign.
Method Signature:
int DeleteCampaign(string sessionId, Guid campaignId)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaignId	ID of the campaign to be deleted

The method returns an error code indicating whether the request was processed successfully (zero) or unsuccessfully (a number different than zero).

Retrieving the list of contacts within a campaign

This method returns a list containing the IDs of all contacts within a campaign.
Method Signature:
List<Guid> GetCampaignContactsListing(string sessionId, Guid campaignId)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaignId	ID of the target campaign

The method returns a list containing the ID (global unique identifier) of each active campaign.
The list will be empty if no campaign is active.
The list will be null if there is an error while processing the request.

Retrieving the contacts within a campaign

This method returns a list containing the information about all contacts within a campaign.
Method Signature:
List<OutboundNotificationContactInfo> GetCampaignContacts(string sessionId, Guid campaignId)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaignId	ID of the target campaign

The method returns a list containing objects of type "OutboundNotificationContactInfo".
The list will be empty if no active campaign is found.
The list will be null if there is an error while processing the request.
The OutboundNotificationContactInfo data type contains the following fields or properties:

Field Name	Type	Description
Id	Guid	ID of the contact
CampaignId	Guid	Id of the campaign the contact belongs to
SMSCommInfo	Custom	Communication information specific to SMS delivery
VoiceCommInfo	Custom	Communication information specific to voice delivery
EmailCommInfo	Custom	Communication information specific to email delivery

SMSCommInfo, VoiceCommInfo and EmailCommInfo are of type CommunicationInfo. This data type contains the following fields or properties:

Field Name	Type	Description
Destination	String	Destination (phone number or email address) to be contacted
TextToSendOverwrite	String	Text to be sent (if blank, the system will use the corresponding text defined at the campaign level)
StatusCode	Integer	Status (do not try = 0; pending = 1; sending = 2; delivering = 3; success = 4; waiting for retry = 5; permanent failure = 6; cancelled = 7)
LastDeliveryErrorCode	Integer	A numeric code describing the result of the previous delivery attempt (zero means successful)
RetryCount	Integer	Number of attempts left (value must be between 0...255)

Adding a contact to a campaign

This method adds a contact to a campaign.
Method Signature:
int AddCampaignContact(string sessionId, OutboundNotificationContactInfo contact)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
contact	The contact's information being added

Notes:

The value specified in the StatusCode is always ignored when adding contacts.
The StatusCode code will be set to 0 if the value of the Destination field is blank, otherwise it will set to 1.
The LastDeliveryError will also be ignored when adding contacts

The method returns an error code indicating whether the request was processed successfully (zero) or unsuccessfully (a number different than zero).

Updating a contact within a campaign

This method updates a contact within a campaign.
Method Signature:
int UpdateCampaignContact(string sessionId, OutboundNotificationContactInfo contact)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
contact	The contact's information being updated

Notes:

Restrictions may apply on some fields such as StatusCode, and LastDeliveryError (those will be ignored when updating the contact's information)

The method returns an error code indicating whether the request was processed successfully (zero) or unsuccessfully (a number different than zero).

Deleting a contact from a campaign

This method deletes a contact from a campaign.
Method Signature:
int DeleteCampaignContact(string sessionId, Guid campaignId, Guid contactId)
Parameters:

Parameter Name	Description
sessionId	ID of the session opened by invoking OpenAPISession method
campaignId	ID of the campaign the target contact belongs to
contactId	ID of the contact being deleted

The method returns an error code indicating whether the request was processed successfully (zero) or unsuccessfully (a number different than zero).

Product Knowledgebase

Dynamic Notifications API

Introduction

OpenAPISession Method

CloseAPISession Method

Retrieving the active campaigns listing

Retrieving the active campaigns

Adding a campaign

Retrieving a campaign

Updating a campaign

Deleting a campaign

Retrieving the list of contacts within a campaign

Retrieving the contacts within a campaign

Adding a contact to a campaign

Updating a contact within a campaign

Deleting a contact from a campaign