Dynamic Notifications API

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).