# Class: Contacts

## Constructor

#### new Contacts(contactsService)

  Provides contacts functionality to the client application. For contacts module namespace, see AvayaClientServices.Services.Contacts.

  Contacts class provides a set of APIs that enable application developers to manage user's contacts and search for other users/contacts.
  The capabilities and the set of allowed operations depend on the state of the contact-related servers and services.

  The client application is notified about contact services status updates through callback functions that the application has registered on the Contacts object.
  These updates may be the result of local operations on the contacts object as well as remote changes initiated either by the service/server or other users.

  In order to retrieve a list of contacts, call the Contacts.getContacts() function.
  It should be done after onContactsServiceAvailableCallback is called.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `contactsService` | AvayaClientServices.Services.Contacts.ContactsService |

## Methods

#### addContact(newContact) → {AvayaClientServices.Base.Promise.<(undefined|AvayaClientServices.Services.Contacts.ContactsError)>}

  Adds a new contact.

  An editable contact object can be created using one of the following functions:

  - by calling Contacts.createEditableContact() and then filling in the fields appropriately.
  - by calling Contacts.createEditableContactFromContact() to populate the editable contact from a directory search result.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `newContact` | AvayaClientServices.Services.Contacts.EditableContact | The contact to be added to the contact list.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contacts#getAddContactCapability}
    - {AvayaClientServices.Services.Contacts.Contacts#updateContact}
    - {AvayaClientServices.Services.Contacts.Contacts#deleteContact}

  ##### Returns:

  { AvayaClientServices.Base.Promise.<(undefined|AvayaClientServices.Services.Contacts.ContactsError)> }

#### changeSearchContactsRequest(dataRetrieval, newSearchString)

  Changes the search contacts request with given new query string. All other parameters are immutable.

  If the search associated with provided DataRetrieval instance was completed more than 2 minutes ago, this function would generate ContactsError with SEARCH_REQUEST_NOT_FOUND reason.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `dataRetrieval` | AvayaClientServices.Base.DataRetrieval | Data retrieval object returned by initial Contacts.searchContacts() call.
  `newSearchString` | string | A new search string.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contacts#getNetworkSearchContactCapability}

  ##### Throws:

  AvayaClientServices.Services.Contacts.ContactsError

#### createEditableContact() → {AvayaClientServices.Services.Contacts.EditableContact}

  Creates new EditableContact object with default values.
  This function must be used to create a new EditableContact object before calling the Contacts.addContact() function.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contacts#createEditableContactFromContact}
    - {AvayaClientServices.Services.Contacts.Contacts#addContact}

  ##### Returns:

  { AvayaClientServices.Services.Contacts.EditableContact }

  Editable contact that has all editable properties set to default values.

#### createEditableContactFromContact(contact) → {AvayaClientServices.Services.Contacts.EditableContact}

  Creates a new editable contact object from a given existing contact.

  This function can be used to create a new contact using the Contacts.searchContacts() function results.
  After that, a new EditableContact can be used in Contacts.addContact() operation.
  There is also a possibility to add the contact from local to enterprise source using the same scenario.

  This function must be used to update an existing contact as well. Once a new EditableContact is created, call the Contacts.updateContact() function to send a request.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `contact` | AvayaClientServices.Services.Contacts.Contact | The contact whose current values will be used to populate the new EditableContact.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contacts#addContact}
    - {AvayaClientServices.Services.Contacts.Contacts#updateContact}

  ##### Returns:

  { AvayaClientServices.Services.Contacts.EditableContact }

  Editable contact that has all editable properties set based on the specified input contact. Note that the fields not supported by enterprise source will not be used.

#### deleteContact(contact) → {AvayaClientServices.Base.Promise.<(undefined|AvayaClientServices.Services.Contacts.ContactsError)>}

  Deletes an existing contact.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `contact` | AvayaClientServices.Services.Contacts.Contact | The contact to be deleted from the contact list.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contact#getDeleteContactCapability}

  ##### Returns:

  { AvayaClientServices.Base.Promise.<(undefined|AvayaClientServices.Services.Contacts.ContactsError)> }

#### findLocalMatchingContacts(searchString, searchField)

  Searches for contacts matching the search request in local cache only. Unlike Contacts.searchContacts(), this function returns MatchedContactsWithMatchLevel instance with detailed information on how strong each contact matches the search request.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `searchString` | string | String to search for.
  `searchField` | AvayaClientServices.Services.Contacts.SearchFieldType | Field the search should be done against (name, phone number, etc.).

#### getContacts() → {AvayaClientServices.Base.DataRetrieval.<AvayaClientServices.Services.Contacts.Contact>}

  Retrieves the list of user's contacts. If this function has been called earlier, it returns the instance of DataRetrieval that was returned from the previous call.
  Contacts will be in underlying DataSet and DataRetrieval#onDataRetrievalDone callback will not be fired again.

  ##### Returns:

  { AvayaClientServices.Base.DataRetrieval.<AvayaClientServices.Services.Contacts.Contact> }

#### resolveContacts(resolveContactsRequest) → {AvayaClientServices.Base.DataRetrieval.<AvayaClientServices.Services.Contacts.ResolveContactResult>}

  Searches for contacts based on list of search strings provided in ResolveContactsRequest.
  This function should be used when the application needs to search for details of multiple users at once, for example, to display the names in user's call history or conference participant list.

  Please note that contacts returned by this function usually have only the basic set of data filled (such as first name, last name, phone numbers, email addresses).

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `resolveContactsRequest` | AvayaClientServices.Services.Contacts.ResolveContactsRequest | Object describing the search parameters.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contacts#getNetworkResolveContactsCapability}

  ##### Throws:

  AvayaClientServices.Services.Contacts.ContactsError

  ##### Returns:

  { AvayaClientServices.Base.DataRetrieval.<AvayaClientServices.Services.Contacts.ResolveContactResult> }

#### searchContacts(searchRequest) → {AvayaClientServices.Base.DataRetrieval.<AvayaClientServices.Services.Contacts.Contact>}

  Searches for the contacts with given request parameters.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `searchRequest` | AvayaClientServices.Services.Contacts.ContactSearchRequest | Object describing the search parameters.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contacts#getNetworkSearchContactCapability}

  ##### Throws:

  AvayaClientServices.Services.Contacts.ContactsError

  ##### Returns:

  { AvayaClientServices.Base.DataRetrieval.<AvayaClientServices.Services.Contacts.Contact> }

#### updateContact(updatedContact) → {AvayaClientServices.Base.Promise.<(undefined|AvayaClientServices.Services.Contacts.ContactsError)>}

  Updates an existing contact.

  An editable contact object can be created by calling Contacts.createEditableContactFromContact() to populate the editable contact from one of the contacts included in the contact list.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `updatedContact` | AvayaClientServices.Services.Contacts.EditableContact | The contact to be updated in the contact list.

  ##### See:

    - {AvayaClientServices.Services.Contacts.Contact#getUpdateContactCapability}
    - {AvayaClientServices.Services.Contacts.Contacts#deleteContact}

  ##### Returns:

  { AvayaClientServices.Base.Promise.<(undefined|AvayaClientServices.Services.Contacts.ContactsError)> }

### Callbacks

#### addOnContactServicesCapabilitiesChangedCallback(callback)

  Adds a new onContactServicesCapabilitiesChangedCallback.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | AvayaClientServices.Services.Contacts.Contacts#onContactServicesCapabilitiesChangedCallback |

#### addOnContactsServiceAvailableCallback(callback)

  Adds new onContactsServiceAvailableCallback.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | AvayaClientServices.Services.Contacts.Contacts#onContactsServiceAvailableCallback |

#### addOnContactsServiceUnavailableCallback(callback)

  Adds new onContactsServiceUnavailableCallback.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | AvayaClientServices.Services.Contacts.Contacts#onContactsServiceUnavailableCallback |

#### removeOnContactServicesCapabilitiesChangedCallback(callback)

  Removes existing onContactServicesCapabilitiesChangedCallback.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | AvayaClientServices.Services.Contacts.Contacts#onContactServicesCapabilitiesChangedCallback |

#### removeOnContactsServiceAvailableCallback(callback)

  Removes existing onContactsServiceAvailableCallback.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | AvayaClientServices.Services.Contacts.Contacts#onContactsServiceAvailableCallback |

#### removeOnContactsServiceUnavailableCallback(callback)

  Removes existing onContactsServiceUnavailableCallback.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `callback` | AvayaClientServices.Services.Contacts.Contacts#onContactsServiceUnavailableCallback |

### Capabilities

#### getAddContactCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability indicating if the provided contact can be updated.

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing whether the contact service supports adding contacts.

#### getAgentSearchCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to search only contact center agents

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing ability to search only contact center agents.

#### getAgentSearchCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to search all contacts including their extensions

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing ability to search all contacts including their extensions.

#### getConferenceSearchCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to search users only in conference.

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing ability to do search only in conference.

#### getNetworkResolveContactsCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to resolve contact in the network.

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing whether the contact service supports contacts resolution.

#### getNetworkSearchContactCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to search contacts in the network.

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing whether the contact service supports searching contacts.

#### getNetworkSearchTerminalCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to search terminal in the network.

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing whether the contact service supports searching contacts.

#### getVDNSearchCapability() → {AvayaClientServices.Base.Capability}

  Returns the capability to search only VDNs

  ##### Returns:

  { AvayaClientServices.Base.Capability }

  Capability object describing ability to search VDNs.

## Type Definitions

#### onContactServicesCapabilitiesChangedCallback(contacts)

  Interface for the callback function to be invoked when add or search capabilities of contact service are changed.
  It is up to the UI to inquire what capability has been changed. For example, when ACS provider is out of service, the service notifies that capabilities have been changed, and the UI needs to call Contacts.getAddContactCapability() or Contacts.getNetworkSearchContactCapability() in order to update the UI.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `contacts` | AvayaClientServices.Services.Contacts.Contacts | An instance of contacts module.

#### onContactsServiceAvailableCallback(contacts)

  Interface for the callback function to be invoked when contact service is available.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `contacts` | AvayaClientServices.Services.Contacts.Contacts | An instance of contacts module.

#### onContactsServiceUnavailableCallback(contacts)

  Interface for the callback function to be invoked when contact service is unavailable.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `contacts` | AvayaClientServices.Services.Contacts.Contacts | An instance of contacts module.