Bixby Developer Center

The bixby.contact capsule provides access to information in the user's contact list, such as given names, phone numbers, and addresses. It provides actions, models, and training to let your capsule find and process contact information.

Models

Types are always in the bixby.* namespace, and in the bixby.contact.* namespace unless another namespace is specified (e.g., viv.geo.*). All properties have a cardinality of min (Optional), max (One) unless otherwise specified.

ContactInfo

The ContactInfo structure concept contains information about a contact. Your capsule might interact with or extend this model, or use one of the more specific models its properties represent such as as AddressInfo.

NameInfo

This contains properties for the components of the contact's name.

The StructuredName is the contact's full name, incorporating the filled-in fields for FirstName and LastName.

AddressInfo

This contains information about a contact's address. Most of the information is in an UnresolvedAddress structure (see below).

UnresolvedAddress

This model extends the viv.geo.UnresolvedAddress concept. All types listed in UnresolvedAddress are defined in viv.geo; consult that library's documentation for more details.

PhoneInfo

This contains information about a contact's phone number.

1. The possible symbols for PhoneType are Mobile, Home, Work, WorkFax, HomeFax, Pager, Callback, CustomType, and Other.
2. Set to true if this is the contact's default phone number.

EmailInfo

This contains information about a contact's email address.

1. The possible symbols for EmailType are Home, Work, Other, and Custom. This property is required.
2. Set to true if this is the contact's default email address.

SearchTerm

This is a primitive concept used for training. Continue reading Usage for details.

Usage

1. Import this capsule in your capsule.bxb file:

   capsule-imports {
    import (bixby.contact) { 
      as (contact) 
      version (1.0.0)
    }
    ...
   }

   Use the current version of bixby.contact.

2. In your capsule.bxb file, declare the contacts library-permission necessary to access contact information.

   capsule {
    permissions {
      // access to all contacts on the device
      library-permission (contact:contacts)
      ...
    }
   }

3. Add localized justifications for the permission in your capsule-info.bxb file(s). This is a text string shown to the user when Bixby first requests access to the profile information. See requested-permissions for more details.

   capsule-info {
    requested-permissions {
      permission (contact:contacts) {
        justification (MyGreatCapsule needs access to your contact information.)
      }
    }
    ...
   }

FindContact

The bixby.contact capsule provides a FindContact action with a single input:

FindContact outputs a ContactInfo concept.

In most circumstances, you will use FindContact with a SearchTerm taken from a user utterance. Search terms can be names, phone numbers, and other keywords related to contacts. Contacts on a user's device have their names automatically added to their personal ASR (automatic speech recognition) vocabulary, which help Bixby understand references to them. Bixby will prompt the user for any necessary disambiguation.

The aligned NL for the utterance "call Jenny" might be:

[g:viv.phoneApp.CallingInfo#call] Call (Jenny)[v:bixby.contact.SearchTerm]

Like most actions, FindContact will usually be intelligently incorporated into the execution graph by Bixby—your capsule just needs to provide its own actions that take ContactInfo inputs.

Note that FindContact will return no results if it cannot find a good match to the SearchTerm in the contact database. If your capsule needs to take different action in those cases, you will need to handle that. For example, the text messaging app implements a FindRecipient action to wrap a handler around FindContact:

...
action (FindRecipient) {
  type (Calculation)
  collect {
    input (searchTerm) {
      type (contact.SearchTerm)
      min (Optional) max (One)
    }

    computed-input (contactInfos) {
      type (contact.ContactInfo)
      min (Optional) max (Many)

      compute {
        intent {
          goal: contact.FindContact
          value: $expr(searchTerm)
        }
      }
    }
  }
  ...
}

Then, your JavaScript implementation can handle the no results case as an exception (it will receive a ContactInfo input with a value of undefined).

Autosuggest

You can search named points (and contacts) using viv.location.Autosuggest, which takes a SearchTerm as its input. Read the viv.location documentation for more information.

Migration Notes

The FindContact action takes a searchTerm input and has the same output as the same action in viv.contact; in many cases, you won't need to do anything to migrate your capsule beyond importing bixby.contact instead of viv.contact. It does not support the contactType or phoneType fields of the earlier action.

The returned structures in bixby.contact do not have all of the fields present in viv.contact. The removed fields were rarely used or had inconsistent support across devices, but you should verify your capsule is not using any of these removed fields.

The bixby.contact capsule cannot create contacts, and does not have a SaveContact action or a DraftContactInfo model.