Contacts

• Introduction
• Instantiating the ContactClient
• Contact API
  • Fetching Contacts
  • Create Contact
  • Delete Contact
• Contacts Group API
  • Creating Contact Group
  • Deleting Contact Group

Introduction

The Calling SDK consists of various modules which are created at the time of its initialization. Among these integral modules, one noteworthy component is the ContactClient. To gain a comprehensive understanding of how to initiate a calling instance and instantiate these diverse modules, we strongly recommend consulting our Quickstart guide. This resource will walk you through the step-by-step process of creating a calling instance and provide insights into the instantiation of various modules. By the end of this document, you will have a solid grasp of how to leverage ContactClient to enhance your application's calling capabilities and create a seamless user experience.

Instantiating the ContactClient

 const contacts = calling.contactClient;

Contact API

Fetching Contacts

This API is used to retrieve the contacts and respective contact groups for a user.

  const contactListResponse = await contacts.getContacts();  

Parameters	--
Returns	Promise<ContactResponse>

Contact Response

This is the response type returned by the contact client for the various functionalities invoked. 

{
  statusCode: number;
  data: {
    contacts?: Contact[];
    groups?: ContactGroup[];
    contact?: Contact;
    group?: ContactGroup;
    error?: string;
  };
  message: string | null;
};

An example of the response for getContacts() api successful retrieval of contacts. You can also observe that only contacts  and  groups attributes are present in it. 

{
    "statusCode": 200,
    "data": {
        "contacts": [
            {
                "meta": {
                    "created": "2023-08-31T13:19:15.631Z",
                    "lastModified": "2023-08-31T13:19:15.631Z"
                },
                "contactId": "bd8c0601-e2d6-48ff-8559-72fec60131ad",
                "contactType": "CUSTOM",
                "avatarUrlDomain": "avatar-prod-us-east-2.webexcontent.com",
                "displayName": "John Doe",
                "phoneNumbers": [
                    {
                        "type": "work",
                        "value": "1232323"
                    }
                ],
                "encryptionKeyUrl": "kms://cisco.com/keys/ed180173-04ac-****-****-a9f0155f902f",
                "isMigration": false,
                "ownerId": "a126d98a-6570-487b-87a5-933dd3e97539",
                "groups": [
                    "f5d524df-3479-43c6-a7fd-5fab47b87cab"
                ]
            }
        ],
        "groups": [        
            {
                "meta": {
                    "created": "2021-05-05T09:39:35.067Z",
                    "lastModified": "2021-05-05T09:39:35.067Z"
                },
                "groupId": "1b2af605-de8a-469f-b5ba-9becdae8b67d",
                "groupType": "NORMAL",
                "ownerId": "a126d98a-6570-487b-87a5-933dd3e97539",
                "displayName": "Other contacts",
                "encryptionKeyUrl": "kms://cisco.com/keys/ed180173-04ac-415f-8665-a9f0155f902f",
                "isMigration": false
            }
        ]
    },
    "message": "SUCCESS"
}

 Note: If a user doesn't have any groups associated with the account, the SDK will create default group names "Other contacts".

Create Contact

This API helps to create the contact for the user. There are two ways to create contacts.

1. CUSTOM - These are the contacts created by user manually that are not present in user's organization. 
2. CLOUD - These are Directory Contacts of the user's organization.

Operation	contactType	Required Parameters
Creating Personal contacts	CUSTOM	displayName, contactType
Adding Contacts from Directory	CLOUD	contactId, contactType

Contact

This API accepts Contact object as a parameter. It consists of various attributes covered in the following table:

Name	Description	Type	Required
addressInfo	AddressInformation	Address Type { }	No
avatarURL	Avatar Url	string	No
avatarUrlDomain	Domain of Avatar Url	string	No
companyName	Company Name of Contact	string	No
contactId	contactId  of the person. It is same as userId  incase of a CLOUD contact.	string	Required only for CLOUD
contactType	Type of contact ( CUSTOM | CLOUD) CUSTOM - contacts created by user manually CLOUD -Directory Contacts of the user's organization.	ContactType CUSTOM CLOUD	Yes
department	Department Name of Contact	string	No
displayName	Display name for group.	string	Required only for CUSTOM
emails	Email of the contact	[ ] Name Values Required type string No value string Yes	No
encryptionKeyUrl	EncryptionKeyUrl for the content key to be used.	string	No
firstName	First Name	string	No
groups	groupId's of the groups that the contact is part of.	string [ ]	Yes
kmsResourceObjectUrl	kmsResourceObjectUrl for the content Object to be used	string	No
lastName	Last name	string	No
manager	Name of contact's manager	string	No
ownerId	userId  of the user	string	No
phoneNumbers	PhoneNumbers	[ ] Name Values Required type string No value string Yes	No
primaryContactMethod	Primary contact method as set by the contact/person	string	No
sipAddresses	SipAddresses	[ ] Name Values Required type string No value string Yes	No
title	Job title of the person/contact.	string	No

