Find a direct message (DM) space

  • This guide focuses on utilizing the findDirectMessage() method within the Google Chat API to retrieve information about direct messages (DMs).

  • Authentication can be performed using either app authentication (for Chat app access to DMs) or user authentication (for authenticated user access to DMs).

  • To find a DM, you need to call the FindDirectMessage() method, providing the user's name, and utilize the appropriate authorization scope based on the authentication method.

  • The response from the Chat API will contain a Space object providing detailed information about the specified DM.

This guide explains how to use the findDirectMessage() method on the Space resource of the Google Chat API to get details about a direct message (DM) space.

The Space resource represents a place where people and Chat apps can send messages, share files, and collaborate. There are several types of spaces:

  • Direct messages (DMs) are conversations between two users or a user and a Chat app.
  • Group chats are conversations between three or more users and Chat apps.
  • Named spaces are persistent places where people send messages, share files, and collaborate.

When a Google Workspace administrator installs a Chat app for their entire Google Workspace organization, Google Chat creates a DM between the installed Chat app and each user in the organization.

Authenticating with app authentication lets a Chat app get DMs that the Chat app has access to in Google Chat (for example, DMs it's a member of). Authenticating with user authentication returns DMs that the authenticated user has access to.

Prerequisites

Node.js

Find a direct message

To find a direct message in Google Chat, pass the following in your request:

  • With app authentication, specify the chat.bot authorization scope. With user authentication, specify the chat.spaces.readonly or chat.spaces authorization scope.
  • Call the FindDirectMessage(), method passing the name of the other user in the DM to return. With user authentication, this method returns a DM between the calling user and the specified user. With app authentication, this method returns a DM between the calling app and the specified user.
  • To add a human user as a space member, specify users/{user}, where {user} is either the {person_id} for the person from the People API, or the ID of a user in the Directory API. For example, if the People API person resourceName is people/123456789, you can add the user to the space by including a membership with users/123456789 as the member.name.

Find a direct message with user authentication

Here's how to find a direct message with user authentication:

Node.js

chat/client-libraries/cloud/find-dm-space-user-cred.js
import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = [
  'https://www.googleapis.com/auth/chat.spaces.readonly',
];

// This sample shows how to find a Direct Message space with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace USER_NAME here
    name: 'users/USER_NAME',
  };

  // Make the request
  const response = await chatClient.findDirectMessage(request);

  // Handle the response
  console.log(response);
}

await main();

To run this sample, replace USER_NAME with the ID from the user's name field.

The Chat API returns an instance of Space that details the specified DM.

Find a direct message with app authentication

Here's how to find a direct message with app authentication:

Node.js

chat/client-libraries/cloud/find-dm-space-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to find a Direct Message space with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace USER_NAME here
    name: 'users/USER_NAME',
  };

  // Make the request
  const response = await chatClient.findDirectMessage(request);

  // Handle the response
  console.log(response);
}

await main();

To run this sample, replace USER_NAME with the ID from the user's name field.

The Chat API returns an instance of Space that details the specified DM.