What information does the StatusChangePostURL command post?

Phone Notify! utilizes a command called StatusChangePostURL, which will post back information about the phone call to your server. Once you’ve created a web page to handle postbacks, the URL can be set to recieve this information automatically. The following values are posted:

• QueueID – Contains the ID of the Call
• ResponseCode – 1 = Call Answered, 2 or more – Call Unanswered (see all status codes here)
• StartTime – Start time in Universal Time (UTC)
• EndTime – End time in Universal Time (UTC)
• Duration - Call Length in Seconds
• machinedetection – Currently only HUMAN, MACHINE, or FAX
• AC – Contains a status code – this is for advanced problem solving with Tech Support
• digitsdialed – contains all the digits dialed during a call
• incoming – contains true if the call was an incoming call
• [Any Variables you collected] - any additional variables that you collected during the call

Where do I assign the StatusChangePostURL?

There are three scenarios for assigning the StatusChangePostURL command. The first is when using the Advanced methods of Phone Notify! API. You can pass it in the NotifyPhoneAdvanced and NotifyMultiplePhoneAdvanced programming operations. Each operation contains a parameter named, “StatusChangePostURL” where the URL can be input. A URL must be in lower case.

The Basic methods of Phone Notify! do not contain the “StatusChangePostURL” parameter, so an alternative is to assign the URL in the script. In this case, you can include the URL within your script by using the ~\StatusChangePostURL(posturl)~ command. This should be placed at the beginning of your script.

The last scenario includes incoming phone calls. To set the URL in this case, you can log into your account online and specify a URL for each dedicated phone number assigned to your license key as shown in the image below:

For more information about CDYNE Phone Notify! API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE Phone Notify! API.

Developers find CDYNE Phone Notify! API integration details on the CDYNE developer’s wiki.

MT (Mobile Terminated) PostBack Fields

If you specify a PostBackURL in your SMS outgoing request, the following fields can be programmed to postback when a message is sent:

• SMSSent - Always set to “1.”
• MessageID – A unique identifier that matches the initial MessageID from your outgoing SMS.
• ReferenceID – This is populated if you set a reference id in your outgoing request.
• FromPhoneNumber – This is the number that sent your outgoing message.
• ToPhoneNumber – This is the number you sent the SMS to.
• SentTime – UTC Date when the message was sent.

MO (Mobile Originated) PostBack Fields

If you specify a PostBackURL in your SMS outgoing request, or CDYNE assigned you an SMS DID – the following fields can be programmed to postback when a response message is returned, or when an MO message is sent to your DID.

• SMSResponse – Always set to “1.”
• MessageID – A unique identifier for this response. This will come as a GUID.
• MatchedMessageID – A GUID that is populated when the response matches a previous message.
• ReferenceID – This is populated if the response matches a previous message and you set the ReferenceID field in your outgoing SMS.
• FromPhoneNumber – This is the number that sent the response.
• ToPhoneNumber – This is the Local SMS Number that received the message. If you have an assigned DID number from CDYNE, this will be that number. Otherwise it will be a random number from our Phone Number pool.
• ResponseReceiveDate – UTC Date when the message came in.
• Message – This is the incoming SMS Text Message body.

Shared Numbers or DIDs – How to Assign the PostBackURL

There are currently two flavors of CDYNE SMS messaging: shared and dedicated phone numbers. With shared numbers, your application can send SMS messages, and receive responses to those messages. Shared numbers cannot receive MO (Mobile Originated) or customer initiated/inbound text message to your application. You’ll need a DID for MO messages.

You can order a DID through a CDYNE Account Representative. When they assign the DID to your SMS license key, they can also assign the PostBackURL at that time. Alternatively, you can log into your account online and specify a URL for each dedicated phone number assigned to your license key as shown in the image below:

By doing so, all messages sent to or from the DID will be captured with the PostBackURL.

When using CDYNE’s bank of shared phone numbers, you can assign the PostBackURL in the SimpleSMSSendWithPostback or AdvancedSMSSend methods. When using a DID, if the PostBackURL is already assigned, you do not have to pass it in the SimpleSMSSendWithPostback or AdvancedSMSSend methods. If you do put in a PostBackURL, it will override the system URL.

