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

To instantiate a ContactClient object:

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,
};