Find a direct message (DM) space

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.

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

main().catch(console.error);

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

main().catch(console.error);

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.