* MT (Mobile Terminated) message – an outgoing message sent from your application. It is a text message that terminates on a mobile device.

* MO (Mobile Originated) message – an inbound message sent to your application that is initiated by the customer (rather than a response to an MT message already sent out). It is a text message that originates from a mobile device.

For more information about CDYNE SMS Notify! API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE SMS Notify! API.

Developers find CDYNE SMS Notify! API integration details on the CDYNE developer’s wiki.

• Reduce residential delivery surcharges
• Lower shipping charges by price-shopping for a service that meets your needs
• Enhance Customer Relationship Management (CRM) by demonstrating efficient and accurate shipping practices
• Identify shipping patterns to improve operational efficiency
• Providing online rate-shopping services on websites

CDYNE PAV API includes an optional RDI flag free of charge. It can be returned with VerifyAddressAdvanced method by setting the parameter “ReturnResidentialIndicator” to “True.” If the address is a residence, PAV will return “N,” and if it is a business, PAV will return “Y.” The following is an example showing an address classified as a business.

Input:

505 independence pkwy, chesapeake, va 23320
Return Residential Indicator: True

Output:

505 INDEPENDENCE PKWY, CHESAPEAKE, VA 23320-5178
Residential Delivery Indicator: N

For more information about CDYNE PAV, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE PAV.

Developers find CDYNE PAV API integration details on the CDYNE developer’s wiki.

TRANSLITERATE ADDRESSES FROM ONE ALPHABET TO ANOTHER

PAV-I supports 9 writing systems and will transliterate address data for Latin, Cyrillic, Greek, Hebrew, Japanese Kanji, Chinese, Arabic, Thai, and Korean Hangul. For example, if you input a Japanese address in English characters, you have the option to request the validated address in either English or Japanese Kanji.

We will use the address 3-24-20, YOKODAI ISOGO-KU YOKOHAMA, 2350045, JAPAN to highlight the transliteration capabilities of PAV-I. The default setting for transliteration is false. When set to true, the verified address will output to the native language if it is supported. The only exception to this is the country output field, which will return in English.

Address entered with native output set to true:

Input Address: 3-24-20 YOKODAI ISOGO-KU YOKOHAMA 2350045 JAPAN

Output Results: A RESCODE of “1″ and OUTPUTSTATUS of “C” combined means the address was successfully matched or parsed and has been corrected to match the reference data. The corrected and transliterated address is output both in the ADDR field as well as the individual address fields. As mentioned earlier, the COUNTRY output field will return in English and does not transliterate.

 

The last output field MATCHLVL returned a “2,” which signifies verification down to the street level. These output returns are meaningful because they provide a record of any corrections that were made to your addresses along with the level to which the addresses were verified. The following MATCHLVL returns are available:

• 0 – No Match
• 1 – Town, City, Locality, Municipality, Suburb
• 2 – Street
• 3 – Premise (Building)
• 4 – Organisation (Varies by country, Business or Administrative Entity)

Address entered with native output set to false:

Input Address: 3-24-20 YOKODAI ISOGO-KU YOKOHAMA 2350045 JAPAN

Output Results: A RESCODE of “1″ and OUTPUTSTATUS of “C” combined means the address was successfully matched or parsed and has been corrected to match the reference data.

INNOVATIVE PARSING ABILITY

PAV-I has the ability to parse addresses entered in one or many fields. Using multiple address fields for input is useful when you are familiar with international addresses and the specific elements of the input address. If uncertain of the specific address elements, inputting information in the wrong fields may complicate or confuse matching.

To illustrate this, let’s use the address Rose House, 51-59 Circular Road, Isle of Man, IM1 1AZ, United Kingdom to show how this address can be entered using fielded or unfielded input.

Address entered with unfielded input:

Input Address: Rose House, 51-59 Circular Road, Isle of Man, IM1 1AZ, United Kingdom

