voltmx.phone Namespace

The voltmx.phone namespace provides your apps with the ability to access the phone functionality of the user's device, if it is present on the device. The voltmx.phone namespace provides you with the following API elements:

Functions

The voltmx.phone namespace contains the following functions:

voltmx.phone.addCalendarEvent

Adds a new event to the device calendar.

Syntax


voltmx.phone.addCalendarEvent(  
    eventDetails);

Input Parameters

eventDetails

A JavaScript object that contains the following key-value pairs.

Key	Value
summary	A string that contains a short description of the event.
start	A string that holds the start date and time for the event. The format for date is "dd/mm/yyyy", and time is "hh:mm:ss". This must be less than the date and time in the `finish` key,
finish	A string that holds the finish date and time for the event. The format for date is "dd/mm/yyyy", and time is "hh:mm:ss". This must be greater than the date and time in the `start` key.
alarm	An optional number that specifies the time in seconds before the `start` time when the phone must trigger an alarm. This key can be omitted if your app does not need to specify an alarm time.
note	A string that contains the long description of the event.
integer	A integer that defines the occurrence of a event.
access	A string that indicated the privacy setting for the event. The values can be `public`, `private`, or `confidential`

repeatConfig - Optional

A dictionary that indicates the repeat frequency and endRecurrence values for the event. The dictionary contains two values: repeat and endRecurrence.

repeat

A constant that indicates the repeat frequency. The values are as follows:

CALENDAREVENT_REPEAT_NONE
CALENDAREVENT_REPEAT_DAILY
CALENDAREVENT_REPEAT_WEEKLY
CALENDAREVENT_REPEAT_MONTHLY
CALENDAREVENT_REPEAT_YEARLY

endRecurrence [Optional]

A string that stores the recurrence end date and time for the event. The format for the end date and time is "dd/mm/yyyy hh:mm:ss". This date must be greater than the start date and time. For native iOS, if you do not specify the endRecurrence value, the events will repeat for 2 years.

Interval [Optoional]

This allows you to set the interval to repeat the event. It must have a positive integer as value. The default value is 1.

For example, to create a quarterly event, configure ‘repeat’ as constants.CALENDAREVENT_REPEAT_MONTHLY and ‘interval’ as '3'. The repeat event will be created in every 3 months(quarterly).

To create a bi-weekly event, configure ‘repeat’ as constants.CALENDAREVENT_REPEAT_WEEKLY and ‘interval’ as '2'. The repeat event will be created in every 2 weeks (biweekly).

The following example shows how to add quarterly repeat event.

Example


//Sample code to add the Input Parameter **Interval** in the add calendar event to the device   
addCalendarEvent argument  
 var eventobj = {  
summary: "Event started",  
start: this.startTime,  
finish: this.finishTime,  
alarm: 40,  
access: "public",  
“repeatConfig“:{  
“repeat“:contants.CALENDAREVENT_REPEAT_MONTHLY,  
“interval“: 3,  
“endRecurrence”:endDate  
}  
};  
voltmx.phone.addCalendarEvent(eventobj);


function addCalendarEvent() {
    try {
        alert("calendar event is about to start");
        var evtobj = {
            summary: "Event started",
            start: "15/04/2012 11:23:45",
            finish: "16/04/2012 12:59:45",
            alarm: 40,
            note: "Event will end at 12.59 PM",
            access: "public",
            repeatConfig: {
                repeat: constants.CALENDAREVENT\_REPEAT\_MONTHLY,
                endRecurrence: ”21/12/2013 13:00:00”
            }
        }
        voltmx.phone.addCalendarEvent(evtobj);
        //Adds an event to the device calendar
    } catch (PhoneError) {
        alert("error in addCalendarEvent:: " + PhoneError);
    }

}


// To add the calendar event to the device using 'voltmx.phone.addCalendarEvent' APICalendarAddEvent: function(eventObj) {
    try {

        var today = new Date();
        var dd = today.getDate();
        var mm = today.getMonth() + 1;
        var yyyy = today.getFullYear();
        var h = today.getHours();
        var m = today.getMinutes();
        var s = today.getSeconds();
        if (dd &amp; lt; 10) {
            dd = '0' + dd
        }
        if (mm &amp; lt; 10) {
            mm = '0' + mm
        }
        var date = dd + '/
' + mm + ' / ' + yyyy;
        var stime = h + ":" + (parseInt(m) + 2).toString() + ":" + s;
        this.startTime = date + " " + stime;
        var ftime = (parseInt(h) + 1).toString() + ":" + m + ":" + s;
        this.finishTime = date + " " + ftime;
        if (eventObj\["text"\] == "Add calendar event") {
            var evtobj = {
                summary: "Event started",
                start: this.startTime,
                finish: this.finishTime,
                alarm: 40,
                access: "public"
            };
            voltmx.phone.addCalendarEvent(evtobj);
            alert("Calendar event is added with start time = " + this.startTime + ". Please open device calendar to observe this.");
        } else {
            var evtobj = {
                summary: "Event started",
                start: this.startTime,
                finish: this.finishTime,
                alarm: 40,
                access: "confidential"
            };
            voltmx.phone.addCalendarEvent(evtobj);
            alert("Calendar event is added in confidential mode with start time = " + this.startTime + ".");

        }
    } catch (PhoneError) {
        alert("error in addCalendarEvent:: " + PhoneError);
    }
}

