For an introduction, we recommend consulting our Quickstart guide which 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 article, you will have a solid grasp of how to leverage ContactClient to enhance your application's calling capabilities and create a seamless user experience.

anchorInstantiate the ContactClient

The ContactsClient is implemented as the ContactsClient class in the SDK and there are two ways of instantiating it.

To instantiate just the ContactsClient, use the createContactsClient method:

const contacts = createContactsClient(webex, logger);

If the ContactsClient is initialized through the calling instantiation:

const contacts = calling.contactClient;

anchorFetch Contacts Method

The getContacts() method retrieves the contacts and respective contact groups for a user.

const contactListResponse = await contacts.getContacts();

FetchContact Response

Here's the prototype for the response returned by the getContacts() method:

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

Here's an example response for the getContacts() method:

{
  "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"
}

anchorCreate Contact Method

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 a user manually that are not present in a user's organization.
2. CLOUD - These are Directory Contacts from the user's organization.

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

Define a contactInfo Object and Create a Contact

You can define a contactInfo object as either a CLOUD or a CUSTOM contact. Once you've created the contactInfo object, pass it to the createContact() method:

// For a CLOUD contact

const contactinfo = {
  contactId: '<UUID>',
  contactType: 'CLOUD'
};

// For a CUSTOM contact

const contactinfo = {
  displayName: 'John Doe',
  contactType: 'CUSTOM',
  phoneNumber: [
    {
      type: 'work',
      value: '+1987987521'
    }
  ]
};
const contactCreatedResponse = await contacts.createContact(contactInfo);

Here's an example of a response after a contact is successfully created (in this case, a CUSTOM contact):

{
  "statusCode": 201,
  "data": {
    "contact": {
      "avatarURL": "",
      "displayName": "testuser1",
      "phoneNumbers": [
        {
          "type": "work",
          "value": "+1985557521"
        }
      ],
      "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"
}

Delete a Contact Method

The deleteContact() method lets you delete a contact. It takes a contactId as an argument.

const contactId = 'bd8c0601-e2d6-48ff-8559-72fec60131ad';

const contactDeletedResponse = await contacts.deleteContact(contactId);

Here's an example of a response from a successful contact deletion:

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

anchorContacts Group API

The methods in this section let you perform operations on groups of contacts.

Create Contact Group Method

The createContactGroup() creates a new contact group. A contact must belong to a group. You only need to specify the groupName for basic usage.

ContactGroup Object

Once the contact group is created using the createContactGroup() method, the ContactGroup object contains the following attributes:

const contactGroupCreatedResponse = await contacts.createContactGroup(displayName);

Here's an example of a response upon the successful creation of a 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"
}

Delete Contact Group

The deleteContactGroup() method lets you delete an existing contact group given a groupId.

const groupId = '5b92c76b-42e2-4fa6-b14b-90b8be6913b6';

const contactGroupDeletedResponse = await contacts.deleteContactGroup(groupId);

Here's an example of a response upon the successful deletion of a contact group.

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