Introduction

This FAQ contains answers to and resources for common questions partners have about ButterflyMX setup, testing, and usage. This document will also help you troubleshoot some common API errors.

If you continue to run into issues after reading this FAQ, please email [email protected] for further assistance.

This FAQ will help you:

Set up partner accounts
Set up ButterflyMX accounts
Set up ButterflyMX emulation software
Understand the difference between ButterflyMX account types and how they relate to API permissions
Configure environments and ButterflyMX panel software
Use the API and SDK
Troubleshoot common issues

Definitions

Glossary of ButterflyMX Terms and Abbreviations

Building Admin Account: One of the roles a ButterflyMX user can be associated with. Integrations that use building-level APIs will need to authorize using a Building Admin Account account as Resource Owner.

Tenant Account = Integrations that use tenant-level APIs will need to authorize using a Tenant Account as Resource Owner.

Unit Admin (not currently available)

Zone Admin (not currently available)

GUI = Graphical User Interface. In ButterflyMX parlance, it is often used to mean the touchscreen interface of the intercom

VCAM2 = version 2 of the virtual camera software

VCAM3 = version 3 of the virtual camera software

On-boarding FAQs

Using the ButterflyMX App and Property Management Dashboard (ButterflyMX OS)

You’ll find many answers to FAQs about configuring and using our desktop property management dashboard and our mobile app using the links below. We recommend that you start here first:

Intercom Emulation & Intercom Software Installation

How do I simulate intercom functionality so that I can test my API development?

We can install our intercom software on a Windows machine for you. Please contact [email protected] with your request.

We recommend you use a laptop with a built-in camera and the Windows 10 OS.

You'll need to install TeamViewer and provide us with your TeamViewer ID and password.

Is it possible to set up the panel software on a virtual machine?

We don't support installations of the panel software on virtual machines

ButterflyMX Account Types and API Access

Which ButterflyMX user account level should I use when implementing my integration?

This depends on your use cases and the endpoints your use cases require. For example, here are the permissions associated with the building-level and door releases APIs

Can a partner have more than one client ID and secret associated with their API access?

A partner is limited to one set of client IDs and secrets for each production environment. You will only be provided with one set for the Sandbox environment and another set for the Production environment.

Will the API access provided by the one client ID and secret that we receive be able to access all of the buildings we integrate with?

Your one client/secret pair will provide access to all of the resources to which you have access.

Can a partner have more than one admin account associated with their API access?

For the sandbox environment, your ButterflyMX partner contact can create as many Building Admin Accounts as needed. Each admin account can be used to retrieve access, refresh tokens, or work with any other API. For example, Building Admin Accounts in the sandbox environment can also create virtual keys or show a list of units.

For the production environment, partners will be provided with only one Building Admin Account per building if the integration requires that level of access.

Building Admin Accounts in both environments cannot create other Building Admin Accounts, but they can freely create tenant accounts. More details on managing users in our admin console can be found in the "Training Videos" section of this page: https://butterflymx.com/resources/property-managers/

How do I turn on an integration for a building?

Once an integration has been approved by ButterflyMX, we will provide you with a link to a form. You can then pass this form to building staff to request an integration activation. Once the individual property has approved the integration via this form, ButterflyMX will turn on the integration for that single building.

Oauth2 and Authentication

Is the OAuth2 implementation for the API the same for the mobile SDKs?

Yes.

I need to add a redirect URI. How do I do it?

Please contact your ButterflyMX technical support team in the shared Slack channel that has been set up or at [email protected] to have redirect URIs added for your application.

Does each tenant have to log in through the SDK flow for us to manage their calls? Or can we instead use admin credentials for everyone and pass the calls to a specific tenant?

Each tenant will have to log in individually. Calls and all other actions performed by tenants (like creating virtual keys or opening doors) should be handled using tenant accounts.

Virtual Keys and PINs

What are the six-digit PIN code requirements?

No repetitive PINs — more than half of the PIN needs to be a unique digit. For example,143213 (4 unique digits in a 6-digit PIN) is fine, but 144214 is not (only 3 unique digits in a 6-digit PIN)
No consecutive number sequences (123456, 98765, etc.)
The PIN needs to be unique at the building level

If the intercom loses its internet connection, will the PIN still work?

Yes. PINs are synced to the mobile app and intercom as soon as they are created. So, the intercom will still recognize a PIN even without an active internet connection.

Can I create one virtual key that allows a user access across multiple buildings that have different ButterflyMX intercoms?

If the property with multiple buildings is setup in our system as a single "Building," one virtual key will have access to all of the intercoms associated with that single "Building." But if each physical building within the property is a different "Building" in our system, different virtual keys for each building will need to be used.

How can I create permanent PINs for non-residents?

Our API allows you to create tenants, set PINS and specify start and end dates for when tenants will be active in the system.

With this functionality, you can:

Create a placeholder unit.
Assign the non-resident to that unit.
Create your unique PIN for that resident.

⚠️ **Remember:** Be sure to use a format for the unit that is distinct from the property's actual units so that it will not interfere with them. You can check the property's unit format in the Units section of the ButterflyMX OS.

