The ButterflyMX system allows residents to receive audio/video calls from visitors through the ButterflyMX video intercom. The resident will be able to see the visitor, talk to the visitor, and open the door for the visitor.

This guide outlines the requirements for implementing ButterflyMX’s audio/video call from a ButterflyMX intercom. As a result, your mobile application(iOS and/or Android) will be capable of connecting to the ButterflyMX infrastructure to receive notifications about a call from a touchscreen, receive an audio/video call, and grant access to a property.

Getting started

This integration uses the ButterflyMX mobile SDK that is available for iOS and Android. In addition, to the ButterflyMX mobile SDK, you may need to use our API directly from your mobile application. Lastly, we have created and maintain iOS and Android sample applications that showcase the integration.

Receiving a notification about incoming audio/video calls depends on Firebase (Android) and Apple (iOS) push notification services. You are responsible for implementation of the backend infrastructure to send the call notifications. The ButterflyMX backend uses webhooks to notify your infrastructure about call events.

In order for your application to work, you will need to do the following:

1. Include our mobile SDK into your application and ensure compatibility.
2. Implement authorization.
3. Register call notification webhooks.
4. Implement call UI/UX using our mobile SDK
   a. Call notification
   b. Call processing
   c. Granting access
5. Optional
   a. Removing authorization (User logout)
   b. Call history
   c. Access history

1. Compatibility

Our mobile SDK is distributed using popular package managers. We use CocoaPods to distribute the iOS SDK and GitHub package manager for the Android SDK.

Please follow the SDK integration section of our mobile SDK reference (iOS or Android).

2. Authorization

ButterflyMX utilizes the OAuth 2 authorization code flow to facilitate authorization. This authorization allows the resident to authenticate to their ButterflyMX account to allow authorization from your application. This requires a button that initiates this authorization workflow within your application that is styled to the ButterflyMX brand guidelines.

Please follow the SDK authorization section of our mobile SDK reference (iOS or Android).

3. Register call notification webhooks

ButterflyMX infrastructure will notify your backend of a visitor call using webhooks. It is the partner’s responsibility to implement the relationship between the call and the notification of the appropriate resident. Webhook content includes user email address, call status, and additional information.

Webhooks will be sent for the following events:

• Incoming call
• Call status

Examples of web hook events:

Call object sent with the create event:

{
	'guid': '7e342936-f47c-4814-ac4a-c56a0ef749a6', 
	'user': {
		'id': 8,
		'first_name': 'Yurii',
		'last_name': 'Sekretar',
		'sip_username': '6',
		'email': '[email protected]'
		}, 
	'panel': {
		'id': 1387, 
		'name': 'Yurii Monarch',
		'sip_username': 'panel_1387'
	}, 
	'unit': {
		'id': 158,
		'label': '303'
	}, 
	'provider': 'twilio'
}

Call Status object sent with the status_update event:

{
'call': {
		'guid': '7e342936-f47c-4814-ac4a-c56a0ef749a6', 
		'user': {
			'id': 8,
			'first_name': 'Yurii', 
			'last_name': 'Sekretar', 
			'sip_username': '6', 
			'email': '[email protected]'
		}, 
		'panel': {
			'id': 1387,
			'name': 'Yurii Monarch', 
			'sip_username': 'panel_1387'
		}, 
		'unit': {
			'id': 158, 
			'label': '303'
		}, 
		'provider': 'twilio'
	}, 
	'status': 'canceled'
}

Please follow the SDK webhook integration section of our mobile SDK reference (iOS or Android). Also, you can use Tenant Webhook API or Building Webhook API directly from your app.

You can also use our sample backend webhook infrastructure that we use for our demo application (iOS and Android) to showcase the integration.

4. Implement call UI/UX using our mobile SDK

  a. Call notifications: A resident is notified about an incoming call from a visitor. The notification can include sound and visual representation of an incoming call. The notification can include a camera snapshot of the visitor. On iOS, you can use APNs (Apple Push Notification Service) notifications or PushKit (CallKit) to present notifications. On Android, you can use native or custom notifications.

Please follow the SDK notification processing section of our mobile SDK reference (iOS or Android).

  b. Call processing: Call experience where a resident can hear, see, and talk to a visitor. Residents are able to mute/unmute audio, enable/disable their camera, end the call, and request door release.

Please follow the SDK call processing section of our mobile SDK reference (iOS or Android).

  c. Granting access - By requesting door release the resident will notify intercom to grant access to a visitor. Each door release request will be associated with a call. The system tracks when a call occurred and any door request release associated with the call will be recorded as an access log.

Please follow the SDK door release section of our mobile SDK reference (iOS or Android).

You can reference our demo applications for an example of the UI/UX implementation.

5. Optional features

  a. Removing authorization (User logout) - It is a partner’s responsibility to implement the logout experience to make sure that resident does not receive notifications and does not have access to ButterflyMX SDK.

  b. Call history - Call history can be retrieved by resident and will include date, time, and an image of the visitor. To retrieve call history, a partner should use the Call History API. This functionality is not included in the Mobile SDK.

  c. Access history - Access history can be retrieved by the resident and will include date and time that the request for door release was made. For example, a visitor could attempt 3 calls, but only 1 request for door release will appear in the access history. To retrieve access history, a partner should use the Access History API.