Skip to content

Contacts

Jump to bottom
Rajesh Kumar edited this page Mar 4, 2024 · 6 revisions

Webex Calling Web SDK Contacts

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. 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.

Instantiate the ContactClient

To instantiate a ContactClient object:

const contacts = calling.contactClient;

Fetch Contacts Method

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

const contactListResponse = await contacts.getContacts();
Parameters --
Returns Promise<ContactResponse>

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:

Only `contacts`  and  `groups` attributes are present.
{
  "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"
}
If a user doesn't have any groups associated with their account, the SDK creates a default group name, "Other contacts".

Create 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.
Operation Contact Type Required Parameters
Creating Personal contacts CUSTOM displayName, contactType
Adding Contacts from Directory CLOUD contactId, contactType

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

Name Description Type Required
addressInfo Address information. Address Type { } No
avatarURL Avatar URL string No
avatarUrlDomain Domain of Avatar URL. string No
companyName Company name of the contact. string No
contactId The contactId of the person. The same as a userId in the case of a CLOUD contact. string Required only for CLOUD
contactType Type of contact, CUSTOM or CLOUD.
  1. CUSTOM - contacts created by user manually
  2. CLOUD - Directory Contacts of the user's organization.
ContactType
CUSTOM CLOUD
Yes
department Contact's department. string No
displayName Display name for the group. string Required only for CUSTOM.
emails Email addresses 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 Group IDs 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 ownerId 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 List of SIP addresses. [ ]
Name Values Required
type string No
value string Yes
No
title Job title of the person/contact. string No

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);
Parameters contactInfo<Contact>
Returns Promise<ContactResponse>

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"
}
If a `contact.group` is not defined, the default group **Other contacts** is used.

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);
Parameters contactId<string>
Returns Promise<ContactResponse>

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

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

Contacts 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:

Name Description Values
displayName Display name for the group. string
encryptionKeyUrl EncryptionKeyUrl for the content key. string
groupId Group ID. string
groupType Group Type of contact, NORMAL, or EXTERNAL. Default: NORMAL GroupType: NORMAL, EXTERNAL
members String array of contactId s that are part of the group. string [ ]
ownerId Owner ID 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 the contact either NORMAL or EXTERNAL. Default: NORMAL GroupType
NORMAL EXTERNAL
No
Returns Promise<ContactResponse>

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);
Parameters groupId<string>
Returns Promise<ContactResponse>

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

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

Caution

The Documentation is no longer be current.

  • Click here to view updated content for Calling SDK from our Developer Portal.

  • Click here to view updated content for Meetings SDK from our Developer Portal.

Webex Web SDK

Calling

Meeting

Clone this wiki locally