addressBooks API

The addressBooks API allows to access and manage the user’s address books.

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

addressBooks

Read and modify your address books and contacts.

Note

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

Functions

closeUI()

– [Added in TB 64]

Closes the address book user interface.

Required permissions

  • addressBooks

create(properties)

– [Added in TB 64]

Creates a new, empty address book.

Parameters

properties

properties

(object)

name

name

(string)

Return type (Promise)

_returns

string

– [Added in TB 89]

The id of the new address book.

Required permissions

  • addressBooks

delete(id)

– [Added in TB 64]

Removes an address book, and all associated contacts and mailing lists.

Parameters

id

id

(string)

Required permissions

  • addressBooks

get(id, [complete])

– [Added in TB 64]

Gets a single address book, optionally including all contacts and mailing lists.

Parameters

id

id

(string)

complete

[complete]

(boolean, optional)

If set to true, results will include contacts and mailing lists for this address book.

Return type (Promise)

_returns

– [Added in TB 89]

Required permissions

  • addressBooks

list([complete])

– [Added in TB 64]

Gets a list of the user’s address books, optionally including all contacts and mailing lists.

Parameters

complete

[complete]

(boolean, optional)

If set to true, results will include contacts and mailing lists for each address book.

Return type (Promise)

_returns

array of AddressBookNode

– [Added in TB 89]

Required permissions

  • addressBooks

openUI()

– [Added in TB 64]

Opens the address book user interface.

Return type (Promise)

_returns

Tab

– [Added in TB 114]

Required permissions

  • addressBooks

update(id, properties)

– [Added in TB 64]

Renames an address book.

Parameters

id

id

(string)

properties

properties

(object)

name

name

(string)

Required permissions

  • addressBooks

Events

onCreated

– [Added in TB 64]

Fired when an address book 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

Required permissions

  • addressBooks

onDeleted

– [Added in TB 64]

Fired when an addressBook is deleted.

Parameters for onDeleted.addListener(listener)

listener(id)

listener(id)

A function that will be called when this event occurs.

Parameters passed to the listener function

id

id

(string)

Required permissions

  • addressBooks

onUpdated

– [Added in TB 64]

Fired when an address book is renamed.

Parameters for onUpdated.addListener(listener)

listener(node)

listener(node)

A function that will be called when this event occurs.

Parameters passed to the listener function

node

Required permissions

  • addressBooks

Types

AddressBookNode

– [Added in TB 64]

A node representing 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.

name

name

(string)

type

type

Always set to addressBook.

contacts

[contacts]

(array of ContactNode, optional)

A list of contacts held by this node’s address book or mailing list.

mailingLists

[mailingLists]

(array of MailingListNode, optional)

A list of mailingLists in this node’s address book.

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 address book is accessed via remote look-up.

NodeType

– [Added in TB 64]

Indicates the type of a Node.

string

Supported values:

addressBook

addressBook

contact

contact

mailingList

mailingList