Bixby Developer Center

The viv.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 viv.\* namespace, and in the viv.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 all 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.

DraftContactInfo

This model extends ContactInfo with a named-consumer block that links the SaveContact action to a contactInfo input through a create action. This is used to create a contact.

NameInfo

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

1. The StructuredName is the contact's full name, incorporating all the filled-in fields for Prefix, FirstName, MiddleName, LastName, and Suffix.
2. Automatically populated via lazy-source.

AddressInfo

1. The possible symbols for AddressType are Home, Work, and Other. This property is required.
2. AddressLabel is required unless AddressType is Other.

Address and UnresolvedAddress

Address both extends and has the role-of the UnresolvedAddress concept. This, in turn, extends the viv.geo.UnresolvedAddress structure concept; for more details, read the viv.geo documentation.

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. The Runestone field for a contact will be set to true by the phone application if that contact is called frequently; it can be used for disambiguation and learning purposes (e.g., if "call John" returns multiple contacts named "John," the one with Runestone set to true could be given higher priority).
3. The SpeechNumber is a formatted phone number for reading, and is automatically populated via lazy-source.

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.

RelationshipInfo

This specifies a relationship of a given type from the contact to another person.

1. The possible symbols for RelationshipType are Parent, Mother, Father, Brother, Sister, Spouse, Child, Friend, Relative, DomesticPartner, Partner, Manager, Assistant, and ReferredBy.

PhotoInfo

The PhotoInfo concept simply extends viv.image.Image, and contains the same fields.

WorkInfo

This contains information about the contact's employment.

BirthdayInfo

This extends the viv.time.Date concept, and has the same fields. Typically, you will use only the month, day, and year fields for contact birthdays.

SearchTerm

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

Usage

Searching for Contacts

The viv.contact capsule provides a FindContact action with the following inputs:

FindContact will prompt the user for any disambiguation necessary, and 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. The aligned NL for the utterance "call Jenny" might be:

[g:viv.phoneApp.CallingInfo#call] Call (Jenny)[v:viv.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

The viv.contact capsule provides an Autosuggest action that works with the auto-complete Views component, allowing Bixby to present real-time completion suggestions for contacts and nearby locations (named points).

Accessing the user's contacts requires the user-profile-access permission. If this permission is not granted, Autosuggest can still autocomplete named locations, as long as isSearchGeoLocations is true.

To use this in an auto-complete block, set Autosuggest to the goal of a new intent, passing a SearchTerm in as an input value.

input-view {
  match: DestinationPoint

  message ("Where would you like to go?")

  render {
    auto-complete {
      type (geo.NamedPoint)
      no-result-text { template ("No results") }
      placeholder { template ("Search for locations") }
      source {
        collect-with (query) {
          intent {
            goal: contact.Autosuggest
            value: contact.SearchTerm$expr (query)
            value: contact.IsFuzzyMatchAddressType(true)
          }
        }
        label { template ("Search Results") }
        where-each (place) { 
          display {
            primary-text { template ("[#{value(place.name)}]") }
            secondary-text { template ("[#{value(place.address)}]") }
          }
          on-select {
            intent {
              goal: DestinationPoint
              value: viv.core.FormElement(place)
            }
          }
        }
      }
    }
  }
}

By default, Autosuggest will use location data to help resolve suggestions. You can disable this by setting isSearchGeoLocations to false in the intent block:

intent {
  goal: contact.Autosuggest
  value: contact.SearchTerm$expr (query)
  value: contact.IsSearchGeoLocations (false)
}

If you disable isSearchGeoLocations, then Autosuggest will not be able to autocomplete locations.

Setting isFuzzyMatchAddressType to true will allow "fuzzy matching" for address types such as home and office. By default, this is not enabled.

Creating a Contact

The SaveContact action takes a ContactInfo concept as input and returns an ActionResult, a structure with two properties:

You can use this action with the DraftContactInfo model. Implement an action named CreateContact that collects all the fields for a contact and outputs your draft model:

action (CreateContact) {
  type (Calculation)
  collect {
    input (firstName) {
      type (viv.contact.FirstName)
      min (Required) max (One)
    }
    input (lastName) {
      type (viv.contact.LastName)
      min (Required) max (One)
    }
    input (phoneNumber) {
      type (viv.contact.PhoneNumber)
      min (Required) max (One)
    }
    // more inputs, as needed
  }

  output (DraftContactInfo)
}

Lastly, train Bixby with a goal of DraftContactInfo#create and a route of CreateContact:

[g:viv.contactApp.DraftContactInfo#create,r:viv.contactApp.CreateContact] Store phone number (485451515)[v:viv.contact.PhoneNumber] as (Ted)[v:viv.contact.StructuredName]