Understand identifier types

Communication Services SDKs and REST APIs use the identifier type to identify who is communicating with whom. For example, identifiers specify who to call, or who has sent a chat message.

Depending on context, identifiers get wrapped with extra properties, like inside the ChatParticipant in the Chat SDK or inside the RemoteParticipant in the Calling SDK.

In this article, you'll learn about different types of identifiers and how they look across programming languages. You'll also get tips on how to use them.

The CommunicationIdentifier type

There are user identities that you create yourself and there are external identities. Microsoft Teams users and phone numbers are external identities that come to play in interop scenarios. Each of these different identity types has a corresponding identifier that represents it. An identifier is a structured type that offers type-safety and works well with your editor's code completion.

Communication user

The CommunicationUserIdentifier interface represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage

// at some point you will have created a new user identity in your trusted service
const newUser = await identityClient.createUser();

// and then send newUser.communicationUserId down to your client application
// where you can again create an identifier for the user
const sameUser = { communicationUserId: newUserId };

API reference

CommunicationUserIdentifier

Microsoft Teams user

The MicrosoftTeamsUserIdentifier interface represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an Microsoft Entra token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

// get the Teams user's ID from Graph APIs if only the email is known
const user = await graphClient.api("/users/bob@contoso.com").get();

// create an identifier
const teamsUser = { microsoftTeamsUserId: user.id };

// if you're not operating in the public cloud, you must also pass the right Cloud type.
const gcchTeamsUser = { microsoftTeamsUserId: userId, cloud: "gcch" };

API reference

MicrosoftTeamsUserIdentifier

Phone number

The PhoneNumberIdentifier interface represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

// create an identifier
const phoneNumber = { phoneNumber: "+112345556789" };

API reference

PhoneNumberIdentifier

Microsoft Teams Application

The MicrosoftTeamsAppIdentifier interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

// Get the Microsoft Teams App's ID from Graph APIs
const users = await graphClient.api("/users")
                    .filter(filterConditions)
                    .select('displayName,id')
                    .get();
//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
const bot = getBotFromUsers(users);
// Create an identifier
const teamsAppIdentifier = { teamsAppId: bot.id };

// If you're not operating in the public cloud, you must also pass the right Cloud type.
const gcchTeamsAppIdentifier = { teamsAppId: id, cloud: "gcch" };

API reference

MicrosoftTeamsAppIdentifier

Unknown

The UnknownIdentifier interface exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the UnknownIdentifier in the SDK.

Basic usage

// create an identifier
const unknownId = { id: "a raw id that originated in the service" };

API reference

UnknownIdentifier

How to handle the CommunicationIdentifier base interface

While you construct identifiers for a concrete type that you pass into the SDK, the SDK returns a CommunicationIdentifierKind, which is a discriminated union. It's easy to narrow to a concrete type and we suggest a switch-case statement with pattern matching:

