|
5 分ほどお時間をいただけますか？
オンライン アンケートに回答して、Google Workspace のドキュメントの改善にご協力ください。
|
このガイドでは、Google Chat API の Message リソースで create() メソッドを使用して、次のいずれかを行う方法について説明します。
- テキスト、カード、インタラクティブ ウィジェットを含むメッセージを送信します。
- 特定の Chat ユーザーに非公開でメッセージを送信します。
- メッセージ スレッドを開始または返信します。
- 他の Chat API リクエストで指定できるように、メッセージに名前を付けます。
メッセージの最大サイズ（テキストやカードを含む）は 32,000 バイトです。このサイズを超えるメッセージを送信するには、Chat 用アプリで複数のメッセージを送信する必要があります。
Chat 用アプリは、Chat API を呼び出してメッセージを作成するだけでなく、ユーザーが Chat 用アプリをスペースに追加した後にウェルカム メッセージを投稿するなど、ユーザーの操作に返信するメッセージを作成して送信することもできます。Chat 用アプリは、インタラクションへの応答時に、インタラクティブ ダイアログやリンク プレビュー インターフェースなど、他のタイプのメッセージング機能を使用できます。ユーザーに返信する場合、Chat 用アプリは Chat API を呼び出すことなく、メッセージを同期的に返します。インタラクションに応答するメッセージの送信については、Google Chat アプリでインタラクションを受信して応答するをご覧ください。
Chat API で作成されたメッセージの Chat での表示と属性
アプリ認証とユーザー認証を使用して create() メソッドを呼び出すことができます。Chat では、使用する認証のタイプに応じてメッセージの送信者を異なる方法で特定します。
Chat 用アプリとして認証すると、Chat 用アプリがメッセージを送信します。
App が表示されます。ユーザーとして認証すると、Chat 用アプリはユーザーに代わってメッセージを送信します。また、Chat アプリの名前を表示することで、メッセージに Chat アプリが関連付けられます。
認証タイプによって、メッセージに含めることができるメッセージ機能とインターフェースも決まります。アプリ認証を使用すると、Chat 用アプリはリッチテキスト、カードベースのインターフェース、インタラクティブなウィジェットを含むメッセージを送信できます。Chat ユーザーはメッセージでテキストのみを送信できるため、ユーザー認証を使用してメッセージを作成する場合はテキストのみを含めることができます。Chat API で使用できるメッセージ機能の詳細については、Google Chat メッセージの概要をご覧ください。
このガイドでは、いずれかの認証タイプを使用して Chat API でメッセージを送信する方法について説明します。
前提条件
Node.js
- Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
- 環境を設定します。
- Google Cloud プロジェクトを作成します。
- OAuth 同意画面を構成する。
- Chat 用アプリの名前、アイコン、説明を使用して、Google Chat API を有効にして構成します。
- Node.js Cloud クライアント ライブラリをインストールします。
- Google Chat API リクエストで認証を行う方法に基づいて、アクセス認証情報を作成します。
- Chat ユーザーとして認証するには、OAuth クライアント ID 認証情報を作成し、認証情報を
credentials.jsonという名前の JSON ファイルとしてローカル ディレクトリに保存します。 - Chat 用アプリとして認証するには、サービス アカウントの認証情報を作成し、認証情報を
credentials.jsonという名前の JSON ファイルとして保存します。
- Chat ユーザーとして認証するには、OAuth クライアント ID 認証情報を作成し、認証情報を
- ユーザーとして認証するか、Chat 用アプリとして認証するかに基づいて、 認証スコープを選択します。
- 認証済みユーザーまたは通話元の Chat 用アプリがメンバーである Google Chat スペース。Chat 用アプリとして認証するには、Chat 用アプリをスペースに追加します。
Python
- Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
- 環境を設定します。
- Google Cloud プロジェクトを作成します。
- OAuth 同意画面を構成する。
- Chat 用アプリの名前、アイコン、説明を使用して、Google Chat API を有効にして構成します。
- Python Cloud クライアント ライブラリをインストールします。
- Google Chat API リクエストで認証を行う方法に基づいて、アクセス認証情報を作成します。
- Chat ユーザーとして認証するには、OAuth クライアント ID 認証情報を作成し、認証情報を
credentials.jsonという名前の JSON ファイルとしてローカル ディレクトリに保存します。 - Chat 用アプリとして認証するには、サービス アカウントの認証情報を作成し、認証情報を
credentials.jsonという名前の JSON ファイルとして保存します。
- Chat ユーザーとして認証するには、OAuth クライアント ID 認証情報を作成し、認証情報を
- ユーザーとして認証するか、Chat 用アプリとして認証するかに基づいて、 認証スコープを選択します。
- 認証済みユーザーまたは通話元の Chat 用アプリがメンバーである Google Chat スペース。Chat 用アプリとして認証するには、Chat 用アプリをスペースに追加します。
Java
- Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
- 環境を設定します。
- Google Cloud プロジェクトを作成します。
- OAuth 同意画面を構成する。
- Chat 用アプリの名前、アイコン、説明を使用して、Google Chat API を有効にして構成します。
- Java Cloud クライアント ライブラリをインストールします。
- Google Chat API リクエストで認証を行う方法に基づいて、アクセス認証情報を作成します。
- Chat ユーザーとして認証するには、OAuth クライアント ID 認証情報を作成し、認証情報を
credentials.jsonという名前の JSON ファイルとしてローカル ディレクトリに保存します。 - Chat 用アプリとして認証するには、サービス アカウントの認証情報を作成し、認証情報を
credentials.jsonという名前の JSON ファイルとして保存します。
- Chat ユーザーとして認証するには、OAuth クライアント ID 認証情報を作成し、認証情報を
- ユーザーとして認証するか、Chat 用アプリとして認証するかに基づいて、 認証スコープを選択します。
- 認証済みユーザーまたは通話元の Chat 用アプリがメンバーである Google Chat スペース。Chat 用アプリとして認証するには、Chat 用アプリをスペースに追加します。
Apps Script
- Google Chat へのアクセス権を持つ Business または Enterprise の Google Workspace アカウント。
- 環境を設定します。
- Google Cloud プロジェクトを作成します。
- OAuth 同意画面を構成する。
- Chat 用アプリの名前、アイコン、説明を使用して、Google Chat API を有効にして構成します。
- スタンドアロンの Apps Script プロジェクトを作成し、高度な Chat サービスを有効にします。
- このガイドでは、ユーザー認証またはアプリ認証のいずれかを使用する必要があります。Chat 用アプリとして認証するには、サービス アカウントの認証情報を作成します。手順については、Google Chat アプリとして認証と認可を行うをご覧ください。
- ユーザーとして認証するか、Chat 用アプリとして認証するかに基づいて、 認証スコープを選択します。
- 認証済みユーザーまたは通話元の Chat 用アプリがメンバーである Google Chat スペース。Chat 用アプリとして認証するには、Chat 用アプリをスペースに追加します。
Chat 用アプリとしてメッセージを送信する
このセクションでは、アプリ認証を使用して、テキスト、カード、インタラクティブなアクセサリ ウィジェットを含むメッセージを送信する方法について説明します。
アプリ認証を使用して CreateMessage() メソッドを呼び出すには、リクエストで次のフィールドを指定する必要があります。
chat.bot認可スコープ。- メッセージを投稿する
Spaceリソース。Chat 用アプリはスペースのメンバーである必要があります。 - 作成する
Messageリソース。メッセージの内容を定義するには、リッチテキスト（text）、1 つ以上のカード インターフェース（cardsV2）、またはその両方を含めることができます。
必要に応じて、次のものを含めることができます。
accessoryWidgetsフィールド。メッセージの下部にインタラクティブ ボタンを含めます。- 指定したユーザーに
privateMessageViewerフィールドを介して非公開でメッセージを送信します。 messageIdフィールド。他の API リクエストで使用するメッセージに名前を付けることができます。- スレッドを開始または返信するための
thread.threadKeyフィールドとmessageReplyOptionフィールド。スペースでスレッドを使用していない場合、このフィールドは無視されます。
次のコードは、テキスト、カード、メッセージの下部にあるクリック可能なボタンを含む Chat 用アプリとして投稿されたメッセージを Chat 用アプリが送信する方法の例を示しています。
Node.js
Python
Java
Apps Script
このサンプルを実行するには、SPACE_NAME をスペースの name フィールドの ID に置き換えます。ID は、ListSpaces() メソッドを呼び出すか、スペースの URL から取得できます。
メッセージの下部にインタラクティブ ウィジェットを追加する
このガイドの最初のコードサンプルでは、Chat 用アプリのメッセージの下部にクリック可能なボタン（アクセサリ ウィジェット）が表示されます。アクセサリ ウィジェットは、メッセージ内のテキストやカードの後に表示されます。これらのウィジェットを使用すると、次のようなさまざまな方法でユーザーにメッセージの操作を促すことができます。
- メッセージの正確さや満足度を評価する。
- メッセージ アプリまたは Chat アプリに関する問題を報告します。
- ドキュメントなどの関連コンテンツへのリンクを開きます。
- Chat アプリからの同様のメッセージを一定期間非表示にするか、スヌーズします。
アクセサリ ウィジェットを追加するには、リクエストの本文に accessoryWidgets[] フィールドを含め、含めるウィジェットを 1 つ以上指定します。
次の画像は、Chat 用アプリのユーザーが Chat 用アプリの利用体験を評価できるように、アクセサリ ウィジェット付きのテキスト メッセージを追加する Chat 用アプリを示しています。
次の例は、2 つのアクセサリ ボタンを含むテキスト メッセージを作成するリクエストの本文を示しています。ユーザーがボタンをクリックすると、対応する関数（doUpvote など）がインタラクションを処理します。
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
プライベート メッセージを送信する
Chat 用アプリは、スペース内の特定のユーザーにのみメッセージが表示されるように、非公開でメッセージを送信できます。Chat 用アプリが非公開メッセージを送信すると、メッセージには、そのメッセージが自分だけに表示されることをユーザーに知らせるラベルが表示されます。
Chat API を使用して非公開でメッセージを送信するには、リクエストの本文で privateMessageViewer フィールドを指定します。ユーザーを指定するには、Chat ユーザーを表す User リソースに値を設定します。次の例に示すように、User リソースの name フィールドを使用することもできます。
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
このサンプルを使用するには、USER_ID をユーザーの一意の ID（12345678987654321 や hao@cymbalgroup.com など）に置き換えます。ユーザーの指定について詳しくは、Google Chat ユーザーを特定して指定するをご覧ください。
非公開でメッセージを送信するには、リクエストで次の項目を省略する必要があります。
ユーザーの代わりにテキスト メッセージを送信する
このセクションでは、ユーザー認証を使用してユーザーに代わってメッセージを送信する方法について説明します。ユーザー認証を使用する場合、メッセージの内容はテキストのみにすることができ、カード インターフェースやインタラクティブ ウィジェットなど、Chat 用アプリでのみ使用できるメッセージ機能は省略する必要があります。
ユーザー認証を使用して CreateMessage() メソッドを呼び出すには、リクエストで次のフィールドを指定する必要があります。
- このメソッドのユーザー認証をサポートする認可スコープ。次のサンプルでは、
chat.messages.createスコープを使用します。 - メッセージを投稿する
Spaceリソース。認証されたユーザーはスペースのメンバーである必要があります。 - 作成する
Messageリソース。メッセージの内容を定義するには、textフィールドを含める必要があります。
必要に応じて、次のものを含めることができます。
messageIdフィールド。他の API リクエストで使用するメッセージに名前を付けることができます。- スレッドを開始または返信するための
thread.threadKeyフィールドとmessageReplyOptionフィールド。スペースでスレッドを使用していない場合、このフィールドは無視されます。
次のコードは、認証済みユーザーに代わって Chat 用アプリが特定のスペースにテキスト メッセージを送信する方法の例を示しています。
Node.js
Python
Java
Apps Script
このサンプルを実行するには、SPACE_NAME をスペースの name フィールドの ID に置き換えます。ID は、ListSpaces() メソッドを呼び出すか、スペースの URL から取得できます。
スレッドを開始する、またはスレッドに返信する
スレッドを使用するスペースでは、新しいメッセージでスレッドを開始するか、既存のスレッドに返信するかを指定できます。
デフォルトでは、Chat API を使用して作成したメッセージは新しいスレッドを開始します。スレッドを特定して後で返信できるようにするには、リクエストでスレッドキーを指定します。
- リクエストの本文で、
thread.threadKeyフィールドを指定します。 - キーがすでに存在する場合の処理を決定するには、クエリ パラメータ
messageReplyOptionを指定します。
既存のスレッドに返信するメッセージを作成するには:
- リクエストの本文に、
threadフィールドを含めます。設定されている場合は、作成したthreadKeyを指定できます。それ以外の場合は、スレッドのnameを使用する必要があります。 - クエリ パラメータ
messageReplyOptionを指定します。
次のコードは、認証済みユーザーに代わって、特定のスペースのキーで識別される特定のスレッドを開始または返信するテキスト メッセージを Chat 用アプリが送信する方法の例を示しています。
Node.js
Python
Java
Apps Script
このサンプルを実行するには、次の値を置き換えます。
THREAD_KEY: スペース内の既存のスレッドキー。新しいスレッドを作成する場合は、スレッドの一意の名前。SPACE_NAME: スペースのnameフィールドの ID。ID は、ListSpaces()メソッドを呼び出すか、スペースの URL から取得できます。
メッセージに名前を付ける
将来の API 呼び出しでメッセージを取得または指定するには、リクエストの messageId フィールドを設定してメッセージに名前を付けます。メッセージに名前を付けると、メッセージのリソース名からシステム割り当て ID（name フィールドで表される）を保存しなくても、メッセージを指定できます。
たとえば、get() メソッドを使用してメッセージを取得するには、リソース名を使用して、取得するメッセージを指定します。リソース名は spaces/{space}/messages/{message} の形式で指定します。ここで、{message} は、メッセージの作成時に設定したシステム割り当て ID またはカスタム名を表します。
メッセージに名前を付けるには、メッセージの作成時に messageId フィールドにカスタム ID を指定します。messageId フィールドは、Message リソースの clientAssignedMessageId フィールドの値を設定します。
メッセージに名前を付けることができるのは、メッセージの作成時のみです。既存のメッセージのカスタム ID の名前を変更したり、変更したりすることはできません。カスタム ID は次の要件を満たしている必要があります。
client-で始まります。たとえば、client-custom-nameは有効なカスタム ID ですが、custom-nameは無効です。- 63 文字以下で、小文字、数字、ハイフンのみが含まれます。
- スペース内で一意である。Chat 用アプリで、異なるメッセージに同じカスタム ID を使用することはできません。
次のコードは、Chat 用アプリが認証済みユーザーに代わって ID 付きのテキスト メッセージを特定のスペースに送信する方法の例を示しています。
Node.js
Python
Java
Apps Script
このサンプルを実行するには、次の値を置き換えます。
SPACE_NAME: スペースのnameフィールドの ID。ID は、ListSpaces()メソッドを呼び出すか、スペースの URL から取得できます。MESSAGE-ID:custom-で始まるメッセージの名前。指定されたスペースで Chat 用アプリによって作成された他のメッセージ名と重複しないようにする必要があります。
メッセージを引用する
CreateMessage()（rpc、rest）を呼び出し、リクエストで quotedMessageMetadata（rpc、rest）を設定することで、別のメッセージを引用できます。
スレッド内またはメインのチャットでメッセージを引用できますが、別のスレッドのメッセージを引用することはできません。
次のコードは、別のメッセージを引用するメッセージを作成する方法を示しています。
Node.js
import {createClientWithUserCredentials} from './authentication-utils.js';
const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];
// This sample shows how to create a message that quotes another message.
async function main() {
// Create a client
const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);
// Initialize request argument(s)
const request = {
// TODO(developer): Replace SPACE_NAME .
parent: 'spaces/SPACE_NAME',
message: {
text: 'I am responding to a quoted message!',
// quotedMessageMetadata lets chat apps respond to a message by quoting it.
quotedMessageMetadata: {
// TODO(developer): Replace QUOTED_MESSAGE_NAME
// and QUOTED_MESSAGE_LAST_UPDATE_TIME.
name: 'QUOTED_MESSAGE_NAME',
lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME'
}
}
};
// Make the request
const response = await chatClient.createMessage(request);
// Handle the response
console.log(response);
}
main().catch(console.error);
Python
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat
from google.protobuf.timestamp_pb2 import Timestamp
SCOPES = ['https://www.googleapis.com/auth/chat.messages.create']
# This sample shows how to create a message that quotes another message.
def create_message_quote_message():
'''Creates a message that quotes another message.'''
# Create a client
client = create_client_with_user_credentials(SCOPES)
# Create a timestamp from the RFC-3339 string.
# TODO(developer): Replace QUOTED_MESSAGE_LAST_UPDATE_TIME.
last_update_time = Timestamp()
last_update_time.FromJsonString('QUOTED_MESSAGE_LAST_UPDATE_TIME')
# Initialize request argument(s)
request = google_chat.CreateMessageRequest(
# TODO(developer): Replace SPACE_NAME.
parent='spaces/SPACE_NAME',
# Create the message.
message = google_chat.Message(
text='I am responding to a quoted message!',
# quotedMessageMetadata lets chat apps respond to a message by quoting it.
quoted_message_metadata=google_chat.QuotedMessageMetadata(
name='QUOTED_MESSAGE_NAME',
last_update_time=last_update_time
)
)
)
# Make the request
response = client.create_message(request)
# Handle the response
print(response)
create_message_quote_message()
Java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;
import com.google.chat.v1.QuotedMessageMetadata;
import com.google.protobuf.util.Timestamps;
import com.google.workspace.api.chat.samples.utils.AuthenticationUtils;
import java.text.ParseException;
// This sample shows how to create a message that quotes another message.
public class CreateMessageQuoteMessage {
public static void main(String[] args) throws Exception, ParseException {
// Create a client.
ChatServiceClient chatClient = AuthenticationUtils.createClientWithUserCredentials();
// Initialize request argument(s).
// TODO(developer): Replace SPACE_NAME, QUOTED_MESSAGE_NAME,
// and QUOTED_MESSAGE_LAST_UPDATE_TIME here.
String parent = "spaces/SPACE_NAME";
String quotedMessageName = "QUOTED_MESSAGE_NAME";
String lastUpdateTime = "QUOTED_MESSAGE_LAST_UPDATE_TIME";
QuotedMessageMetadata quotedMessageMetadata =
QuotedMessageMetadata.newBuilder()
.setName(quotedMessageName)
.setLastUpdateTime(Timestamps.parse(lastUpdateTime))
.build();
Message message = Message.newBuilder()
.setText("I am responding to a quoted message!")
.setQuotedMessageMetadata(quotedMessageMetadata)
.build();
CreateMessageRequest request =
CreateMessageRequest.newBuilder()
.setParent(parent)
.setMessage(message)
.build();
// Make the request.
Message response = chatClient.createMessage(request);
// Handle the response.
System.out.println(response);
}
}
Apps Script
/**
* Creates a message that quotes another message.
*
* Relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
* referenced in the manifest file (appsscript.json).
*/
function createMessageQuoteMessage() {
// Initialize request argument(s)
// TODO(developer): Replace SPACE_NAME here.
const parent = 'spaces/SPACE_NAME';
const message = {
// The text content of the message.
text: 'I am responding to a quoted message!',
// quotedMessageMetadata lets chat apps respond to a message by quoting it.
//
// TODO(developer): Replace QUOTED_MESSAGE_NAME
// and QUOTED_MESSAGE_LAST_UPDATE_TIME .
quotedMessageMetadata: {
name: 'QUOTED_MESSAGE_NAME',
lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME',
}
};
// Make the request
const response = Chat.Spaces.Messages.create(message, parent);
// Handle the response
console.log(response);
}
このサンプルを実行するには、次の値を置き換えます。
SPACE_NAME: スペースのnameフィールドの ID。ID は、ListSpaces()（rpc、rest）メソッドを呼び出すか、スペースの URL から取得できます。QUOTED_MESSAGE_NAME: 引用するメッセージのメッセージ リソースname（rpc、rest）。形式はspaces/{space}/messages/{message}です。QUOTED_MESSAGE_LAST_UPDATE_TIME: 引用するメッセージの最終更新時刻。メッセージが編集されていない場合は、createTime（rpc、rest）に対応します。メッセージが編集されている場合は、lastUpdateTime（rpc、rest）に対応します。
トラブルシューティング
Google Chat 用アプリまたはカードがエラーを返すと、Chat インターフェースに「エラーが発生しました」というメッセージが表示されます。または「リクエストを処理できません。」と表示されることがあります。Chat UI にエラー メッセージが表示されない場合でも、Chat 用アプリやカードで予期しない結果が生じることがあります。たとえば、カード メッセージが表示されないことがあります。
Chat UI にエラー メッセージが表示されない場合でも、Chat 用アプリのエラー ロギングが有効になっている場合は、エラーの修正に役立つ説明的なエラー メッセージとログデータを利用できます。エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。
関連トピック
- カードビルダーを使用して、Chat 用アプリの JSON カード メッセージを設計してプレビューします。
- メッセージの書式を設定する。
- メッセージの詳細を取得する。
- スペース内のメッセージを一覧表示する。
- メッセージを更新する。
- メッセージを削除する。
- Google Chat のメッセージでユーザーを特定する。
- 着信 Webhook を使用して Google Chat にメッセージを送信する。