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.

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

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 :

 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 :

 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.

Related topics

• Create a space .
• Set up a space .
• Get details about a space .
• List spaces .
• Update a space .
• Delete a space .