// for CLOUD contact
const contactinfo = {
    contactId: "<UUID>",
  	contactType: "CLOUD",
}


// for CUSTOM
const contactinfo = {
    displayName: "John Doe",
 	contactType: "CUSTOM",
  	phoneNumber: [{
          type: 'work',
          value:'+1987987521',
        },]
}  

const contactCreatedResponse = await contacts.createContact(contactInfo);  

Parameters	contactInfo<Contact>
Returns	Promise<ContactResponse>

An example of the response upon successful creation of contact.

{
  "statusCode": 201,
  "data": {
    "contact": {
      "avatarURL": "",
      "displayName": "testuser1",
      "phoneNumbers": [
        {
          "type": "work",
          "value": "+1987987521"
        }
      ],
      "contactType": "CUSTOM",
      "encryptionKeyUrl": "kms://cisco.com/keys/ed180173-04ac-415f-8665-a9f0155f902f",
      "groups": [
        "1b2af605-de8a-469f-b5ba-9becdae8b67d"
      ],
      "schemas": "urn:cisco:codev:identity:contact:core:1.0",
      "contactId": "48db494a-f23a-42b3-88e7-830ee31db7ae"
    }
  },
  "message": "SUCCESS"
}

Note : If a contact.group is not mentioned, the sdk will associate the contact with a default group: Other contacts 

Delete Contact

This API  helps in deleting a contact for the user.

   const contactId = "bd8c0601-e2d6-48ff-8559-72fec60131ad";
 
   const contactDeletedResponse = await contacts.deleteContact(contactId);  

Parameters	contactId<string>
Returns	Promise<ContactResponse>

An example of the response upon successful deletion of contact.

{
    statusCode: 204,
    data: {},
    message: SUCCESS,
};

Contacts Group API

Creating Contact Group

This API helps to create a contact group. A contact needs to be part of some group. Developer only needs to specify the groupName for basic usage. 

Contact Group

Once the contact group is created using createContactGroup API, contact group object would contain following attributes:

Name	Description	Values
displayName	Display name for group	string
encryptionKeyUrl	EncryptionKeyUrl for the content key to be used	string
groupId	groupId	string
groupType	Group Type of contact ( NORMAL | EXTERNAL ). Default is NORMAL.	GroupType NORMAL EXTERNAL
members	contactId s of contacts that are part of the group.	string [ ]
ownerId	userId  of the user	string

  const contactGroupCreatedResponse = await contacts.createContactGroup(displayName);  

Parameters	options Name Description Values Required  displayName  Display name for group   string Yes encryptionKeyUrl EncryptionKeyUrl for the content key to be used. string No groupType  Group Type of contact ( NORMAL | EXTERNAL ). Default is NORMAL. GroupType NORMAL EXTERNAL No
Returns	Promise<ContactResponse>

An example of the response upon successful creation of contact group.

{
    "statusCode": 201,
    "data": {
        "group": {
            "meta": {
                "created": "2023-09-05T08:27:32.651Z",
                "lastModified": "2023-09-05T08:27:32.651Z"
            },
            "groupId": "abf9ffd2-dab8-41c0-a28d-2c00426c5717",
            "groupType": "NORMAL",
            "ownerId": "a126d98a-6570-487b-87a5-933dd3e97539",
            "displayName": "testGRP",
            "encryptionKeyUrl": "kms://cisco.com/keys/ed180173-04ac-415f-8665-a9f0155f902f",
            "isMigration": false
        }
    },
    "message": "SUCCESS"
}

Deleting Contact Group

This API helps in deleting a contact Group for the given groupId.

const groupId ="5b92c76b-42e2-4fa6-b14b-90b8be6913b6";
  
const contactGroupDeletedResponse = await contacts.deleteContactGroup(groupId);  

Parameters	groupId<string>
Returns	Promise<ContactResponse>

An example of the response upon successful deletion of contact group.

{
    statusCode: 204,
    data: {},
    message: SUCCESS,
};