switch (communicationIdentifier.kind)
{
    case "communicationUser":
        // TypeScript has narrowed communicationIdentifier to be a CommunicationUserKind
        console.log(`Communication user: ${communicationIdentifier.communicationUserId}`);
        break;
    case "microsoftTeamsUser":
        // narrowed to MicrosoftTeamsUserKind
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUserId}`);
        break;
    case "microsoftTeamsApp":
        // narrowed to MicrosoftTeamsAppIdentifier
        console.log(`Teams app: ${communicationIdentifier.teamsAppId}`);
        break;
    case "phoneNumber":
         // narrowed to PhoneNumberKind
        console.log(`Phone number: ${communicationIdentifier.phoneNumber}`);
        break;
    case "unknown":
         // narrowed to UnknownIdentifierKind
        console.log(`Unknown: ${communicationIdentifier.id}`);
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

The identifier interfaces have been designed so that you don't have to specify kind to reduce verbosity, and the discriminating union with the kind property is only used when returned from the SDK. However, if you find yourself needing to translate an identifier to its corresponding discriminating union type you can use this helper:

const identifierKind = getIdentifierKind(identifier); // now you can switch-case on the kind

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

Since azure-communication-common@2.1.0 the SDK helps with the conversion:

// get an identifier's raw Id
const rawId = getIdentifierRawId(communicationIdentifier);

// create an identifier from a given raw Id
const identifier = createIdentifierFromRawId(rawId);

An invalid raw ID will just convert to an UnknownIdentifier in the SDK and any validation only happens service-side.

Communication user

The CommunicationUserIdentifier represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = await identityClient.CreateUser();

// and then send newUser.Id down to your client application
// where you can again create an identifier for the user
var sameUser = new CommunicationUserIdentifier(newUserId);

API reference

CommunicationUserIdentifier

Microsoft Teams user

The MicrosoftTeamsUserIdentifier represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an Microsoft Entra token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

// get the Teams user's ID from Graph APIs if only the email is known
var user = await graphClient.Users["bob@contoso.com"]
    .Request()
    .GetAsync();

// create an identifier
var teamsUser = new MicrosoftTeamsUserIdentifier(user.Id);

// if you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch);

API reference

MicrosoftTeamsUserIdentifier

Phone number

The PhoneNumberIdentifier represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

// create an identifier
var phoneNumber = new PhoneNumberIdentifier("+112345556789");

API reference

PhoneNumberIdentifier

Microsoft Teams Application

The MicrosoftTeamsAppIdentifier interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

// Get the Microsoft Teams App's ID from Graph APIs
var users = await graphClient.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };
	requestConfiguration.QueryParameters.Filter = filterConditions;
});

// Here we assume that you have a function GetBotFromUsers that gets the bot from the returned response
var bot = GetBotFromUsers(users);

// Create an identifier
var teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.Id, CommunicationCloudEnvironment.Gcch);

API reference

MicrosoftTeamsAppIdentifier

Unknown

The UnknownIdentifier exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the UnknownIdentifier in the SDK.

Basic usage

// create an identifier
var unknown = new UnknownIdentifier("a raw id that originated in the service");

API reference

UnknownIdentifier

How to handle the CommunicationIdentifier base class

While you construct identifiers for a concrete type that you pass into the SDK, the SDK returns the CommunicationIdentifier protocol. It's easy to down-cast to a concrete type and we suggest a switch-case statement with pattern matching:

switch (communicationIdentifier)
{
    case CommunicationUserIdentifier communicationUser:
        Console.WriteLine($"Communication user: {communicationUser.Id}");
        break;
    case MicrosoftTeamsUserIdentifier teamsUser:
        Console.WriteLine($"Teams user: {teamsUser.UserId}");
        break;
    case MicrosoftTeamsAppIdentifier teamsApp:
        Console.WriteLine($"Teams app: {teamsApp.AppId}");
        break;
    case PhoneNumberIdentifier phoneNumber:
        Console.WriteLine($"Phone number: {phoneNumber.PhoneNumber}");
        break;
    case UnknownIdentifier unknown:
        Console.WriteLine($"Unknown: {unknown.Id}");
        break;
    default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

Since Azure.Communication.Common 1.2.0 the SDK helps with the conversion:

// get an identifier's raw Id
string rawId = communicationIdentifier.RawId;

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.FromRawId(rawId);

An invalid raw ID will just convert to an UnknownIdentifier in the SDK and any validation only happens service-side.

Communication user

The CommunicationUserIdentifier represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage

# at some point you will have created a new user identity in your trusted service
new_user = identity_client.create_user()

# and then send new_user.properties['id'] down to your client application
# where you can again create an identifier for the user
same_user = CommunicationUserIdentifier(new_user_id)

API reference

CommunicationUserIdentifier

Microsoft Teams user

The MicrosoftTeamsUserIdentifier represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an Microsoft Entra token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

# get the Teams user's ID from Graph APIs if only the email is known
user_id = graph_client.get("/users/bob@contoso.com").json().get("id");

# create an identifier
teams_user = MicrosoftTeamsUserIdentifier(user_id)

# if you're not operating in the public cloud, you must also pass the right Cloud type.
gcch_teams_user = MicrosoftTeamsUserIdentifier(user_id, cloud=CommunicationCloudEnvironment.GCCH)

API reference

MicrosoftTeamsUserIdentifier

Phone number

The PhoneNumberIdentifier represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

# create an identifier
phone_number = PhoneNumberIdentifier("+112345556789")

API reference

PhoneNumberIdentifier

Microsoft Teams Application

The MicrosoftTeamsAppIdentifier interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

# Get the Microsoft Teams App's ID from Graph APIs
users = graph_client.get("/users").json()

# Here we assume that you have a function get_bot_from_users that gets the bot from the returned response
bot = get_bot_from_users(users);

# Create an identifier
teams_app_identifier = MicrosoftTeamsAppIdentifier(app_id=bot.get("id"))

# If you're not operating in the public cloud, you must also pass the right Cloud type.
gcch_teams_app_identifier = MicrosoftTeamsAppIdentifier(
            app_id=bot.get("id"),
            cloud=CommunicationCloudEnvironment.GCCH
        )

API reference

MicrosoftTeamsAppIdentifier

Unknown

The UnknownIdentifier exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the UnknownIdentifier in the SDK.

Basic usage

# create an identifier
unknown = UnknownIdentifier("a raw id that originated in the service")

API reference

UnknownIdentifier

How to handle the CommunicationIdentifier base class

While you construct identifiers for a concrete type that you pass into the SDK, the SDK returns the CommunicationIdentifier protocol. Concrete identifier classes are just the CommunicationIdentifier protocol together with a typed dictionary called properties. So you can use pattern matching on the protocol's kind instance variable to translate to the concrete type:

match communication_identifier.kind:
    case CommunicationIdentifierKind.COMMUNICATION_USER:
        print(f"Communication user: {communication_identifier.properties['id']}")
    case CommunicationIdentifierKind.MICROSOFT_TEAMS_USER:
        print(f"Teams user: {communication_identifier.properties['user_id']}")
    case CommunicationIdentifierKind.MICROSOFT_TEAMS_APP:
        print(f"Teams app: {communication_identifier.properties['app_id']}")
    case CommunicationIdentifierKind.PHONE_NUMBER:
        print(f"Phone number: {communication_identifier.properties['value']}")
    case CommunicationIdentifierKind.UNKNOWN:
        print(f"Unknown: {communication_identifier.raw_id}")
    case _:
        # be careful here whether you want to throw because a new SDK version
        # can introduce new identifier types

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

The SDK helps with the conversion:

# get an identifier's raw Id
raw_id = communication_identifier.raw_id

# create an identifier from a given raw Id
identifier = identifier_from_raw_id(raw_id)

An invalid raw ID will just convert to an UnknownIdentifier in the SDK and any validation only happens service-side.

Communication user

The CommunicationUserIdentifier represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = identityClient.CreateUser();

// and then send newUser.getId() down to your client application
// where you can again create an identifier for the user
var sameUser = new CommunicationUserIdentifier(newUserId);

API reference

CommunicationUserIdentifier

Microsoft Teams user

The MicrosoftTeamsUserIdentifier represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an Microsoft Entra token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

// get the Teams user's ID from Graph APIs if only the email is known
var user = graphClient.users("bob@contoso.com")
    .buildRequest()
    .get();

// create an identifier
var teamsUser = new MicrosoftTeamsUserIdentifier(user.id);

// if you're not operating in the public cloud, you must also set the right Cloud type.
var gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

API reference

MicrosoftTeamsUserIdentifier

Phone number

The PhoneNumberIdentifier represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

// create an identifier
var phoneNumber = new PhoneNumberIdentifier("+112345556789");

API reference

PhoneNumberIdentifier

Microsoft Teams Application

The MicrosoftTeamsAppIdentifier interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

// Get the Microsoft Teams App's ID from Graph APIs
var user = graphClient.users()
	.buildRequest()
	.filter(filterConditions)
	.select("displayName,id")
	.get();

//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
var bot = getBotFromUsers(users);

// Create an identifier
var teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
var gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, CommunicationCloudEnvironment.GCCH);

API reference

MicrosoftTeamsAppIdentifier

Unknown

The UnknownIdentifier exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the UnknownIdentifier in the SDK.

Basic usage

// create an identifier
var unknown = new UnknownIdentifier("a raw id that originated in the service");

API reference

UnknownIdentifier

How to handle the CommunicationIdentifier base class

While you construct identifiers for a concrete type that you pass into the SDK, the SDK returns the abstract CommunicationIdentifier. You can down-cast back to a concrete type:

if (communicationIdentifier instanceof CommunicationUserIdentifier) {
    System.out.println("Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
    System.out.println("Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
}
else if (communicationIdentifier instanceof  MicrosoftTeamsAppIdentifier) {
    Log.i(tag, "Teams app: " + (( MicrosoftTeamsAppIdentifier)communicationIdentifier).getAppId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
    System.out.println("Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
    System.out.println("Unkown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
}
else {
    // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
}

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

Since azure-communication-common 1.2.0 the SDK helps with the conversion:

// get an identifier's raw Id
String rawId = communicationIdentifier.getRawId();

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.fromRawId(rawId);

An invalid raw ID will just convert to an UnknownIdentifier in the SDK and any validation only happens service-side.

Communication user

The CommunicationUserIdentifier represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage

// at some point you will have created a new user identity in your trusted service
// and send the new user id down to your client application
// where you can create an identifier for the user
let user = CommunicationUserIdentifier(newUserId)

API reference

CommunicationUserIdentifier

Microsoft Teams user

The MicrosoftTeamsUserIdentifier represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an ID token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

// get the Teams user's ID if only the email is known, assuming a helper method for the Graph API
let userId = await getUserIdFromGraph("bob@contoso.com")

// create an identifier
let teamsUser = MicrosoftTeamsUserIdentifier(userId: userId)

// if you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsUser = MicrosoftTeamsUserIdentifier(userId: userId, cloud: CommunicationCloudEnvironment.Gcch)

API reference

MicrosoftTeamsUserIdentifier

Phone number

The PhoneNumberIdentifier represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

// create an identifier
let phoneNumber = PhoneNumberIdentifier(phoneNumber: "+112345556789")

API reference

PhoneNumberIdentifier

Microsoft Teams Application

The MicrosoftTeamsAppIdentifier interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

// Get the Microsoft Teams App's ID from Graph APIs, assuming a helper method for the Graph API
let botId = await getBotIdFromGraph()

// Create an identifier
let teamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId)

// If you're not operating in the public cloud, you must also pass the right Cloud type.
let gcchTeamsAppIdentifier = MicrosoftTeamsAppIdentifier(appId: botId, cloudEnvironment: CommunicationCloudEnvironment.Gcch)

API reference

MicrosoftTeamsAppIdentifier

Unknown

The UnknownIdentifier exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the UnknownIdentifier in the SDK.

Basic usage

// create an identifier
let unknown = UnknownIdentifier("a raw id that originated in the service")

API reference

UnknownIdentifier

How to handle the CommunicationIdentifier base protocol

While you construct identifiers for a concrete type that you pass into the SDK, the SDK returns the CommunicationIdentifier protocol. It's easy to down-cast back to a concrete type and we suggest a switch-case statement with pattern matching:

switch (communicationIdentifier)
{
    case let communicationUser as CommunicationUserIdentifier:
        print(#"Communication user: \(communicationUser.id)"#)
    case let teamsUser as MicrosoftTeamsUserIdentifier:
        print(#"Teams user: \(teamsUser.UserId)"#)
    case let teamsApp as MicrosoftTeamsAppIdentifier:
        print(#"Teams app: \(teamsApp.appId)"#)
    case let phoneNumber as PhoneNumberIdentifier:
        print(#"Phone number: \(phoneNumber.PhoneNumber)"#)
    case let unknown as UnknownIdentifier:
        print(#"Unknown: \(unknown.Id)"#)
    @unknown default:
        // be careful here whether you want to throw because a new SDK version
        // can introduce new identifier types
        break;
}

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

Since Azure.Communication.Common 1.1.0 the SDK helps with the conversion:

Swift

// get an identifier's raw Id
let rawId = communicationIdentifier.rawId;

// create an identifier from a given raw Id
let identifier = createCommunicationIdentifier(fromRawId: rawId);

An invalid raw ID will just convert to an UnknownIdentifier in the SDK and any validation only happens service-side.

Communication user

The CommunicationUserIdentifier represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage

// at some point you will have created a new user identity in your trusted service
CommunicationUserIdentifier newUser = identityClient.CreateUser();

// and then send newUser.getId() down to your client application
// where you can again create an identifier for the user
CommunicationUserIdentifier sameUser = new CommunicationUserIdentifier(newUserId);

API reference

CommunicationUserIdentifier

Microsoft Teams user

The MicrosoftTeamsUserIdentifier represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an ID token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

// get the Teams user's ID from Graph APIs if only the email is known
User user = graphClient.users("bob@contoso.com")
    .buildRequest()
    .get();

// create an identifier
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(user.id);

// if you're not operating in the public cloud, you must also set the right Cloud type.
MicrosoftTeamsUserIdentifier gcchTeamsUser = new MicrosoftTeamsUserIdentifier(userId).setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

API reference

MicrosoftTeamsUserIdentifier

Phone number

The PhoneNumberIdentifier represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

// create an identifier
PhoneNumberIdentifier phoneNumber = new PhoneNumberIdentifier("+112345556789");

API reference

PhoneNumberIdentifier

Microsoft Teams Application

The MicrosoftTeamsAppIdentifier interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

// Get the Microsoft Teams App's ID from Graph APIs
UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter(filterConditions)
	.select("displayName,id")
	.get();

//Here we assume that you have a function getBotFromUsers that gets the bot from the returned response
User bot = getBotFromUsers(users);

// Create an identifier
MicrosoftTeamsAppIdentifier teamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id);

// If you're not operating in the public cloud, you must also pass the right Cloud type.
MicrosoftTeamsAppIdentifier gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdentifier(bot.id, CommunicationCloudEnvironment.GCCH);

API reference

MicrosoftTeamsAppIdentifier

Unknown

The UnknownIdentifier exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the UnknownIdentifier in the SDK.

Basic usage

// create an identifier
UnknownIdentifier unknown = new UnknownIdentifier("a raw id that originated in the service");

API reference

UnknownIdentifier

How to handle the CommunicationIdentifier base class

While you construct identifiers for a concrete type that you pass into the SDK, the SDK returns the abstract CommunicationIdentifier. You can down-cast back to a concrete type:

if (communicationIdentifier instanceof CommunicationUserIdentifier) {
    Log.i(tag, "Communication user: " + ((CommunicationUserIdentifier)communicationIdentifier).getId());
}
else if (communicationIdentifier instanceof MicrosoftTeamsUserIdentifier) {
    Log.i(tag, "Teams user: " + ((MicrosoftTeamsUserIdentifier)communicationIdentifier).getUserId());
}
else if (communicationIdentifier instanceof  MicrosoftTeamsAppIdentifier) {
    Log.i(tag, "Teams app: " + (( MicrosoftTeamsAppIdentifier)communicationIdentifier).getAppId());
}
else if (communicationIdentifier instanceof PhoneNumberIdentifier) {
    Log.i(tag, "Phone number: " + ((PhoneNumberIdentifier)communicationIdentifier).getPhoneNumber());
}
else if (communicationIdentifier instanceof UnknownIdentifier) {
    Log.i(tag, "Unkown user: " + ((UnknownIdentifier)communicationIdentifier).getId());
}
else {
    // be careful here whether you want to throw because a new SDK version
    // can introduce new identifier types
}

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

Since azure-communication-common 1.1.0 the SDK helps with the conversion:

// get an identifier's raw Id
String rawId = communicationIdentifier.getRawId();

// create an identifier from a given raw Id
CommunicationIdentifier identifier = CommunicationIdentifier.fromRawId(rawId);

An invalid raw ID will just convert to an UnknownIdentifier in the SDK and any validation only happens service-side.

In REST APIs, the identifier is a polymorphic type: you construct a JSON object and a property that maps to a concrete identifier subtype. For convenience and backwards-compatibility reasons, the kind and rawId properties are optional in requests but get populated in service responses.

Communication user

The CommunicationUserIdentifierModel represents a user identity that was created using the Identity SDK or REST API. It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.

Basic usage


// at some point you will have created a new user identity in your trusted service
// you can specify an identifier with the id of the new user in a request
{
    "communicationUser": {
        "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
    }
}

// the corresponding serialization in a response
{
    "kind": "communicationUser",
    "rawId": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715",
    "communicationUser": {
        "id": "8:acs:8540c0de-899f-5cce-acb5-3ec493af3800_c94ff260-162d-46d6-94fd-e79f4d213715"
    }
}

You can find an example for a request that includes an identifier in Chat's REST API for adding a participant, and an example for a response with an identifier under get chat message.

API reference

CommunicationUserIdentifierModel

Microsoft Teams user

The MicrosoftTeamsUserIdentifierModel represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK. Alternatively, you can find the ID as the oid claim in an Microsoft Entra token or Microsoft Entra access token after your user has signed in and acquired a token.

Basic usage

// request
{
    "microsoftTeamsUser": {
        "userId": "daba101a-91c5-44c9-bb9b-e2a9a790571a"
    }
}

// response
{
    "kind": "microsoftTeamsUser",
    "rawId": "8:orgid:daba101a-91c5-44c9-bb9b-e2a9a790571a",
    "microsoftTeamsUser": {
        "userId": "daba101a-91c5-44c9-bb9b-e2a9a790571a"
    }
}


// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
{
    "microsoftTeamsUser": {
        "userId": "daba101a-91c5-44c9-bb9b-e2a9a790571a",
        "cloud": "gcch"
    }
}

// response
{
    "kind": "microsoftTeamsUser",
    "rawId": "8:gcch:daba101a-91c5-44c9-bb9b-e2a9a790571a",
    "microsoftTeamsUser": {
        "userId": "daba101a-91c5-44c9-bb9b-e2a9a790571a",
        "isAnonymous": false,
        "cloud": "gcch"
    }
}

API reference

MicrosoftTeamsUserIdentifierModel

Phone number

The PhoneNumberIdentifierModel represents a phone number. The service assumes that phone numbers are formatted in E.164 format.

Basic usage

// request
{
    "phoneNumber": {
        "value": "+112345556789"
    }
}

// response
{
    "kind": "phoneNumber",
    "rawId": "4:+112345556789",
    "phoneNumber": {
        "value": "+112345556789"
    }
}

API reference

PhoneNumberIdentifierModel

Microsoft Teams Application

The MicrosoftTeamsAppIdentifierModel represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the Microsoft Graph REST API /users endpoint from the id property in the response. For more information on how to work with Microsoft Graph, try the Graph Explorer and look into the Graph SDK.

Basic usage

// request
{
    "microsoftTeamsApp": {
        "appId": "45ab2481-1c1c-4005-be24-0ffb879b1130"
    }
}

// response
{
    "kind": "microsoftTeamsApp",
    "rawId": "28:orgid:45ab2481-1c1c-4005-be24-0ffb879b1130",
    "microsoftTeamsApp": {
        "appId": "45ab2481-1c1c-4005-be24-0ffb879b1130"
    }
}


// if you're not operating in the public cloud, you must also pass the right Cloud type in a request
{
    "microsoftTeamsApp": {
        "appId": "45ab2481-1c1c-4005-be24-0ffb879b1130",
        "cloud": "gcch"
    }
}

// response
{
    "kind": "microsoftTeamsApp",
    "rawId": "28:gcch:45ab2481-1c1c-4005-be24-0ffb879b1130",
    "microsoftTeamsApp": {
        "appId": "45ab2481-1c1c-4005-be24-0ffb879b1130",
        "cloud": "gcch"
    }
}

API reference

MicrosoftTeamsAppIdentifierModel

Unknown

If a new identifier gets introduced in a service, it will get downgraded to the CommunicationIdentifierModel if you are on an old API version.

Basic usage

// request
{
    "rawId": "a raw id that originated in the service"
}

// response
{
    "kind": "unknown",
    "rawId": "a raw id that originated in the service"
}

API reference

CommunicationIdentifierModel

How to handle the CommunicationIdentifierModel in responses

Recent API versions populate a kind property that you can use to discriminate on:

switch (communicationIdentifier.kind)
{
    case "communicationUser":
        console.log(`Communication user: ${communicationIdentifier.communicationUser.id}`);
        break;
    case "microsoftTeamsUser":
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUser.userId}`);
        break;
    case "microsoftTeamsApp":
        console.log(`Teams user: ${communicationIdentifier.microsoftTeamsApp.appId}`);
        break;
    case "phoneNumber":
        console.log(`Phone number: ${communicationIdentifier.phoneNumber.value}`);
        break;
    case "unknown":
        console.log(`Unknown: ${communicationIdentifier.rawId}`);
        break;
    default:
        // this case should not be hit because adding a new identifier type requires a new API version
        // if it does get hit, please file an issue on https://github.com/Azure/azure-rest-api-specs/issues 
        break;
}

