contacts API

The contacts API allows to access and manage the user’s contacts.

Permissions

The following permissions influence the behavior of the API. Depending on which permissions are requested, additional methods might be available, or certain data may be included in responses.

Hint

Request permissions only when needed. Unnecessary requests may result in rejection during ATN review.

addressBooks



Read and modify your address books and contacts.

Note

The permission addressBooks is required to use messenger.contacts.*.

Functions

create(parentId, [id], properties)

– [Added in TB 64]

Adds a new contact to the address book with the id parentId.

Parameters

parentId

parentId

(string)



id

[id]

(string, optional) Deprecated.



Assigns the contact an id. If an existing contact has this id, an exception is thrown.

properties

properties

(ContactProperties)

– [Added in TB 68]



The properties object for the new contact. If it includes a vCard member, all specified legacy properties are ignored and the new contact will be based on the provided vCard string. If a UID is specified in the vCard string, which is already used by another contact, an exception is thrown.

Note

Using individual properties is deprecated, use the vCard member instead.

Return type (Promise)

_returns

string

– [Added in TB 96]



The ID of the new contact.

Required permissions

addressBooks

delete(id)

– [Added in TB 64]

Removes a contact from the address book. The contact is also removed from any mailing lists it is a member of.

Parameters

id

id

(string)



Required permissions

addressBooks

get(id)

– [Added in TB 64]

Gets a single contact.

Parameters

id

id

(string)



Return type (Promise)

_returns

ContactNode

– [Added in TB 96]



Required permissions

addressBooks

getPhoto(id)

– [Added in TB 106]

Gets the photo associated with this contact. Returns null, if no photo is available.

Parameters

id

id

(string)



Return type (Promise)

_returns

File or null



Required permissions

addressBooks

list(parentId)

– [Added in TB 64]

Gets all the contacts in the address book with the id parentId.

Parameters

parentId

parentId

(string)



Return type (Promise)

_returns

array of ContactNode

– [Added in TB 96]



Required permissions

addressBooks

quickSearch([parentId], queryInfo)

– [Added in TB 68]

Gets all contacts matching queryInfo in the address book with the id parentId.

Parameters

parentId

[parentId]

(string, optional)



The id of the address book to search. If not specified, all address books are searched.

queryInfo

queryInfo

(string or QueryInfo)



Either a string with one or more space-separated terms to search for, or a complex QueryInfo search query.

Return type (Promise)

_returns

array of ContactNode

– [Added in TB 96]



Required permissions

addressBooks

setPhoto(id, file)

– [Added in TB 107]

Sets the photo associated with this contact.

Parameters

id

id

(string)



file

file

(File)



Required permissions

addressBooks

update(id, properties)

– [Added in TB 64]

Updates a contact.

Parameters

id

id

(string)



properties

properties

(ContactProperties)



An object with properties to update the specified contact. Individual properties are removed, if they are set to null. If the provided object includes a vCard member, all specified legacy properties are ignored and the details of the contact will be replaced by the provided vCard. Changes to the UID will be ignored.

Note

Using individual properties is deprecated, use the vCard member instead.

Required permissions

addressBooks

Events

onCreated

– [Added in TB 64]

Fired when a contact is created.

Parameters for onCreated.addListener(listener)

listener(node)

listener(node)



A function that will be called when this event occurs.

Parameters passed to the listener function

node

node

(ContactNode)



Required permissions

addressBooks

onDeleted

– [Added in TB 64]

Fired when a contact is removed from an address book.

Parameters for onDeleted.addListener(listener)

listener(parentId, id)

listener(parentId, id)



A function that will be called when this event occurs.

Parameters passed to the listener function

parentId

parentId

(string)



id

id

(string)



Required permissions

addressBooks

onUpdated

– [Added in TB 64]

Fired when a contact is changed.

Parameters for onUpdated.addListener(listener)

listener(node, changedProperties)

listener(node, changedProperties)



A function that will be called when this event occurs.

Parameters passed to the listener function

node

node

(ContactNode)



changedProperties

changedProperties

(PropertyChange)

– [Added in TB 83]



Required permissions

addressBooks

Types

ContactNode

– [Added in TB 64]

A node representing a contact in an address book.

object

id

id

(string)



The unique identifier for the node. IDs are unique within the current profile, and they remain valid even after the program is restarted.

properties

properties

(ContactProperties)



type

type

(NodeType)



Always set to contact.

parentId

[parentId]

(string, optional)



The id of the parent object.

readOnly

[readOnly]

(boolean, optional)



Indicates if the object is read-only.

remote

[remote]

(boolean, optional)

– [Added in TB 91]



Indicates if the object came from a remote address book.

ContactProperties

– [Added in TB 64]

A set of individual properties for a particular contact, and its vCard string. Further information can be found in Working with vCard contacts.

object

PropertyChange

– [Added in TB 83]

A dictionary of changed properties. Keys are the property name that changed, values are an object containing oldValue and newValue. Values can be either a string or null.

object