Output Results: A RESCODE of “1″ and OUTPUTSTATUS of “V” combined means the address was successfully matched or parsed and has been verified mailable with no change.

Address entered with fielded input:

Input Address: Rose House, 51-59 Circular Road, IM1 1AZ, United Kingdom

Output Results: In this case, “Isle of Man” was not included in the input data. As a result, RESCODE  “1″ and OUTPUTSTATUS “C” was returned (the address was successfully matched or parsed and has been corrected to match the reference data).

PAV-I VERIFICATION CODES

Addresses are verified with a RESCODE and an OUTPUTSTATUS. The RESCODE returns data based on whether the address was successfully matched or not. The OUTPUTSTATUS provides extra details regarding the verification or correction that occurred when verifying the address. 

For more information about CDYNE PAV-I API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE PAV-I API.

Developers find CDYNE PAV-I API integration details on the CDYNE developer’s wiki

There are two supported operations for Canadian address verification: VerifyAddress and VerifyAddressAdvanced. Only two return codes apply to Canadian addresses. A return code of 200 means that the address was verified. A return code of 202 means that the input address is confirmed for all components except for the secondary number. A return code of 10 means that the address could not be found or verified.

If you have Canadian addresses with missing zip codes, PAV can append the zip code of the address as long as the Canadian province name has been abbreviated at input. Please see image below for an example.

We will use the address 75 University Ave West, Waterloo, ON to emphasize PAV’s ability to append a missing zip code.

Address input with missing zip code:

Address output with appended zip code:

As you can see, the correct zip code has been added and the address yields a return code of 200, meaning that the address is verified.  The address is now prepared for optimum delivery as suggested by the Canada Post with the output address properly parsed in upper case fonts and the zip code separated after the first three characters.

For more information about CDYNE PAV, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE PAV.

Developers find CDYNE PAV API integration details on the CDYNE developer’s wiki.

AN OVERVIEW

There are over 50 Phone Notify! programming operations available to build and integrate voice applications into your system. They can be categorized into the list shown below. Additionally, a detailed operation list by category may be found here.

• Send and Receive Phone Calls
• Status Report Management
• Script Management
• Sound File Management
• List Management

TUTORIALS & SCRIPTING SAMPLES

Tutorials 1 and 2 use C# in Visual Studio 2010. You may find additional source code examples and download code examples from the Phone Notify! developer’s wiki. The script samples show advance scripting features that are available with Phone Notify! API.

• Tutorial 1: Appointment Reminder

Build an appointment reminder using NotifyPhoneBasic and RecordSoundViaPhoneCall methods

• Tutorial 2: Conference Call

Integrate conference calls using NotifyPhoneAdvanced, SetIncomingCallScript, and CancelConference methods

• Script Sample: Advanced Scripting for Appointment Reminder

An advanced scripting example for automated phone reminders

Additional scripting examples for a political poll, school announcement, registration confirmation, survey, and recording sound files may be found on the CDYNE developer’s wiki.

For more information about CDYNE Phone Notify! API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE Phone Notify! API.

Developers find CDYNE Phone Notify! API integration details on the CDYNE developer’s wiki.

The following list shows Phone Notify! operations by category. You may view each method’s parameters, data type, and sample input and output data on the Phone Notify! developer’s wiki . A compiled list of operation notes may also be found in the Phone Notify! Specification PDF.

Send and Receive Phone Calls

Basic Methods for Single or Multiple Calls

NotifyPhoneBasic
This method will call any phone number in the US/Canada and read the TextToSay to that phone number.

NotifyPhoneBasicWithTryCount
Same as NotifyPhoneBasic with a number of times it will retry the call. The max is 3.

NotifyPhoneBasicWithTransfer
This method will call any phone number in the US/Canada and read the TextToSay to that phone number. It also allows you to transfer a call by pressing 0.

NotifyPhoneEnglishBasic
This method will call any phone number in the US/Canada and read the TextToSay to that phone number using the voice of Diane (VoiceID: 0). PhoneNumberToDial must be filled in (They can be in any format as long as there is 10 digits).