Return Values

None

Exceptions

This function throws the following phone exceptions.

Exception	Description
2100	Unable to send the Message
2101	Insufficient Permissions
2102	Cannot open mail, mail not configured
2103	Cannot open media gallery

This function also throws the following general exceptions.

Constant	Description
100	Invalid parameter type.
101	Invalid number of arguments.
102	Invalid input – thrown when the input is invalid based on the context.
103	Invalid operation – thrown when the operation is invalid based on the context.
104	Not supported error – thrown when the method is not supported at all.
105	Index out of range.
106	Unknown error

Remarks

You can view a video on using the Calendar here.

Events cannot be added in the past.

When your app calls this function on Android, it must have both the READ_CALENDAR and WRITE_CALENDAR permissions. Due to Android limitations, when your app sets an alarm with this function the number of seconds are rounded to the nearest minute. Events are added to the local calendar with the calendar name as the application name. They cannot be synched to email accounts.

When your app calls this function on iOS, the app must have NSCalendarsUsageDescription in info plist. Starting iOS 17, app must have NSCalendarsWriteOnlyAccessUsageDescription or NSCalendarsFullAccessUsageDescription in info plist. For more details, refer to Apple documentation.

The time zone of events that your app adds is the same as the device's current time zone.

Platform Availability

iOS
Android version 4.0 and later
Windows

voltmx.phone.cancelVibration

This API stops the ongoing vibration pattern on a device. This API is available from V9 SP2 onwards.

Important: For Android, you must define the VIBRATE permission under Manifest Properties.

Syntax


voltmx.phone.cancelVibration()

Input Parameters

None.

Example


voltmx.phone.cancelVibration();

Return Values

None.

Limitations/Requirements

Windows
- The device must have vibration hardware.
- Device family (Windows OS build version) must be: Windows 10 Creators Update (introduced v10.0.15063.0) or later.
- API contract must be: Windows.Foundation.UniversalApiContract (introduced v4) or later.

Platform Availability

Android
Windows

voltmx.phone.clearSMSListeners

When invoked, this API clears the broadcast receiver and the existing listeners that are registered to retrieve the one-time password (OTP) from the SMS message received.

Syntax


voltmx.phone.clearSMSListeners()

Input Parameters

Parameter	Description
SMSListenerType [Constant] - Optional	The SMSListenerType value can be any of the following: voltmx.phone.SMS_WITH_USER_CONSENT voltmx.phone.SMS_WITHOUT_USER_CONSENT Depending on the parameter value, a specific listener type is cleared. If no type is specified, both type of listeners(if any) are cleared.

Note: Ensure that you create an androidbuild.properties file in the project folder of your Volt MX Iris workspace, and add the following key: addSMSRetrieverSupport = UI.
You can set the key to UI or Non-UI to fetch the required Gradle entries. To know more about adding Android properties to the androidbuild.properties file, click here.

Example


clearAll: function() {
try {
voltmx.phone.clearSMSListeners();
} catch (err) {
alert("Error:: " + err);
}
}

Return Values

None.

Exceptions

101 - Invalid type of arguments to the voltmx.phone.clearSMSListeners API

Platform Availability

Android

voltmx.phone.generateAppHashKey

App hash key is a hash string composed of the app's package name and the app's public key certificate. When invoked, this API generates a hash key that must be included in the SMS message sent from the server to the user's device.

For an app to receive the message callback, the hash key has to be correct.

Note: This API must be invoked only if type of SMS listener triggered is voltmx.phone.SMS_WITHOUT_USER_CONSENT

Syntax


voltmx.phone.generateAppHashKey()

Input Parameters

None.

Note: Ensure that you create an androidbuild.properties file in the project folder of your Volt MX Iris workspace, and add the following key: addSMSRetrieverSupport = UI.
You can set the key to UI or Non-UI to fetch the required Gradle entries. To know more about adding Android properties to the androidbuild.properties file, click here.

Example


generateAppHashKey: function() {
    var key = voltmx.phone.generateAppHashKey();
    voltmx.print("AppHashkey: " + key);
}

Return Values

Return Value	Description
appHashKey[ String ]	Returns a hash key that has to be appended to the SMS message by server.

Platform Availability

Android

voltmx.phone.dial

Enables your app to call the specified telephone number.

You can use this API to make calls to other numbers without leaving the application.

Syntax


voltmx.phone.dial(  
    number);

Input Parameters

Parameter	Description
number	A string containing the phone number to call. Only numbers, +, - and space are treated as valid characters in this string.

Example


dial: function() {
    var number = this.view.tbxDial.text;
    voltmx.phone.dial(number);
},

Return Values

None

Exceptions

2101 - Insufficient Permissions

Remarks

When you make a call to the specified number using this API, the underlying OS is used to make the call. The call charges as imposed by the service provider are applicable.

On the iPhone simulator, this function is a dummy call. You need to test this function on an actual iPhone device.

Platform Availability

Not supported on Windows, iPad, Android Tablets, Desktop Web, and Mobile Web platforms. You can use the phone widget to achieve the same functionality on Mobile Web.

voltmx.phone.findCalendarEvents