On older API versions, the kind property is missing and you have to check for the existence of the right subproperty:

if (communicationIdentifier.communicationUser) {
    console.log(`Communication user: ${communicationIdentifier.communicationUser.id}`);
} else if (communicationIdentifier.microsoftTeamsUser) {
    console.log(`Teams user: ${communicationIdentifier.microsoftTeamsUser.userId}`);
} else if (communicationIdentifier.microsoftTeamsApp) {
    console.log(`Teams app: ${communicationIdentifier.microsoftTeamsApp.appId}`);
} else if (communicationIdentifier.phoneNumber) {
    console.log(`Phone number: ${communicationIdentifier.phoneNumber.value}`);
} else {
    console.log(`Unknown: ${communicationIdentifier.rawId}`);
}

Raw ID representation

Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.

For that purpose, identifiers have another representation called RawId. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.

If you're using the Azure SDK, it will help you with the conversion. If you use the REST API directly, you need to construct the raw ID manually as described below.

Communication user

Identifier:

{
    "communicationUser": {
        "id": "[communicationUserId]"
    }
}

Raw ID:

[communicationUserId]

The raw ID is the same as communicationUser.id.

Microsoft Teams user

Identifier:

{
    "microsoftTeamsUser": {
        "userId": "[entraUserId]"
    }
}