NotifyMultiplePhoneBasic
This method will call phone numbers with a default of 3,000 calls per minute (delimited by a semicolon) in the US/Canada and read the TextToSay to that phone number.

NotifyMultiplePhoneBasicWithCPM
This method includes a way to set the calls per minute (CPM) when calling phone numbers in the US/Canada, and will read the TextToSay to that phone number.

Advanced Methods for Single or Multiple Calls

NotifyPhoneAdvanced
Allows you to control notifies with a class. This method allows for the maximum combinations of using Phone Notify! API.

NotifyMultiplePhoneAdvanced
Allows you to control notifies with a class. This function allows multiple notifies to be sent at one time. This allows for the maximum combinations of using Phone Notify! API. We suggest using our list management features for batches over 100.

Additional Methods

CancelNotify
Cancels a single notify. This will not cancel completed calls or calls in progress. You will receive credit for any successfully cancelled notify that returns “true.”

getVoices
This method will list all the voices available for your notification. Use the VoiceID for the Notification Methods

GetIncomingCallScript
Allows you to get the call script for incoming calls for a particular number. You must have incoming phone numbers set by CDYNE Staff.

CancelConference
Cancels a conference by conference key.

Status Report Management

GetQueueIDStatus
Returns a status on a particular QueueID.

GetQueueIDStatusWithAdvancedInfo
Returns a status on a particular QueueID. This also includes variable information and more.

GetQueueIDStatusesByPhoneNumber
Returns the last 10 phone notifications for a particular phone number.

GetMultipleQueueIdStatus
This method returns information about the status of multiple notifies via QueueID (delimited by a semicolon). The QueueID returns a specific phone call ID.

GetResponseCodes
This method will list all of the response codes.

Script Management

ScriptDelete
Script Management – Delete a script.

ScriptList
Script Management – Lists the scripts belonging to a license key. Set IncludeGlobalScripts to true if you would like CDYNE global scripts to be included.

ScriptLoad
Script Management – Load a script’s text.

ScriptSave
Script Management – Save a script (Scriptname can only be 50 characters or less). Saving a script with an existing name will overwrite the old script.

SetIncomingCallScript
Allows you to update a Call Script for incoming calls. You must have incoming phone numbers set by CDYNE Staff.

Sound File Management

UploadSoundFile
Sound file upload. Our system accepts WAV (PCM, U-law, A-law, MS ADPCM) Files. To use the sound file in the notify put ~ around it and start it with a ^.Example “Hello ~^soundfile~, you are cool.”(This would TextToSay “Hello,” and “you are cool,” adding the sound file in the middle).

GetSoundFile
Sound file retrieval.

GetSoundFileInMP3
Sound file retrieval (returns an MP3 encoded in 32,64, or 128).

GetSoundFileInUlaw
Sound file retrieval (returns ULAW encoded file).

GetSoundFileLength
Gets a sound file length in seconds.

GetSoundFileURL
Sound file retrieval. Returns a URL to listen to a particular sound file in MP3.

GetTTSInMP3
Allows you to convert text into a MP3 encoded sound file. Returns an MP3 encoded in 32,64, or 128 (May require a additional License Key).

GetTTSInULAW
Allows you to convert text into a ULAW encoded sound file (May require an additional License Key).

RecordSoundViaPhoneCall
Request the system to call you to record a sound file. SoundfileIDs can only be lowercase and contain normal file characters. The CallerIDName will be the SoundFileID and the number will be 8000000000.

RemoveSoundFile
Sound file delete.

RenameSoundFile
Sound file rename.

ReturnSoundFileIDs
Get available sound files that you can add to your stream via a license key.

List Management

LM_AddListMember
List Management – Allows you to add contacts to a List. You will need the ListID. The only required fields are ListID, PhoneNumber, and LicenseKey. Returns a List Member ID.

LM_AddNewList
List Management – Allows you to add a list that can contain members (Contacts). You can also attach this list to be apart of a Parent List, otherwise leave ParentList ID = 0.

LM_AlterListID
List Management – Allows you alter a ListMember, use 0 if you do not want to have a ParentListID, and -1 if you do not wish to change the ParentListID.