This function finds an event in the device's calendar.

Syntax


voltmx.phone.findCalendarEvents(  
    evtobj);

Input Parameters

Parameter	Description
evtobj [Object] - Mandatory	A JavaScript object that can contain the following values:type: "starting" or "ending" or "occuring"start: The start date and time.finish: The end date and time.

Example


var evtobj = {
    type: "starting",
    start: this.startTime,
    finish: this.finishTime
};
var events = voltmx.phone.findCalendarEvents(evtobj);

Return Values

If no matching event is found, this function returns null. If matching events are found, this function returns an array of JavaScript objects containing the matching events. Each JavaScript object contains the following key-value pairs.

Key	Value
summary	A string that contains a short description of the event.
start	A string that holds the start date and time for the event. The format for date is "dd/mm/yyyy", and time is "hh:mm:ss". This must be less than the date and time in the `finish` key,
finish	A string that holds the finish date and time for the event. The format for date is "dd/mm/yyyy", and time is "hh:mm:ss". This must be greater than the date and time in the `start` key.
alarm	An optional number that specifies the time in seconds before the `start` time when the phone must trigger an alarm. This key can be omitted if your app does not need to specify an alarm time.
note	A string that contains the long description of the event.
access	A string that indicated the privacy setting for the event. The values can be `public`, `private`, or `confidential`

Exceptions

This function throws the following phone exceptions.

Exception	Description
2100	Unable to send the Message
2101	Insufficient Permissions
2102	Cannot open mail, mail not configured
2103	Cannot open media gallery

This function also throws the following general exceptions.

Constant	Description
100	Invalid parameter type.
101	Invalid number of arguments.
102	Invalid input – thrown when the input is invalid based on the context.
103	Invalid operation – thrown when the operation is invalid based on the context.
104	Not supported error – thrown when the method is not supported at all.
105	Index out of range.
106	Unknown error

Remarks

The search criteria in the type key in the evtobj parameter can be any of the following values.

Constant	Description
starting	Searches for events starting between "start" and "finish".
ending	Searches for events ending between "start" and "finish".
occurring	Searches for events that have any part of the event occurring during the period specified between "start" and "finish". This is the default.

READ_CALENDAR permission is needed to use this function.

This function is supported on Android 4.0 version and above (that is, Android API 14 and later). Invocation on Android version less than 4.0 ( that is, an Android API level earlier than 14) is ignored.

When your app calls this function on iOS, the app must have NSCalendarsUsageDescription in info plist. Starting iOS 17, app must have NSCalendarsFullAccessUsageDescription in info plist. For more details, refer to Apple documentation.

This function searches only those events that are added by the application.

Platform Availability

iOS
Android 4.0 or later
Windows

voltmx.phone.getRemoveEventOptions

This API returns an array of constants that indicates possible actions for removing a particular event depending on the native support on the device. One of the values that this API returns must be passed as removeOption for voltmx.phone.removeCalendarEvent API.

Syntax


