Phone API

The Phone API provides your applications with access to the device's phone functionality, if the device supports it. Use the Phone API to access default applications in the underlying platform of the mobile device.

The Phone API provides you with the following Namespaces and the respective API elements therein:

kony.contact Namespace

Function	Description
`kony.contact.add`	Adds a contact to the address book of the mobile device.
`kony.contact.details`	Displays the details of a given contact and returns a new instance of the contact structure.
`kony.contact.find`	Parses through the address book of the mobile device and looks for contacts that match the input string.
`kony.contact.remove`	Deletes the contact (s) that was returned by the contact.find operation.

To add contacts to the phones address book, use the kony.contact.add function. From the list of contacts, you can search for and retrieve a contact using the kony.contact.find function, and view details of a specific contact using the kony.contact.details function. Use the kony.contact.remove function to delete a contact.

To view the functionality of the kony.contact Namespace in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Quantum App.

kony.phone Namespace

Function	Description
`kony.phone.addCalendarEvent`	Adds a new event to the device calendar.
`kony.phone.cancelVibration`	Stops the ongoing vibration pattern on a device.
`kony.phone.clearSMSListeners`	Clears the broadcast receiver and the existing listeners that are registered to read the one-time password (OTP) from an SMS message received from the server.
`kony.phone.dial`	Enables your app to call the specified telephone number.
`kony.phone.findCalendarEvents`	Finds an event in the device's calendar.
`kony.phone.generateAppHashKey`	Generates a hash key that must be included in the SMS message sent from the server to the user's device.
`kony.phone.getRemoveEventOptions`	Returns an array of constants that indicates possible actions for removing a particular event depending on the native support on the device.
`kony.phone.hasVibratorSupport`	Returns whether vibrator is supported on a device.
`kony.phone.openEmail`	Enables the application to launch the native email client with predefined email addresses, subject, body, and attachments.
`kony.phone.openMediaGallery`	Enables you to open the picture gallery of the mobile device and pick an existing picture.
`kony.phone.performHapticFeedback`	Provides various haptic feedback to users.
`kony.phone.removeCalendarEvent`	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.
`kony.phone.retrieveSMS`	Reads the one-time password from an SMS message received from the server. The one-time code will then be sent back to the server to complete the verification process.
`kony.phone.sendSMS`	Provides access to the Messaging service of the underlying platform
`kony.phone.startVibration`	Starts the vibration feature on a device, provided that device supports vibration.

Use the kony.phone.dial function to call a specific telephone number. To send messages to a specific telephone number, use the kony.phone.sendSMS function. Use the kony.phone.openEmail function to launch the native email client app, and open the picture gallery of the device using the kony.phone.openMediaGallery function.

To add new Calendar events, use the kony.phone.addCalendarEvent function, find calendar events using the kony.phone.findCalendarEvents function, and set actions to remove calendar events using the kony.phone.getRemoveEventOptions function. Use the kony.phone.removeCalendarEvent function to delete events from the Calendar.

On Android and iOS platforms, an app must have the end users’ runtime permission to use the openMediaGallery, addCalendarEvent, findCalendarEvent, and the removeCalendarEvent functions of the Phone API. If these functions are invoked without the end users’ permission, the platform automatically displays a system permission dialog box requesting permission from the end user.

To check whether a device supports vibration, use the kony.phone.hasVibratorSupport function. Provide haptic feedback using the kony.phone.performHapticFeedback function. To start and stop a devices’ vibrate feature, use the kony.phone.startVibration and the kony.phone.cancelVibration functions respectively.

To view the functionality of the kony.phone Namespace in action, download the sample application from the link below. Once the application is downloaded, build and preview the application using the Quantum App.

Error Code

2300 - Permission denied.

Example


try {
    kony.contact.find('John', false);
    catch (e) {
        if (e instanceof KonyError) {
            if (e.name == “PermissionError” & amp; & amp; e.errorCode == 2300) alert(“Failed to find contacts due to permission denial”);
        }
    }