LM_AlterListMember
List Management – Allows you alter a ListMember.

LM_DeleteList
List Management – Deletes a List and its sub-lists (The lists that have is as a ParentListID).

LM_DeleteListMember
List Management – Deletes a List’s Member (or contact).

LM_DialList
List Management – Dial a List by ListID. Returns a Batch ID for the list and begins dialing at the scheduled time. Scheduled times are in UTC.

LM_DialListAdvanced
List Management – Dial a list by ListID that allows you to set more advanced properties.

LM_GetListIDsByLicensekey
List Management – Obtains all list IDs from a specific License key.

LM_GetListMembersByListID
List Management – Gets all the phone numbers with their first and last names.

For more information about CDYNE Phone Notify! API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE Phone Notify! API.

Developers find CDYNE Phone Notify! API integration details on the CDYNE developer’s wiki.

This tutorial uses C# in Visual Studio 2010. You can find additional source code examples and download code examples from the Phone Notify! developer’s wiki.

Phone Notify! Operations Used

• NotifyPhoneAdvanced
• SetIncomingCallScript
• CancelConference

Step 1: Consuming Phone Notify! Web Service

• Open a new or existing project in Visual Studio 2010
• From the top tool bar, go to Project>Add Service Reference, which will open up the following screen:

• Click on the Advanced button in the lower left-hand corner, which will open up another screen:

• Click on the Add Web Reference button, which will open up a third screen:

• Add the Phone Notify WSDL URL: http://ws.cdyne.com/NotifyWS/PhoneNotify.asmx?wsdl to the URL box, and click on the green arrow. This will pull up the Phone Notify! Web Service Description as shown in the next screen:
• Name the web reference. In this case, we named it WSDL. Then click the Add Reference button.

Step 2: Start Conference

The following example uses the NotifyPhoneAdvanced method to receive an incoming phone call, and the SetIncomingCallScript method to set the call script which will initiate a conference call. A dedicated phone number assigned to your account license key is required to receive phone calls.

The script in the code above uses advanced Notify commands that are available with Phone Notify! API. The following list includes notes on these commands:

~\statuschangepostURL(“User’s specified URL”)~
This posts information about the call to a URL you specify. Using this method is highly suggested if you have a server to postback to on the web. The posturl must be in lower case. In this instance, when an inbound call is placed a conference key is posted to the URL specified here.

~\ActOnDigitPress(false)~ 
Turns off Message Interruption for digit commands (i.e., 1 for repeat). This is useful for a message that, for example, says “enter your zip code” and it won’t jump around in the Dial Plan when the digits are pressed.

~\ClearDTMF()~
Provides a clean slate for Acting on DTMF Commands. This will clear the default of “press 1 to repeat.”

~\Label(MainMenu)~
Sets the label, “MainMenu,” which states in TTS “Thank you for calling CDYNE Corporation. Please choose a selection from one of the following options.”

