Uh oh! We couldn’t find any match.
Please try other search keywords.
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.
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.
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
.
Property | Type | Kind | Notes |
---|---|---|---|
contactId | ContactId | integer | Identifier from device |
nameInfo | NameInfo | structure | |
addressInfos | AddressInfo | structure | max (Many) |
phoneInfos | PhoneInfo | structure | max (Many) |
emailInfos | EmailInfo | structure | max (Many) |
relationshipInfos | RelationshipInfo | structure | max (Many) |
photoInfo | PhotoInfo | structure | |
isFavorite | IsFavorite | boolean | |
workInfo | WorkInfo | structure | |
birthdayInfo | BirthdayInfo | structure |
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.
This contains properties for the components of the contact's name.
Property | Type | Kind | Notes |
---|---|---|---|
structuredName | StructuredName | text | (1) |
firstName | FirstName | text | |
middleName | MiddleName | text | |
lastName | LastName | text | |
prefix | NamePrefix | text | |
suffix | NameSuffix | text | |
nickName | NickName | text | |
initial | InitialOfName | name | (2) |
StructuredName
is the contact's full name, incorporating all the filled-in fields for Prefix
, FirstName
, MiddleName
, LastName
, and Suffix
.lazy-source
.Property | Type | Kind | Notes |
---|---|---|---|
type | AddressType | enum | (1) |
label | AddressLabel | name | (2) |
address | Address | structure | Required |
AddressType
are Home
, Work
, and Other
. This property is required.AddressLabel
is required unless AddressType
is Other
.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.
Property | Type | Kind | Notes |
---|---|---|---|
streetAddress | StreetAddress | text | |
streetAddress2 | StreetAddress2 | text | |
locality | Locality | structure | |
levelOne | LevelOneDivision | text | |
levelTwo | UnresolvedLevelTwoDivisionName | text | |
levelThree | LevelThreeDivisionName | text | |
levelFour | LevelFourDivisionName | text | |
country | ISOCountryCode2 | text | |
postalCode | PostalCode | text |
This contains information about a contact's phone number.
Property | Type | Kind | Notes |
---|---|---|---|
phoneType | PhoneType | enum | (1) |
phoneNumber | PhoneNumber | text | Required |
runestone | Runestone | boolean | (2) |
speechNumber | SpeechPhoneNumber | text | (3) |
PhoneType
are Mobile
, Home
, Work
, WorkFax
, HomeFax
, Pager
, Callback
, CustomType
, and Other
.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).SpeechNumber
is a formatted phone number for reading, and is automatically populated via lazy-source
.This contains information about a contact's email address.
Property | Type | Kind | Notes |
---|---|---|---|
emailType | EmailType | enum | (1) |
emailAddress | EmailAddress | name | Required |
EmailType
are Home
, Work
, Other
, and Custom
. This property is required.This specifies a relationship of a given type from the contact to another person.
Property | Type | Kind | Notes |
---|---|---|---|
relationshipType | RelationshipType | enum | (1) |
name | RelationshipName | text | Required |
RelationshipType
are Parent
, Mother
, Father
, Brother
, Sister
, Spouse
, Child
, Friend
, Relative
, DomesticPartner
, Partner
, Manager
, Assistant
, and ReferredBy
.The PhotoInfo
concept simply extends viv.image.Image
, and contains the same fields.
This contains information about the contact's employment.
Property | Type | Kind | Notes |
---|---|---|---|
title | JobTitle | name | |
department | Department | name | |
company | Company | name |
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.
Property | Type | Kind | Notes |
---|---|---|---|
month | time.Month | integer | |
day | time.Day | integer | |
year | time.Year | integer |
This is a primitive concept used for training. Continue reading Usage for details.
The viv.contact
capsule provides a FindContact
action with the following inputs:
Input | Type | Notes |
---|---|---|
searchTerm | SearchTerm | Optional |
contactType | ContactType | Required, default None |
phoneType | PhoneType |
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
).
The SaveContact
action takes a ContactInfo
concept as input and returns an ActionResult
, a structure with two properties:
Property | Type | Kind | Notes |
---|---|---|---|
result | Result | enum | "success" or "failure" |
description | ResultDescription | text |
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]