このガイドでは、Google Chat アプリがメッセージを送信するさまざまな方法について説明します。
- ユーザーの操作に反応することで、テキスト メッセージやカード メッセージをリアルタイムで送信できます。
Message
リソースのcreate
メソッドを呼び出して、テキスト メッセージとカード メッセージを非同期で送信します。- メッセージ スレッドを開始するか、スレッドに返信します。
- メッセージを送信して名前を付けます。
Message
リソースは、Google Chat のテキストまたはカード メッセージを表します。Google Chat API 内のメッセージに対して create
、get
、update
、delete
を行うには、対応するメソッドを呼び出します。テキスト メッセージとカード メッセージの詳細については、Google Chat メッセージの概要をご覧ください。
メッセージの最大サイズ(テキストやカードを含む)は 32,000 バイトです。メッセージがこのサイズを超えた場合、Chat アプリは代わりに複数のメッセージを送信できます。
Google Chat アプリでは、Google Chat API の Message
リソースの create
メソッドを呼び出してテキスト メッセージやカード メッセージを非同期で送信する代わりに、ユーザーの操作にリアルタイムで応答するメッセージを作成することもできます。ユーザー操作に対するレスポンスには認証は必要なく、インタラクティブなダイアログやリンク プレビューなど、他のタイプのメッセージがサポートされています。詳しくは、Google Chat アプリでの操作を受信して応答するをご覧ください。
前提条件
Node.js
- Google Chat へのアクセス権を持つ Google Workspace アカウント。
- Google Chat API が有効で構成されている Google Cloud プロジェクト。手順については、Google Chat アプリを作成するをご覧ください。
- Chat アプリが非同期メッセージを送信するために構成された認可。リアルタイムでメッセージを送信するために認可構成は必要ありません。
- テキスト メッセージの送信では、次の両方の承認方法がサポートされています。
- カード メッセージを送信するには、
chat.bot
認証スコープを使用したアプリの認証が必要です。
Python
- Google Chat へのアクセス権を持つ Google Workspace アカウント。
- Python 3.6 以降
- pip パッケージ管理ツール
最新の Python 用 Google クライアント ライブラリ。これらをインストールまたは更新するには、コマンドライン インターフェースで次のコマンドを実行します。
pip3 install --upgrade google-api-python-client google-auth
- Google Chat API が有効で構成されている Google Cloud プロジェクト。手順については、Google Chat アプリを作成するをご覧ください。
Chat アプリが非同期メッセージを送信するために構成された認可。リアルタイムでメッセージを送信するために 認可構成は必要ありません
- テキスト メッセージの送信では、次の両方の承認方法がサポートされています。
- カード メッセージを送信するには、
chat.bot
認証スコープを使用したアプリの認証が必要です。
Apps Script
- Google Chat へのアクセス権を持つ Google Workspace アカウント。
- 公開された Chat アプリ。Chat アプリを作成するには、このquickstartに沿って操作してください。
- Chat アプリが非同期メッセージを送信するために構成された認可。リアルタイムでメッセージを送信するために認可構成は必要ありません。
- テキスト メッセージの送信では、次の両方の承認方法がサポートされています。
- カード メッセージを送信するには、
chat.bot
認証スコープを使用したアプリの認証が必要です。
テキスト メッセージを送信する
このセクションでは、次の 2 つの方法でテキスト メッセージを送信する方法について説明します。
- ユーザーの操作に返信することで、テキスト メッセージをリアルタイムで送信できます。
- Google Chat API を非同期で呼び出し、テキスト メッセージを送信します。
テキスト メッセージをリアルタイムで送信
この例では、スペースにテキスト メッセージが追加されるたびに、Chat アプリがテキスト メッセージを作成して送信します。ユーザーのオンボーディングに関するベスト プラクティスについては、便利なオンボーディングでユーザーとスペースの利用を開始するをご覧ください。
ユーザーがスペースに Chat 用アプリを追加したときにテキスト メッセージを送信するため、Chat アプリは ADDED_TO_SPACE
インタラクション イベントに応答します。ADDED_TO_SPACE
操作イベントにテキスト メッセージで応答するには、次のコードを使用します。
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports.onMessage = function onMessage(req, res) {
if (req.method === 'GET' || !req.body.message) {
res.send(
'Hello! This function is meant to be used in a Google Chat space.');
}
// Send an onboarding message when added to a Chat space
if (req.body.type === 'ADDED_TO_SPACE') {
res.json({
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
learn what else I can do, type `/help`.'
});
}
};
Apps Script
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} event The event object from Chat API.
* @return {Object} Response from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
function onAddToSpace(event) {
return {
'text': 'Hi, Cymbal at your service. I help you manage your calendar
from Google Chat. Take a look at your schedule today by typing
`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
what else I can do, type `/help`.'
}
}
このコードサンプルは、次のテキスト メッセージを返します。
テキスト メッセージを非同期で送信する
次のセクションでは、アプリ認証とユーザー認証を使用してテキスト メッセージを非同期で送信する方法について説明します。
テキスト メッセージを送信するには、リクエストに次のものを渡します。
- アプリ認証では、
chat.bot
承認スコープを指定します。ユーザー認証では、chat.messages.create
承認スコープを指定します。 Message
リソースのcreate
メソッドを呼び出します。
アプリの認証を使用してテキスト メッセージを送信する
アプリ認証を使用してテキスト メッセージを送信する方法は、次のとおりです。
Python
- 作業ディレクトリに、
chat_create_text_message_app.py
という名前のファイルを作成します。 chat_create_text_message_app.py
に次のコードを含めます。from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
コードで
SPACE
をスペース名に置き換えます。スペースは、Chat API のspaces.list()
メソッドまたはスペースの URL から取得します。作業ディレクトリでサンプルをビルドして実行します。
python3 chat_create_text_message_app.py
Chat API は、送信されたメッセージの詳細を示す Message
のインスタンスを返します。
ユーザー認証を使用してテキスト メッセージを送信する
ユーザー認証を使用してテキスト メッセージを送信する方法は次のとおりです。
Python
- 作業ディレクトリに、
chat_create_text_message_user.py
という名前のファイルを作成します。 chat_create_text_message_user.py
に次のコードを含めます。import os.path from google.auth.transport.requests import Request from google.oauth2.credentials import Credentials from google_auth_oauthlib.flow import InstalledAppFlow from googleapiclient.discovery import build from googleapiclient.errors import HttpError # Define your app's authorization scopes. # When modifying these scopes, delete the file token.json, if it exists. SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"] def main(): ''' Authenticates with Chat API via user credentials, then creates a text message in a Chat space. ''' # Start with no credentials. creds = None # Authenticate with Google Workspace # and get user authorization. flow = InstalledAppFlow.from_client_secrets_file( 'client_secrets.json', SCOPES) creds = flow.run_local_server() # Build a service endpoint for Chat API. chat = build('chat', 'v1', credentials=creds) # Use the service endpoint to call Chat API. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body={'text': 'Hello, world!'} ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
コードで
SPACE
をスペース名に置き換えます。スペースは、Chat API のspaces.list()
メソッドまたはスペースの URL から取得します。作業ディレクトリでサンプルをビルドして実行します。
python3 chat_create_text_message_user.py
Chat API は、送信されたメッセージの詳細を示す Message
のインスタンスを返します。
カード メッセージを送信する
このセクションでは、次の 2 つの方法でカード メッセージを送信する方法について説明します。
- ユーザーの操作に反応して、カード メッセージをリアルタイムで送信します。
- Google Chat API を非同期で呼び出し、カード メッセージを送信します。
カード メッセージをリアルタイムで送信する
Chat アプリでは、ユーザー操作(Chat アプリにメッセージを送信したときやスペースに Chat アプリを追加したときなど)に応答するカード メッセージを作成できます。ユーザー操作への応答について詳しくは、Chat 用アプリの操作イベントを受信して応答するをご覧ください。
この例では、ユーザーが Chat アプリにメッセージを送信すると、Chat アプリがユーザーの名前とアバター画像を表示するカード メッセージを送信して応答します。
カード メッセージを非同期で送信する
カード メッセージを送信するには、リクエストに以下を渡します。
- アプリ認証では、
chat.bot
承認スコープを指定します。ユーザー認証を使用してカード メッセージを送信することはできません。 Message
リソースのcreate
メソッドを呼び出します。
カード メッセージの例を次に示します。
アプリの認証を使用してカード メッセージを送信する方法は次のとおりです。
Python
- 作業ディレクトリに、
chat_create_card_message.py
という名前のファイルを作成します。 chat_create_card_message.py
に次のコードを含めます。from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # The message to create. body= { 'cardsV2': [{ 'cardId': 'createCardMessage', 'card': { 'header': { 'title': 'A card message!', 'subtitle': 'Created with the Chat API', 'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png', 'imageType': 'CIRCLE' }, 'sections': [ { 'widgets': [ { 'buttonList': { 'buttons': [ { 'text': 'Read the docs!', 'onClick': { 'openLink': { 'url': 'https://developers.google.com/chat' } } } ] } } ] } ] } }] } ).execute() print(result)
コードで
SPACE
をスペース名に置き換えます。スペースは、Chat API のspaces.list
メソッドまたはスペースの URL から取得します。作業ディレクトリでサンプルをビルドして実行します。
python3 chat_create_card_message.py
メッセージ スレッドを開始または返信する
メッセージ スレッドを開始するには、メッセージを送信し、thread.name
を空のままにします。これにより、スレッドの作成時に Google Chat によって値が入力されます。必要に応じて、スレッドの名前をカスタマイズするには、thread.threadKey
フィールドを指定します。
メッセージ スレッドに返信するには、スレッドの threadKey
フィールドまたは name
フィールドを指定してメッセージを送信します。スレッドがユーザーまたは他の Chat アプリによって作成された場合は、thread.name
フィールドを使用する必要があります。
一致するスレッドが見つからない場合は、messageReplyOption
フィールドを設定して、メッセージを新しいスレッドを開始するか、投稿に失敗するかを指定できます。
messageReplyOption
が設定されている場合は、thread.name
または thread.threadKey
も設定する必要があります。
threadKey
フィールドを nameOfThread
として定義してスレッドを開始したり、スレッドに返信したりする方法は次のとおりです。
Python
- 作業ディレクトリに、
chat_create_message_thread.py
という名前のファイルを作成します。 chat_create_message_thread.py
に次のコードを含めます。from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Whether to start a thread or reply to an existing one. # # Required when threading is enabled in a space unless starting a # thread. Ignored in other space types. Threading is enabled when # space.spaceThreadingState is THREADED_MESSAGES. # # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread # if one exists, otherwise it starts a new one. messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD', # The message body. body={ # The message to create. 'text': 'Start or reply to another message in a thread!', # The thread to start or reply to. 'thread': { 'threadKey': 'nameOfThread' } } ).execute() print(result)
コードで
SPACE
をスペース名に置き換えます。スペースは、Chat API のspaces.list
メソッドまたはスペースの URL から取得します。作業ディレクトリでサンプルをビルドして実行します。
python3 chat_create_message_thread.py
Chat API は、送信されたメッセージの詳細を示す Message
のインスタンスを返します。
メッセージに名前を付ける
このセクションでは、メッセージのカスタム ID を設定してメッセージに名前を付ける方法について説明します。カスタム ID を使用して、メッセージを取得、更新、削除できます。カスタム ID を使用すると、メッセージのリソース名(name
フィールドで指定)からシステムによって割り当てられた ID を保存しなくても、メッセージを指定できます。リソース名は、メッセージの作成時にレスポンスの本文に生成されます。
たとえば、get()
メソッドを使用してメッセージを取得するには、リソース名を使用して取得するメッセージを指定します。リソース名の形式は spaces/{space}/messages/{message}
です。ここで、{message}
はシステムによって割り当てられた ID を表します。メッセージに名前を付けた場合は、{message}
の値をカスタム ID に置き換えることができます。
メッセージに名前を付けるには、メッセージの作成時に messageId
フィールドにカスタム ID を指定します。messageId
フィールドは、Message
リソースの clientAssignedMessageId
フィールドの値を設定します。
メッセージに名前を付けることができるのは、メッセージの作成時のみです。既存のメッセージのカスタム ID に名前を付けたり、変更したりすることはできません。カスタム ID は次の要件を満たす必要があります。
client-
で始まります。たとえば、client-custom-name
は有効なカスタム ID ですが、custom-name
は有効ではありません。- 63 文字以下で、小文字、数字、ハイフンのみを使用します。
- スペース内で一意である。Chat アプリでは、同じカスタム ID を異なるメッセージに使用することはできません。
カスタム ID を使用してメッセージを送信する方法は次のとおりです。
Python
- 作業ディレクトリに、
chat_create_named_message.py
という名前のファイルを作成します。 chat_create_named_message.py
に次のコードを含めます。from apiclient.discovery import build from google.oauth2 import service_account # Specify required scopes. SCOPES = ['https://www.googleapis.com/auth/chat.bot'] # Specify service account details. CREDENTIALS = service_account.Credentials.from_service_account_file( 'credentials.json', scopes=SCOPES) # Build the URI and authenticate with the service account. chat = build('chat', 'v1', credentials=CREDENTIALS) # Create a Chat message with a custom name. result = chat.spaces().messages().create( # The space to create the message in. # # Replace SPACE with a space name. # Obtain the space name from the spaces resource of Chat API, # or from a space's URL. parent='spaces/SPACE', # Custom name for the message used to facilitate later operations. messageId='client-NAME', # The message to create. body={'text': 'Hello, world!'} ).execute() print(result)
コードの次のように置き換えます。
SPACE
: メッセージを投稿するスペースの ID。これは、Chat API のspaces.list
メソッドまたはスペースの URL から取得できます。NAME
: メッセージのカスタム名。
作業ディレクトリでサンプルをビルドして実行します。
python3 chat_create_named_message.py
Chat API は Message
のインスタンスを返します。
メッセージの下部にインタラクティブなウィジェットを追加する
必要に応じて、アクセサリ ウィジェットを使用してメッセージを追加できます。アクセサリ ウィジェットは、メッセージ内のテキストやカードの後に表示されます。これらのウィジェットを使用すると、さまざまな方法でユーザーにメッセージの操作を促すことができます。次に例を示します。
- メッセージの正確性または満足度を評価してください。
- メッセージまたは Chat アプリに関する問題を報告します。
- ドキュメントなどの関連コンテンツへのリンクを開きます。
- Chat アプリから同様のメッセージを一定期間、拒否またはスヌーズする。
アクセサリ ウィジェットを追加するには、メッセージに accessoryWidgets[]
オブジェクトを含め、含めたい AccessoryWidgets
を 1 つ以上指定します。メッセージは、スペース内のすべてのユーザーに表示される必要があります(プライベート メッセージにアクセサリ ウィジェットを追加することはできません)。
次の図は、ユーザーが Chat アプリのエクスペリエンスを評価できるように、アクセサリ ウィジェットを使用してテキスト メッセージを付加する Chat アプリを示しています。
次のコードサンプルは、このメッセージの JSON を示しています。ユーザーがいずれかのボタンをクリックすると、評価を処理する対応する関数(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 アプリでは、テキスト メッセージやカード メッセージを非公開で送信できるため、スペース内の 1 人のユーザーにのみメッセージを表示できます。非公開でメッセージを送信するには、メッセージの privateMessageViewer
フィールドを指定します。プライベート メッセージを送信できるのは Chat アプリのみです。プライベート メッセージを非同期で送信するには、アプリの認証を使用する必要があります。
詳しくは、Google Chat ユーザーにプライベート メッセージを送信するをご覧ください。
トラブルシューティング
Google Chat アプリまたはカードがエラーを返すと、Chat インターフェースに「エラーが発生しました」というメッセージが表示されます。または「リクエストを処理できません」が表示されます。Chat UI にエラー メッセージが表示されなくても、Chat アプリやカードが予期しない結果(カード メッセージが表示されないなど)を生成することがあります。
Chat UI にエラー メッセージが表示されない場合がありますが、Chat 用アプリのエラーロギングが有効になっている場合は、説明的なエラー メッセージとログデータを使用してエラーを修正できます。エラーの表示、デバッグ、修正については、Google Chat のエラーのトラブルシューティングと修正をご覧ください。
関連トピック
- メールの書式を設定します。
- メッセージの詳細を取得する
- スペース内のメッセージを一覧表示する
- メッセージを更新する。
- メールを削除する。
- Google Chat のメッセージでユーザーを特定する
- 着信 Webhook を使用して Google Chat にメッセージを送信する