Can I send ButterflyMX PINs or QR codes via Email or SMS?

ButterflyMX PINS are automatically sent via SMS and/or email if you include the recipient email address and the mobile phone number as part of your payload when you create a keychain.
Alternatively, if your use case involves sending the PINs via another channel, you should create a recipient keychain first, and then attach a recipient-less virtual key to that keychain using the virtual key endpoint, which will return a PIN code and QR code URL.

Door Releases

What is the difference between the various door_releases and open_door endpoints?

`POST/v3/me/open_door- opens a door for the current user - you need to pass a panelidin aPOST` parameter

`GET /v3/me/door_releases` - returns all door release events for the current user. Door release event can be created by the tenant via the Open Door API or within a call and/or visitor using virtual key

`GET /v3/door_releases` - mostly used by admin accounts with filtering options

What activity method should I post for door unlocks?

You can send front_door_view as a door_release_method

Test / Sandbox Environment FAQs

How do I access test enviroments from the production ButterflyMX mobile app?

Add /test to the end of your login email if you're testing in the staging environment

Add /sandbox to the end of your login email if you're testing in the sandbox environment

For example, for the sandbox environment :

Username: [email protected]**/sandbox**

Tenant & Unit Logic

Do you allow tenants to connect multiple devices with their profile? For example, can I use both my iPhone and iPad to receive push notifications?

Yes.

Can a tenant be associated with multiple units in the same property? For example, if a tenant is transferring units and has access to both apartments, or if a tenant is renting multiple units.

Yes. We allow users to have multiple tenancies. We define ‘tenant’ by considering both the user and the unit.

When a tenant is associated with multiple units, how do you handle elevator control for their associated unit floors?

We handle elevator control by associating the tenant with each unit separately. So, if a tenant resides in an additional unit, they will have an additional tenant entity in our system and will need separate elevator control access.

Webhooks

Can you push updates to us if: (1) a new ButterflyMX access point is added to a community (for example, my building just opened a new pool) or (2) a tenant's access is changed (i.e. John can no longer access the pool)?

We do not currently offer push updates for either of these things, but they might become available in the future. For now, you will we need to fetch the data from our API

Do you send a webhook to partners when the contact preference is set to Phone Call?

No. This only happens when the preference is set to Mobile App.

Calls

Video Calls vs Audio calls

If a contact is listed as a “phone call user”, does that mean a Session Initiation Protocol (SIP) call will not work?

Yes. In this case the call will be routed directly to the contact's cell phone.

Devices and video calls

Can multiple devices enter a video call simultaneously? Or can only one device be active at a time?

Currently, only one device can be in a video call at a time.

General FAQs

Is there a way to hide tenants via API?

Yes, you can use the following endpoint:
https://apidocs.butterflymx.com/core/v3/production/index.html#tenants-tenants-patch
Include display_only_on_search as a value in the attributes section

Is there any API we can use to specify a building `id` while fetching, and get the units for only that building?

Yes, you can use the filters here:

https://apidocs.butterflymx.com/core/v3/test/index.html#header-filtering

Can I create buildings in ButterflyMX OS?

No, Building Admin Accounts cannot create buildings, and we restrict partner accounts to no higher access level than Building Admin access.

Can I give verified prospects doing self guided tours one-time community access?

Yes, using the 'create-one-time keychain' in our virtual keys API

Can a Butterflymx unit be assigned to the company/community level? Or is it always assigned to a building?

A ButterflyMX unit is always assigned to a building.

What timezone should be used when we send data in API requests? The timezone of the building or another?

You should use the timezone of the building. Also, you should always use the iso8601 format when sending datetime data.

Troubleshooting

Teamviewer

I'm unable to connect and receiving the message "Version Out of Date: Update The Remote Teamviewer Software"?

Please contact [email protected] with your Teamviewer ID and Password

API errors

How do I resolve a 404 error or a `"Client authentication failed due to unknown client, no client authentication included, or unsupported authentication method"` message?

Please ensure that there are no URL typos in your request.
Please ensure that you are using the correct URL in your request:
- If you are in the sandbox environment, you should be sending authentication requests to accountssandbox.butterflymx.com
- If you are in the staging environment, you should be sending authentication requests to accountstest.butterflymx.com

How do I resolve an internal server error when I make an API request?

Please ensure that you are using https:// in your endpoint

I'm receiving `"An unexpected error occurred while processing your request"` when using the Integrations endpoints

Ensure that your "url" parameter is something other than localhost

How do I resolve a 500 error when making a POST request to the keychains endpoint?

Ensure that you are you are sending a unit_id in the request. The system requires a unit ID in order to associate the key with a unit/tenant.

Virtual key / PIN issues

I am receiving the error `Error in ButterflyMX QR code generation ---- ButterflyMX: generate_onetime_keychain - /data/attributes/base QR Keys feature is not enabled for the building where unit belongs` when there is an attempt to create a virtual key.

This usually means that virtual keys have not been manually enabled for the building. Please contact your ButterflyMX technical support team in the shared Slack channel that has been set up, or at [email protected] to have that functionality enabled.