Bixby Developer Center

Guides
References

Contact (bixby.contact)

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.

Note

The viv.contact library capsule has been deprecated, and should be replaced by bixby.contact in your capsules. Read Migration Notes for help with migration.

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.

PropertyTypeKindNotes
nameInfoNameInfostructure
addressInfosAddressInfostructuremax (Many)
phoneInfosPhoneInfostructuremax (Many)
emailInfosEmailInfostructuremax (Many)

NameInfo

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

PropertyTypeKindNotes
structuredNameStructuredNametext
firstNameFirstNametext
lastNameLastNametext
displayNameDisplayNametext 

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).

PropertyTypeKindNotes
typeAddressTypeenumRequired
labelAddressLabeltext
unresolvedAddressUnresolvedAddressRequired 

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.

PropertyTypeKindNotes
streetAddressStreetAddresstext
streetAddress2StreetAddress2text 
localityLocalitystructure
countryCountryDivisiontext
levelOneLevelOneDivisiontext
levelTwoLevelTwoDivisionNametext
levelThreeLevelThreeDivisionNametext
levelFourLevelFourDivisionNametext
postalCodePostalCodetext

PhoneInfo

This contains information about a contact's phone number.

PropertyTypeKindNotes
phoneTypePhoneTypeenum(1)
labelPhoneLabeltext
numberPhoneNumbertextRequired
isDefaultIsDefaultboolean(2)
  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.

PropertyTypeKindNotes
typeEmailTypeenum(1)
addressEmailAddresstextRequired
labelEmailLabeltext
isDefaultIsDefaultboolean(2)
  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:

InputTypeNotes
searchTermSearchTermOptional

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.