voltmx.phone.getRemoveEventOptions([eventHandle](#eventHandle1))

Input Parameters

Parameter	Description
eventHandle - Mandatory	Single event from the array of events that the voltmx.phone.findCalendarEvents API returns.

Example


var removeOptions = voltmx.phone.getRemoveEventOptions(eventHandle);

Return Values

An array with possible constant values depending on native support in devices. The possible constants that will be returned as part of the array are as follows:

Constant	Description
CALENDAREVENT_REMOVE_THIS	Indicates that only one event must be deleted.
CALENDAREVENT_REMOVE_THIS_AND_FUTURE	Indicates that the event as well as future events must be deleted.

Note: Depending on the OS configuration of certain Android devices, any of these two values may not be applicable. So before passing any of these two values in the API, you must verify if the Android device supports the required value.

Platform Availability

iOS
Android
Windows

voltmx.phone.hasVibratorSupport

This API returns whether vibrator is supported on a device. This API is available from V9 SP2 onwards.

Important: For Android, you must define the VIBRATE permission under Manifest Properties.

Syntax


voltmx.phone.hasVibratorSupport()

Example


hasVibratorSupport: function() {
    if (voltmx.phone.hasVibratorSupport() === true) {
        alert("The device contains a Vibration motor");
    }
},

Input Parameters

None.

Return Values

Boolean is the return value.

Return Value	Description
true	The device supports vibrator.
false	The device does not support vibrator.

Limitations/Requirements

Windows
- The device must have vibration hardware.
- Device family (Windows OS build version) must be: Windows 10 Creators Update (introduced v10.0.15063.0) or later.
- API contract must be: Windows.Foundation.UniversalApiContract (introduced v4) or later.

Platform Availability

Android
Windows

voltmx.phone.openEmail

This API allows the application to launch the native email client with predefined email addresses, subject, body, and attachments.

Syntax

voltmx.phone.openEmail(torecipients,ccrecipients, bccrecipients, subject, messagebody, ismessagebodyhtml, attachments, viewMode, filterEmailAppsOnly)

Input Parameters

Parameter	Description
torecipients [Array of Strings] - Mandatory	List of email addresses to be included in the “to” list. For example, “john@example.com”,”stephen.joseph@voltmx.com”, and “test@somecompany.com”.
ccrecipients [Array of Strings] - Optional	List of email addresses to be included in the “cc” list. For example, “john@example.com”,”stephen.joseph@voltmx.com”, and “test@somecompany.com”. If you do not want to use this parameter, you can pass null value.
bccrecipients [Array of Strings] - Optional	List of email addresses to be included in the “bcc” list. For example, “john@example.com”, “stephen.joseph@voltmx.com”, and “test@somecompany.com”.If you do not want to use this parameter, you can pass null value.
subject [String]- Optional	Subject to be part of the email. If you do not want to use this parameter, you can pass null value.
messagebody [String] -Optional	Body to be part of the email. If you do not want to use this parameter, you can pass null value.
ismessagebod.html [Boolean] - Optional	If you do not want to use this parameter, you can pass null value. When you pass null value, this parameter defaults to false. true: message body must be treated as HTML content false: message body must not be treated as HTML content true:message body must be treated as HTML content false:message body must not be treated as HTML content Note: Windows 10 platform do not support HTML body. This is an underlying SDK limitation.
attachments [Array of Objects] - Optional	Each attachment is a Hash-table with the following key-value pairs. If you do not want to use the attachments parameter, you can pass null value. mimetype [String]Standard mime types like image/png or image/jpg or image/* etc. attachment [Object]Rawbytes received from the camera, image widget, or openmediagallery api. filename (Optional) [String]name of the file to appear as attachment. Note: In Android, filename property is not supported.The Android SDK does not provide any provision for giving file name in attachments while launching native email Application. For more information on how to attach files in Android, click here
viewMode [Integer] - Optional	Defines the possible view preferences for an email client window. This is a Windows-specific parameter. The values of viewMode are as follows: 0 - Default value Defaults to half, which means, the window uses 50% (half) of the available horizontal screen pixels. 1 - UseLess The window uses less than 50% of the available horizontal screen pixels. 2 - UseHalf The window uses 50% (half) of the available horizontal screen pixels. 3 - UseMore The window uses more than 50% of the available horizontal screen pixels. 4 - UseMinimum The window uses the minimum horizontal pixel width (either 320 or 500 pixels) specified in the app's manifest file. 5 - UseNone The window uses no visible component. If you pass any value other than an integer, the "openEmail : mode must be integer" error message is displayed. Note: viewMode is specific only to Windows and is ignored for all other platforms. For all other devices, the viewMode parameter falls back to its default behavior.
filterEmailAppsOnly [Boolean] - Optional	Set this parameter to true to filter and list only email applications, which are shown in the Chooser dialog box. By default, the value of this parameter is false. If you do not want to use this parameter, you can pass a null value. Note: This property is only available on the Android platform. On Android 11 (Target SDK version 30, or later) devices, if you want to view a filtered list of email applications, add the following entry in the Project Settings > Native > Android Mobile/Tablet > Child tag entries under <manifest> tag field: `<queries> <intent> <action android:name="android.intent.action.SENDTO" /> <data android:scheme="mailto"/> </intent> </queries>`

Example


emailSend: function() {
    voltmx.phone.openEmail(["kitchensinkapp@voltmx.com"], [""], [""], "Feedback on KitchenSink Application 1.1", "", false, []);
}

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

2100 - Unable to send the Message
2101 - Insufficient Permissions
2102 - Cannot open mail, mail not configured
2103 - Cannot open media gallery

Platform Availability

Available on all platforms except Server Side Mobile Web, SPA, and Desktop Web.

For these platforms you can launch the native email client by using Richtext widget with an href tag similar to the one shown below:

Email Me

voltmx.phone.openMediaGallery

This API allows you to open the picture gallery of the mobile device and pick an existing picture.

You can use this API to use any of the multimedia resources (image files, audio files, or video files) available in the device media gallery within your application.

For iPad, openMediaGallery will show the Photos/Videos in the native popover. The popover can be anchored to a widget. The widget to which the popup should be anchored will be provided as a third parameter to openMediaGallery API.

You can view a video on using iPad Popover here.

Note:
For Android below permissions are required in IRIS project setting -> Native-> Android Mobile/Tablet -> Tags (Child tag entries under tag) depending on the target version.
If target version is 33 and above below media permission must be added.
< uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
< uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
< uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
If target version is 34 and above below permission must be added along with other media permissions.
< uses-permission android:name="android.permission.READ_MEDIA_VISUAL_USER_SELECTED"/>
Click here For more information on Android 14 behavioral change, also for understanding other media permissions please refer Android 13..

Syntax


voltmx.phone.openMediaGallery([onselectioncallback](#onselectioncallback), [querycontext,](#querycontext) [PSP](#PSP))

Input Parameters

Parameter	Description
onselectioncallback [Function] - Mandatory	This callback function is invoked when a media is selected. The function receives rawbytes and permStatus as parameters. rawbytes: Raw bytes of a selected file. permStatus: Permission status whether an app has permission to access the media gallery of the device. For iOS: Generally, an app needs runtime permission from the end-user to access the media gallery. If you call the API without obtaining the permission, platform automatically pops up a system permission dialog box with "Allow" and "Deny" options, asking the end-user to grant permission to add a contact to the device.If the end-user taps the "Allow" option, platform proceeds to access the underlying OS API. If the end-user taps the "Deny" option, the rawbytes parameter carries null value and the permStatus parameter holds the voltmx.application.PERMISSION_DENIED constant value indicates the permission to access the media gallery is denied.For Android: This parameter reads the external storage permission that is required to read contents from the media gallery. If you call the API without obtaining the required permission, the platform automatically pops up a system permission dialog containing 'Allow' and 'Deny' options, asking the end user to grant the necessary permission. If the end user taps the 'Allow' option, the platform proceeds to access the underlying OS API. If the end user taps the 'Deny' option, the rawbytes parameter carries null value and the permStatus parameter holds the voltmx.application.PERMISSION_DENIED constant value, which indicates that the permission to access the media gallery has been denied. mimeType: The file format of a selected file. For more information on the standard mime types, refer to the IANA. Examplefunction onSelectionCallback(rawbytes, permStatus, mimeType) { if(rawbytes != null) { //access the rawbytes alert(“file format: ”++mimeType); } else if (permStatus == voltmx.application.PERMISSION_DENIED) { alert(“Permission Denied to Access the Photo Gallery”); } } var querycontext = { mimeType: "video/*" }; var returnStatus = voltmx.phone.openMediaGallery(onSelectionCallback, querycontext);
querycontext [Table] - Optional	Query context is an Object that can be populated with key-value pairs for fine tuning the media items for display (currently only one key "mimetype" supported to query the gallery items ). The possible values of the mimetype key can be image/, video/, audio/*. rawbytes.getRawbytesType () This API returns the type of rawbytes that are obtained from onSelectionCallback of openMediaGallery. Rawbytes can be of different types such as image, audio, video, file, bytes, and livePhoto. This API is available from V9 SP2 onwards. var rawbytesType = rawbytes.getRawbytesType(); To check the obtained rawbyte type, the following constants can be used: constants. RAWBYTES _IMAGE: rawbytes related to image constants. RAWBYTES _VIDEO: rawbytes related to video constants. RAWBYTES _AUDIO: rawbytes related to audio constants. RAWBYTES _FILE: rawbytes related to files constants. RAWBYTES _BYTES: rawbytes related to bytes constants. RAWBYTES _LIVEPHOTO: rawbytes related to livePhoto if(rawbytes.getRawbytesType() == constants. RAWBYTES_LIVEPHOTO) { // app logic } livePhotoResources - Rawbytes Property Returns both image and file paths, using this property you can get the both image and video paths. This property returns a json containing both video and image paths, and is available from V9 SP2 onwards. It contains the following keys: imageURL: path of stored image related to livePhoto. videoURL: path of stored video related to livePhoto. var livePhotoResources = Rawbytes.livePhotoResources;//Example for creating Live photos using FFIFunction onSelectionCallback(){ if (rawbytes !== null) { if (rawbytes.getRawbytesType() == constants.RAWBYTES_LIVEPHOTO) { globalArrOFURLS = rawbytes.livePhotoResources; alert(globalArrOFURLS); var livePhotosFFIObject = new PHVFFI.livePhotosFFI(); //Invokes method 'createLivePhoto' on the object livePhotosFFIObject.createLivePhoto(globalArrOFURLS); } frmHome.imgOne.rawBytes = rawbytes; } else if (permStatus == voltmx.application.PERMISSION_DENIED) { alert("PERMISSION_DENIED"); } } } var returnStatus = voltmx.phone.openMediaGallery(onSelectionCallback, querycontext);
PSP [Table] - Optional	The PSP parameter is a dictionary with the following properties. widgetref [Widget Reference]: Applicable only on iPad. The widget to which the pop-up will be anchored to. For example, formname.widgetname. compressionlevel: Compression level is a float value. Specify 0.0 for most compressed images and 1.0 for least compressed images.

Example


openMediaGalleryForEmail: function() {
    voltmx.phone.openMediaGallery(this.openMediaGallaeryCallBck, {
        mimetype: "image/*"
    });
}

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

2100 - Unable to send the Message
2101 - Insufficient Permissions
2102 - Cannot open mail, mail not configured
2103 - Cannot open media gallery

Platform Availability

Supported on all platforms except Mobile Web, SPA, and Desktop Web.

voltmx.phone.performHapticFeedback

This API provides various haptic feedback to users, and is available from V9 SP2 onwards.

Syntax


voltmx.phone.performHapticFeedback(hapticFeedbackValue)

Input Parameters

hapticFeedbackValue [constant] – Mandatory

Indicates the type of haptic feedback. Its possible values are as follows:

hapticFeedbackValue	Description
0 - voltmx.hapticFeedback.SUCCESS	Triggers a haptic feedback for a successful event.
1 - voltmx.hapticFeedback.WARNING	Triggers a haptic feedback that represents a warning to users.
2 - voltmx.hapticFeedback.FAILURE	Triggers a haptic feedback for a failure event.
3 - voltmx.hapticFeedback.LIGHT	Triggers a haptic feedback of light intensity.
4 - voltmx.hapticFeedback.MEDIUM	Triggers a haptic feedback of medium intensity.
5 - voltmx.hapticFeedback.HEAVY	Triggers a haptic feedback of high intensity.
6 - voltmx.hapticFeedback.SELECTION	Triggers a haptic feedback that represents a selection/state change.

Example


hapticFeedback: function(){
  voltmx.phone.performHapticFeedback(5);
}

Return Values

None.

Remarks

iOS
- The Haptic Feedback feature is available on iPhone 7 devices and later. These devices have Taptic Engine hardware and users can enable/disable Haptics from Device Settings-> Sounds & Haptics-> System Haptics.
Android
- Users can enable the Vibrate on touch feature from Settings-> Sound & notification-> Other sounds.

Platform Availability

iOS

voltmx.phone.removeCalendarEvent

This API either deletes a single event or a series of repeat events starting from the date specified in the eventHandle from the device calendar, depending on the provided removeOption parameter. While deleting a series of recurring events, the API deletes all subsequent events beginning from the date specified in the eventHandle; however, the API does not delete any repeat event that is before the specified date.

Note: To delete an event, you must first search for the event by using the findCalendarEvents API and delete the event.

Syntax


voltmx.phone.removeCalendarEvent([eventHandle](#eventHandle), [removeOption](#removeOption))

Input Parameters

Parameter

Description

eventHandle [Object] - Mandatory

Event handle is returned by the find operation.

removeOption - Optional

This parameter is considered only for recurring events. If you do not specify a value for this parameter or pass an invalid value for a recurring event, the current event as well as future recurrences are deleted. Default fallback value of removeOption is constants.CALENDAREVENT_REMOVE_THIS_AND_FUTURE. You can fetch possible removeOption values for delete events by using the voltmx.phone.getRemoveEventOptions API. The following constants are available for removeOption: CALENDAREVENT_REMOVE_THIS : Indicates that only one event should be deleted. CALENDAREVENT_REMOVE_THIS_AND_FUTURE : Indicates the event as well as future events should be deleted.

Example


//To remove the calendar event from the device using 'voltmx.phone.removeCalendarEvent' API

CalendarRemoveEvent: function() {
    if (this.startTime === "undefined" || this.startTime === undefined) {
        this.view.lblPhone.text = "Please create the calendar event.";
        return;
    }
    var evtobj = {
        type: "starting",
        start: this.startTime,
        finish: this.finishTime
    };
    var events = voltmx.phone.findCalendarEvents(evtobj);

    voltmx.phone.removeCalendarEvent(events[0]);
    alert("Calendar event is removed. Please open device calendar to observe this");
}


voltmx.phone.removeCalendarEvent(events\[1\],constants.CALENDAREVENT\_REMOVE\_THIS);  
voltmx.phone.removeCalendarEvent(events\[1\],constants.CALENDAREVENT\_REMOVE\_THIS\_AND\_FUTURE);  
voltmx.phone.removeCalendarEvent(events\[1\]); //If it is non-recurring, the current event is deleted; however, if it is a recurring event, the event as well as future events will be deleted.

Return Values

None.

Exceptions

PhoneError

The following error codes are defined for Phone APIs

2100 - Unable to send the Message
2101 - Insufficient Permissions
2102 - Cannot open mail, mail not configured
2103 - Cannot open media gallery

Error

100 – invalid type of parameters
101 – invalid number of arguments
102 – invalid input – thrown when the input is invalid based on the context.
103 – invalid operation – thrown when the operation is invalid based on the context.
104 – not supported error – thrown when the method is not supported at all.
105 – index out of range.
106 – unknown error.

Platform Availability

iOS
Android
Windows

Remarks

READ_CALENDAR and WRITE_CALENDAR permissions are needed for this API.
This API is supported for Android 4.0 version and above (that is, Android API level later to 13). Invocation on Android version less than 4.0 ( that is, Android API level earlier to 14) will be ignored.
When your app calls this function on iOS, the app must have NSCalendarsUsageDescription in info plist. Starting iOS 17, app must have NSCalendarsWriteOnlyAccessUsageDescription or NSCalendarsFullAccessUsageDescription in info plist. For more details, refer to Apple documentation.
If this API removes last calendar event added to local calendar, then the local calendar account will be deleted.

voltmx.phone.retrieveSMS

When invoked, this API reads an SMS message received from the server. The API then retrieves the one-time password (OTP) from the message if it matches with the config provided.

Syntax


voltmx.phone.retrieveSMS(callback, SMSConfig);

Input Parameters

SMSConfig [Object] - Optional

SMSConfig supports the following key-value pairs:

Key	Description
OTPSizeLimit [Number] - Optional	Expected/desired size limit of the OTP. If the OTPSizeLimit is not specified, the default size limit is 6.
OTPType [Constant] - Optional	Expected/desired type of OTP. [ voltmx.phone.SMS_ALPHANUMERIC_OTP or voltmx.phone.SMS_NUMERIC_OTP] The default type is Numeric.
OTPRegex [String] - Optional	Customized regex to retrieve OTP or PIN as required. If customized regex is provided, all the other criteria such as OTPSizeLimit and OTPType are neglected.
SMSListenerType [Constant] - Optional	Type of SMS listener to be triggered. Following are the SMS listener types: voltmx.phone.SMS_WITHOUT_USER_CONSENT: Using this constant, OTP would be retrieved automatically without any user interaction. In this case, the message that you send from the server to the user's device must fulfill the following: Be no longer than 140 bytes Contain a one-time code that the client sends back to your server to complete the verification flow Include an 11-character hash string that identifies your app To generate a hash key, use any of the following ways: The command-line procedure to generate hash. For more information on computing an app's hash string, refer here. The generateAppHashKey API to generate the hash key when signed in with the production keystore. Here is a sample message format: 123ABC78 FA+9qCX9VSu (123ABC78 is the one-time code and FA+9qCX9VSu is the hash string) voltmx.phone.SMS_WITH_USER_CONSENT: The User Consent Screen is displayed to users after the SMS with an OTP is received. The OTP would be retrieved only after user grants access to the SMS through the User Consent Screen. In this case, the message that you send from the server to the user's device must fulfill the following: Contain a 4-10 character alphanumeric string with at least one number. Is sent by a phone number that's not in the user's contacts.
SMSSenderDetails [String] - Optional	SMS sender details may be specified only if `SMSListenerType = voltmx.phone.SMS_WITH_USER_CONSENT.` In this case, OTP will be retrieved only if the SMS was sent by that phone number specified in SMSSenderDetails key. The sender's phone number should be of E.164 format.

callback [Function] - Mandatory

The callback executed to communicate the SMS Listener Registration status and response of API. The syntax of the callback function is:

callback(callbackObject)

The callbackObject contains SMS and status key value pairs.

SMS key: SMS object, the value of the SMS key is populated only when code is equal to voltmx.phone.SMS_RETRIEVED_SUCCESSFULLY. In case of any error, the SMS object is null.

The SMS object contains the following key-value pairs:

Key	Description
message [String]	SMS received
OTP [String]	Retrieved OTP from SMS

Note: The OTP value returned can be null/empty if the message doesn't contain any OTP matching the SMSConfig.

status key: Value of the status key contains the following key-value pairs:

Key	Description
code[Number]	status code
message[String]	status message

The code key can have any of the following values. A code value is populated when the scenario in the corresponding description occurs.

The following codes specify if the framework is successful in starting the SMS listener.

Code	Description
voltmx.phone.SMS_LISTENER_REGISTRATION_SUCCESS	SMS listener registered successfully. You must request the server for OTP only after the successful registration status is conveyed in a message callback.
voltmx.phone.SMS_LISTENER_REGISTRATION_FAILED	SMS listener registration failed.

The following codes are applicable only after voltmx.phone.SMS_LISTENER_REGISTRATION_SUCCESS is received.

Code	Description
voltmx.phone.SMS_RETRIEVED_SUCCESSFULLY	SMS retrieved successfully.
voltmx.phone.SMS_TIMEOUT	The SMS listener has timed out as No SMS is received within 5mins of trigger of API.
voltmx.phone.SMS_DEVELOPER_ERROR	Caller app has incorrect number of certificates. Only one certificate is allowed. This can occur only when SMSListenerType is set to voltmx.phone.SMS_WITHOUT_USER_CONSENT.
voltmx.phone.SMS_ERROR	App-code collides with other installed apps. This can occur only when SMSListenerType is set to voltmx.phone.SMS_WITHOUT_USER_CONSENT.
voltmx.phone.SMS_USER_CANCELLED	While SMSListenerType = voltmx.phone.SMS_WITH_USER_CONSENT, user denies OTP retrieval. This can occur only when SMSListenerType is set to voltmx.phone.SMS_WITH_USER_CONSENT.
voltmx.phone.ACTIVITY_NOT_FOUND	While SMSListenerType = voltmx.phone.SMS_WITH_USER_CONSENT, an activity cannot be found to launch the Consent dialog. This can occur only when SMSListenerType is set to voltmx.phone.SMS_WITH_USER_CONSENT.
voltmx.phone.SMS_UNKNOWN_ERROR	Any error with unknown root cause.

Note: Ensure that you create an androidbuild.properties file in the project folder of your Volt MX Iris workspace, and add the following key: addSMSRetrieverSupport = UI.
You can set the key to UI or Non-UI to fetch the required Gradle entries. To know more about adding Android properties to the androidbuild.properties file, click here.

Example


retrieveOTPFromSMS: function() {


    SMSConfig = {}
    SMSConfig.OTPSizeLimit = 4;
    SMSConfig.OTPType = voltmx.phone.SMS_NUMERIC_OTP;
    SMSConfig.SMSListenerType = voltmx.phone.SMS_WITH_USER_CONSENT;
    SMSConfig.SMSSenderDetails = null;
    try {
        voltmx.phone.retrieveSMS(callback, SMSConfig);
    } catch (err) {
        voltmx.print("ERROR:" + err);
    }


    function callback(callbackObj) {
        statusCode = callbackObj.status.code;

        voltmx.print("STATUS_CODE::" + statusCode);

        if (statusCode == voltmx.phone.SMS_LISTENER_REGISTRATION_SUCCESS) {
            //ADD CODE TO INDICATE SERVER TO SEND OTP
        }

        if (statusCode == voltmx.phone.SMS_RETRIEVED_SUCCESSFULLY) {
            voltmx.print("message:" + callbackObj.SMS.message)
            voltmx.print("otp:" + callbackObj.SMS.OTP)
            alert(callbackObj.SMS.OTP)
        }

    }

Return Values

None

Limitations

You must start an SMS retriever only after the previous registered retriever responds with a success or failure response. However, if you register a second SMS retriever before the first SMS retriever provides a response, the possible limitations are as follows:

When two SMS retrievals without a user's consent run simultaneously, the SMS callbacks are triggered in the same sequence in which they are registered. This sequence might not be same as the sequence in which the user has sent the requests to the server. As a result, a mismatch in the provided OTP config might occur.
When two SMS retrievals with a user's consent provide two unique sender details for two parallel SMS retrieval registrations, the SMS callbacks are triggered in the same sequence in which they are registered. The SMS details received at the native level does not contain the senders information. Consequently, a mismatch between the senders might occur.

Exceptions

Error Codes:

100 - Invalid number of arguments to API voltmx.phone.retrieveSMS()
101 - Invalid type of arguments to API voltmx.phone.retrieveSMS()

Platform Availability

Android

voltmx.phone.sendSMS

This API provides access to the Messaging service of the underlying platform. You can send a text message to a specified number. This API accesses the messaging application of the underlying platform and uses that application to send text message to the specified number.

Important: You can send only text messages and multimedia messages are not supported.

Note: When you send messages using this API, the charges as imposed by the Service Provider are applicable. On iPhone this API opens the Messages application with a prepopulated text and number.

You can use this API to send messages to other numbers without leaving the application.

Syntax


voltmx.phone.sendSMS([phonenumber](#phonenumber), [text](#text))

Input Parameters

Parameter	Description
phonenumber [String] - Mandatory	Number to which the SMS must be sent.
text [String] - Mandatory	Content of the SMS.

Example


sendSMS: function() {
    if (voltmx.os.deviceInfo().model == "iPhone Simulator") {
        alert("Works only on device");
    } else {
        var phoneNo = "+91 40 12345678"; // This is a dummy number
        var text = "Hi Volt MX developer";
        voltmx.phone.sendSMS(phoneNo, text);
    }
}

Return Values

None

Exceptions

PhoneError

The following error codes are defined for Phone APIs

2100 - Unable to send the Message.
2101 - Insufficient Permissions.

Remarks

When you send messages using this API, the messaging application of the underlying platform is used to send the message with the number and text you specified i.e., the phone number and the message are pre-populated in the messaging application.

Platform Availability

Available on all platforms except Desktop Web,SPA, Mobile Web, Android Tablets, iPad.

Note: This API allows you to send only text messages. It does not support multimedia messages.

voltmx.phone.startVibration

This API starts the vibration feature on a device, provided that device supports vibration. If the device does not support vibration, this API has no effect. If a vibration pattern is already in progress when this API is called, the previous pattern is halted and the new one begins. This API is available from V9 SP2 onwards.

Important: For Android, you must define the VIBRATE permission under Manifest Properties.

Syntax


voltmx.phone.startVibration (vibrationConfig, repeat)

Input Parameters

Parameter

Description

vibrationConfig [Array] - Mandatory

Specifies the list of all vibration patterns as an array. Each vibration pattern object accepts the duration, amplitude, and delay keys. delay [Integer] - Mandatory Specifies that the vibration will be paused for the specified delay time in milliseconds. This parameter must be a positive number. The default value of delay is 0 milliseconds. Any invalid or negative values specified for delay reverts to the default value, i.e., 0 milliseconds. duration [Integer] – Mandatory The number of milliseconds for which the device vibrates. This parameter must be a positive number. The default value of duration is 0 milliseconds. Any invalid or negative values specified for duration reverts to the default value, i.e., 0 milliseconds. amplitude [Integer] - Optional Controls the strength of the vibration. This must be a value between 0 and 255. For Windows and Android devices, when the vibration amplitude is 0, the vibration motor is turned off; whereas, when the vibration amplitude is 255, the vibration is performed at full strength. This parameter must be a positive number. The default value of amplitude is 0 milliseconds. Any invalid or negative values specified for amplitude reverts to the default value, i.e., 0 milliseconds. The amplitude parameter is supported on Android 8.0 and later.

repeat [Boolean] – Optional

true : The repeat vibration pattern is repeated until the voltmx.phone.cancelVibration API is called.false : Stops the repeat vibration pattern. This is the default value.

Example


//Device will vibrate for 100 milliseconds.

startVibration: function()
  {
    if(voltmx.phone.hasVibratorSupport()===true)
      {
        var vibrationConfig=[{
    "delay": 0,
    "duration": 100,
    "amplitude": 250
}];
        voltmx.phone.startVibration(vibrationConfig, true);
      }
    else{
        alert("The device does not support vibration");  
    }
  }

Return Values

None.

Behavior, Requirements, and Limitations

iOS
- The startVibration API generates only a single vibration effect.
- iOS does not support config parameters, such as amplitude and duration, for startVibration API.
- The startVibration API accepts arguments on iOS devices, but it ignores them. The API does not throw any error/exception.
- Windows
- The device must have vibration hardware.
- Device family (Windows OS build version) must be: Windows 10 Creators Update (introduced v10.0.15063.0) or later.
- API contract must be: Windows.Foundation.UniversalApiContract (introduced v4) or later.

Remarks

You can call this API with or without arguments for Android and Windows. If the arguments are not specified, the device vibrates for 100 milliseconds to align with the behavior for iOS.

Platform Availability

Android
iOS
Windows