Raw ID:

8:orgid:[entraUserId]

The raw ID is the Microsoft Entra user object ID prefixed with 8:orgid:.

Identifier:

{
    "microsoftTeamsUser": {
        "userId": "[entraUserId]",
        "cloud": "gcch"
    }
}

Raw ID:

8:gcch:[entraUserId]

The raw ID is the Microsoft Entra user object ID prefixed with 8:gcch: or 8:dod: depending on the cloud environment.

Identifier:

{
    "microsoftTeamsUser": {
        "userId": "[visitorUserId]",
        "isAnonymous": true
    }
}

Raw ID:

8:teamsvisitor:[visitorUserId]

The raw ID is the Teams visitor ID prefixed with 8:teamsvisitor:. The Teams visitor ID is a temporary ID that Teams generates to enable meeting access.

Phone number

Identifier:

{
    "phoneNumber": {
        "value": "+1123455567"
    }
}

Raw ID:

4:+1123455567

The raw ID is the E.164 formatted phone number prefixed with 4:.

Microsoft Teams app

Identifier:

{
    "microsoftTeamsApp": {
        "appId": "[entraUserId]"
    }
}

Raw ID:

28:orgid:[entraUserId]

The raw ID is the application's Entra user object ID prefixed with 28:orgid:.

Identifier:

{
    "microsoftTeamsUser": {
        "userId": "[entraUserId]",
        "cloud": "gcch"
    }
}

Raw ID:

28:gcch:[entraUserId]

The raw ID is the application's Entra user object ID prefixed with 28:gcch: or 28:dod: depending on the cloud environment.

Unknown

Identifier:

{
    "rawId": "[unknown identifier id]"
}

Raw ID:

[unknown identifier id]

If a raw ID is invalid, the service will fail the request.

Next steps