~\AssignDTMF(1|Join)~
Assigns 1 on the dial pad to go to the label “Join.” In this script, the star (*) is subsequently assigned to the label “MainMenu” and the pound sign (#) is assigned to go to the label “EndCall.”

~\WaitForDTMF(5)~
This function will wait 5 seconds for a DTMF Command ( it accepts only one digit). Make sure that ActOnDigitPress(true) is set (It is true by default).

~\Goto(MainMenu)~
This will go to a label defined by the Label command. In this instance, if the recipient does not press a designated digit within 5 seconds, the Goto command instructs the script to go to the MainMenu.    

~\Label(Join)~
Sets the label, “Join,” which states in TTS “Please wait while you are connected to the conference call.”     

~\Conference()~
Provides a way to conference multiple Notifies together. The first Notify that uses the conference command will return a ConfKey variable (you must use StatusChangePostURL to get it). You can then start other Notifies with the same ConfKey to join the person to the same room using the ~\SetVar(ConfKey|the confkey guid)~ command.  

~\Label(Unavailable)~
 Sets the label, “Unavailable,” which states in TTS “We’re sorry no one is available at this time.”  

~\Label(EndCall)~
Sets the label, “EndCall,” which will end the call.                                                               

Step 3: Add a Caller to Conference

In the example below, an outbound call to an operator or representative is initiated to let them know that the caller in Step 2 is in queue. This is done with the NotifyPhoneAdvanced method. If the operator or representative accepts the call, both calls will be joined in a conference.

~\SetVar(ConfKey|”Conference Key”)~
The conference key is placed here. In most cases the servers handling the process will know to grab the conference key generated and posted to the URL during the phone call in Step 2.

Step 4: Cancel Conference

The CancelConference operation cancels the conference if the inbound call (from Step 2) is not accepted by the operator or representative in Step3. It will play the message, “We’re sorry no one is available at this time.” This is specified in Step 2 to play in the event the conference is cancelled.

For more information about CDYNE Phone Notify! API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE Phone Notify! API.

Developers find CDYNE Phone Notify! API integration details on the CDYNE developer’s wiki.

At the time of invoicing, Reseller Web Service customers have three ways to view their account usage and totals. The first view is the main invoice which includes the Web Service monthly fee as well as the total monthly transaction fee per Web Service. Here is an example invoice showing a total of 96 SMS transactions:

So how do you find the transaction and price breakdown of each reseller license key? At the bottom of the invoice there is a statement, “For a detailed report:” with a link that follows. Clicking on this link will open up a separate page with two additional reports:  the CDYNE Corporation billing detail report, and a Breakdown of Summary Items report.

The CDYNE Corporation billing detail report shows a list of each license key under the parent account. It also shows the transactions per key, as well as the total transaction charge per key. Below is an example that shows five license keys for SMS Notify! The first license key ending in “3abc4d” had 25 transactions for a total of 25 cents.

The Breakdown of Summary Items report shows a daily summary of transactions processed per license key. Continuing with the license key ending in “3abc4d,” the report below shows the daily count – starting with 3 transactions on 10/31, and ending with 2 transactions on 11/26.

For more account information, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

A second option is to order DIDs, which are assigned to your SMS Notify! license key. In this case, you would program with the AdvancedSMSSend method which contains a parameter named AssignedDID to input your assigned dedicated number. When using the AssignedDID parameter, the API will send text messages from the DID entered (as long as the DID is assigned to the account license key).

So should you use shared phone numbers or DIDs, and why? There are three key differences between to consider.

Receive Mobile Originated (MO) or Inbound Messages to Your Application

The main difference between the two options is the ability for your application to receive Mobile Originated (MO) messages, or inbound text messages (initiated by your end users). With a DID, your customers can initiate a text message to your application by sending the message to your assigned phone number. When using SMS Notify! shared  numbers, you cannot receive a MO message sent to the shared phone numbers. You can only send messages outbound from your application – but receiving responses to those messages is included via the MessageID (A unique identifier that matches the initial MessageID from your Outgoing SMS).

Determine Your Throughput Needs

The throughput when using CDYNE SMS Notify! shared phone numbers is 1,500 text messages per minute. With a single DID assigned to your account, the throughput is 10 messages per minute; but you have the ability to purchase additional DIDs in order to increase the throughput.

Can the Sender ID be Dynamic, or Should Messages come From the Same Phone Number?

When using the shared pool of numbers, the sender ID will be randomly generated based on the phone number available to send the text message. With an assigned DID, the sender ID remains the same number each time your application sends a message. If your business requires the stability of sending text messages from a constant number, then using a DID makes sense. If the sender ID is inconsequential, and you don’t need the ability to receive MO messages, using the shared phone numbers may make more sense. The advantage here is cost. DIDs cost $1/month/DID in addition to the $9.99 fee and 1 cent per transaction charge. Using shared numbers does not cost extra.

Summary Comparison

For more information about CDYNE SMS Notify! API, please contact an account representative at 1-800-984-3710, inquire by email, or initiate a chat for more details.

Or sign up for a free trial license key to test CDYNE SMS Notify! API.

Developers find CDYNE SMS Notify! API integration details on the CDYNE developer’s wiki.