במדריך הזה מוסבר איך להשתמש ב-Google Chat API כדי ליצור הודעות שמכילות כרטיסים אינטראקטיביים בשם משתמשים, לצרף כרטיסים להודעות קיימות ולעדכן את הכרטיסים האלה באופן אסינכרוני.
יצירה ועדכון של כרטיסים שימושיים כשרוצים לבצע את הפעולות הבאות:
- פרסום כרטיס שמייצג משימה או משאב חיצוני בשם משתמש.
- אפשר לצרף כרטיס להודעה קיימת של משתמש כדי לספק הקשר אינטראקטיבי או תהליכי עבודה.
- עדכון הסטטוס של הכרטיס (לדוגמה, מ'בתהליך' ל'הושלם') על סמך אירועים חיצוניים, בלי לחכות לאינטראקציה של המשתמש.
- רענון התוכן של כרטיס בהודעה למשתמש, כמו תצוגה מקדימה של קישור.
דרישות מוקדמות
Node.js
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה ל-OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- מתקינים את ספריית הלקוח של Google API ל-Node.js.
- יוצרים פרטי גישה בהתאם לאופן שבו רוצים לבצע אימות בבקשה של Google Chat API:
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
credentials.jsonבספרייה המקומית. - כדי לבצע אימות כאפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json.
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
Python
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה ל-OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- מתקינים את ספריית הלקוח של Google API ל-Python.
- יוצרים פרטי גישה בהתאם לאופן שבו רוצים לבצע אימות בבקשה של Google Chat API:
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
credentials.jsonבספרייה המקומית. - כדי לבצע אימות כאפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json.
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
Java
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה ל-OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- מתקינים את ספריית הלקוח של Google API ל-Java.
- יוצרים פרטי גישה בהתאם לאופן שבו רוצים לבצע אימות בבקשה של Google Chat API:
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
credentials.jsonבספרייה המקומית. - כדי לבצע אימות כאפליקציית Chat, יוצרים פרטי כניסה לחשבון שירות ושומרים אותם כקובץ JSON בשם
credentials.json.
- כדי לבצע אימות כמשתמש ב-Chat, יוצרים פרטי כניסה של מזהה לקוח OAuth ושומרים אותם כקובץ JSON בשם
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
Apps Script
- חשבון Google Workspace במהדורת Business או Enterprise עם גישה ל-Google Chat.
- מגדירים את הסביבה:
- יוצרים פרויקט ב-Google Cloud.
- הגדרת מסך ההסכמה ל-OAuth.
- מפעילים ומגדירים את Google Chat API עם שם, סמל ותיאור לאפליקציית Chat.
- יוצרים פרויקט עצמאי של Apps Script ומפעילים את שירות Chat המתקדם.
- במדריך הזה, צריך להשתמש באימות משתמשים או באפליקציות. כדי לבצע אימות כאפליקציית Chat, צריך ליצור פרטי כניסה לחשבון שירות. במאמר אימות והרשאה כאפליקציה ל-Google Chat מוסבר איך לעשות זאת.
- בוחרים היקף הרשאה בהתאם לאופן שבו רוצים לבצע אימות – כמשתמש או כאפליקציית Chat.
יצירת הודעה בכרטיס מטעם משתמש
כדי ליצור הודעה עם כרטיסים בשם משתמש, צריך להשתמש באימות משתמש.
כדי ליצור את ההודעה, צריך לציין בבקשה את הפרטים הבאים:
- היקף ההרשאות
chat.messages.createאוchat.messages. - השדה
cardsV2במשאבMessage, שמכיל את נתוני הכרטיס. - הפרמטר
cardIdבכל כרטיס, שנדרש לעדכונים אסינכרוניים.
בדוגמה הבאה מוצג איך יוצרים הודעה עם כרטיס בשם משתמש:
Node.js
/**
* This sample shows how to create a message with a card on behalf of a user.
*/
const {google} = require('googleapis');
const {auth} = require('google-auth-library');
async function main() {
// Create a client
const authClient = await auth.getClient({
scopes: ['https://www.googleapis.com/auth/chat.messages.create']
});
google.options({auth: authClient});
// Initialize the Chat API
const chat = google.chat({version: 'v1'});
// The space to create the message in.
const parent = 'spaces/SPACE_NAME';
// Create the request
const request = {
parent: parent,
requestBody: {
text: 'Here is a card created on my behalf:',
cardsV2: [{
cardId: 'unique-card-id',
card: {
header: {
title: 'Card Title',
subtitle: 'Card Subtitle'
},
sections: [{
widgets: [{
textParagraph: {
text: 'This card is attached to a user message.'
}
}]
}]
}
}]
}
};
// Call the API
const response = await chat.spaces.messages.create(request);
// Handle the response
console.log(response.data);
}
main().catch(console.error);
Python
"""
This sample shows how to create a message with a card on behalf of a user.
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
import google.auth
def create_message_with_card():
# Create a client
scopes = ["https://www.googleapis.com/auth/chat.messages.create"]
credentials, _ = google.auth.default(scopes=scopes)
# Build the service endpoint for Chat API.
service = build('chat', 'v1', credentials=credentials)
# The space to create the message in.
parent = "spaces/SPACE_NAME"
# Create the request
result = service.spaces().messages().create(
parent=parent,
body={
'text': 'Here is a card created on my behalf:',
'cardsV2': [{
'cardId': 'unique-card-id',
'card': {
'header': {
'title': 'Card Title',
'subtitle': 'Card Subtitle'
},
'sections': [{
'widgets': [{
'textParagraph': {
'text': 'This card is attached to a user message.'
}
}]
}]
}
}]
}
).execute()
print(result)
if __name__ == "__main__":
create_message_with_card()
Java
/**
* This sample shows how to create a message with a card on behalf of a user.
*/
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class CreateMessageWithCard {
public static void main(String[] args) throws Exception {
HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
GsonFactory jsonFactory = GsonFactory.getDefaultInstance();
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
.createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.messages.create"));
HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));
String parent = "spaces/SPACE_NAME";
GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + parent + "/messages");
// Construct the message body
Map<String, Object> message = new HashMap<>();
message.put("text", "Here is a card created on my behalf:");
Map<String, Object> header = new HashMap<>();
header.put("title", "Card Title");
header.put("subtitle", "Card Subtitle");
Map<String, Object> textParagraph = new HashMap<>();
textParagraph.put("text", "This card is attached to a user message.");
Map<String, Object> widget = new HashMap<>();
widget.put("textParagraph", textParagraph);
Map<String, Object> section = new HashMap<>();
section.put("widgets", Collections.singletonList(widget));
Map<String, Object> card = new HashMap<>();
card.put("header", header);
card.put("sections", Collections.singletonList(section));
Map<String, Object> cardWithId = new HashMap<>();
cardWithId.put("cardId", "unique-card-id");
cardWithId.put("card", card);
message.put("cardsV2", Collections.singletonList(cardWithId));
HttpRequest request = requestFactory.buildPostRequest(url, new JsonHttpContent(jsonFactory, message));
System.out.println(request.execute().parseAsString());
}
}
Apps Script
/**
* This sample shows how to create a message with a card on behalf of a user.
*/
function createMessageWithCard() {
const parent = 'spaces/SPACE_NAME';
const url = `https://chat.googleapis.com/v1/${parent}/messages`;
const message = {
text: 'Here is a card created on my behalf:',
cardsV2: [{
cardId: 'unique-card-id',
card: {
header: {
title: 'Card Title',
subtitle: 'Card Subtitle'
},
sections: [{
widgets: [{
textParagraph: {
text: 'This card is attached to a user message.'
}
}]
}]
}
}]
};
const options = {
method: 'post',
headers: {
Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
},
contentType: 'application/json',
payload: JSON.stringify(message),
muteHttpExceptions: true
};
try {
const response = UrlFetchApp.fetch(url, options);
console.log(response.getContentText());
} catch (err) {
console.log('Failed to create message: ' + err.message);
}
}
צירוף כרטיסים להודעה קיימת בשם משתמש
כדי לצרף כרטיסים להודעה קיימת בשם משתמש, צריך להפעיל את השיטה patch באמצעות אימות משתמש.
כדי לצרף כרטיסים להודעה, צריך לציין בבקשה את הפרטים הבאים:
- היקף ההרשאה
chat.messages. - ה-
nameשל ההודעה שרוצים לעדכן, בפורמטspaces/{space}/messages/{message}. - הערך של
updateMaskהוגדר ל-cards_v2. כשמעדכנים הודעה עם אימות משתמש,cards_v2חייב להיות השדה היחיד במסכת העדכון. אי אפשר לעדכן את ההודעותtextו-cards_v2באותה בקשה. - השדה
cardsV2במשאבMessage, שמכיל את נתוני הכרטיס. - ה-
cardIdשל כל כרטיס, שנדרש לעדכונים אסינכרוניים עתידיים.
בדוגמה הבאה אפשר לראות איך מצרפים כרטיס להודעה קיימת בשם משתמש:
Node.js
/**
* This sample shows how to attach a card to an existing message on behalf of a user.
*/
const {google} = require('googleapis');
const {auth} = require('google-auth-library');
async function main() {
// Create a client with user credentials
const authClient = await auth.getClient({
scopes: ['https://www.googleapis.com/auth/chat.messages']
});
google.options({auth: authClient});
// Initialize the Chat API
const chat = google.chat({version: 'v1'});
// The message to update.
const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
// Create the request
const request = {
name: messageName,
updateMask: 'cards_v2',
requestBody: {
cardsV2: [{
cardId: 'unique-card-id',
card: {
header: {
title: 'Card Title',
subtitle: 'Card Subtitle'
},
sections: [{
widgets: [{
textParagraph: {
text: 'This card was attached to an existing user message.'
}
}]
}]
}
}]
}
};
// Call the API
const response = await chat.spaces.messages.patch(request);
// Handle the response
console.log(response.data);
}
main().catch(console.error);
Python
"""
This sample shows how to attach a card to an existing message on behalf of a user.
"""
from googleapiclient.discovery import build
import google.auth
def attach_card_to_message():
# Create a client with user credentials
scopes = ["https://www.googleapis.com/auth/chat.messages"]
credentials, _ = google.auth.default(scopes=scopes)
# Build the service endpoint for Chat API.
service = build('chat', 'v1', credentials=credentials)
# The message to update.
message_name = "spaces/SPACE_NAME/messages/MESSAGE_ID"
# Create the request
result = service.spaces().messages().patch(
name=message_name,
updateMask="cards_v2",
body={
'cardsV2': [{
'cardId': 'unique-card-id',
'card': {
'header': {
'title': 'Card Title',
'subtitle': 'Card Subtitle'
},
'sections': [{
'widgets': [{
'textParagraph': {
'text': 'This card was attached to an existing user message.'
}
}]
}]
}
}]
}
).execute()
print(result)
if __name__ == "__main__":
attach_card_to_message()
Java
/**
* This sample shows how to attach a card to an existing message on behalf of a user.
*/
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class AttachCardToMessage {
public static void main(String[] args) throws Exception {
HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
GsonFactory jsonFactory = GsonFactory.getDefaultInstance();
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
.createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.messages"));
HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));
String messageName = "spaces/SPACE_NAME/messages/MESSAGE_ID";
GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + messageName + "?updateMask=cards_v2");
// Construct the card body
Map<String, Object> header = new HashMap<>();
header.put("title", "Card Title");
header.put("subtitle", "Card Subtitle");
Map<String, Object> textParagraph = new HashMap<>();
textParagraph.put("text", "This card was attached to an existing user message.");
Map<String, Object> widget = new HashMap<>();
widget.put("textParagraph", textParagraph);
Map<String, Object> section = new HashMap<>();
section.put("widgets", Collections.singletonList(widget));
Map<String, Object> card = new HashMap<>();
card.put("header", header);
card.put("sections", Collections.singletonList(section));
Map<String, Object> cardWithId = new HashMap<>();
cardWithId.put("cardId", "unique-card-id");
cardWithId.put("card", card);
Map<String, Object> message = new HashMap<>();
message.put("cardsV2", Collections.singletonList(cardWithId));
HttpRequest request = requestFactory.buildPatchRequest(url, new JsonHttpContent(jsonFactory, message));
System.out.println(request.execute().parseAsString());
}
}
Apps Script
/**
* This sample shows how to attach a card to an existing message on behalf of a user.
*/
function attachCardToMessage() {
const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
const url = `https://chat.googleapis.com/v1/${messageName}?updateMask=cards_v2`;
const message = {
cardsV2: [{
cardId: 'unique-card-id',
card: {
header: {
title: 'Card Title',
subtitle: 'Card Subtitle'
},
sections: [{
widgets: [{
textParagraph: {
text: 'This card was attached to an existing user message.'
}
}]
}]
}
}]
};
const options = {
method: 'patch',
headers: {
Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
},
contentType: 'application/json',
payload: JSON.stringify(message),
muteHttpExceptions: true
};
try {
const response = UrlFetchApp.fetch(url, options);
console.log(response.getContentText());
} catch (err) {
console.log('Failed to attach card: ' + err.message);
}
}
עדכון כרטיסים באופן אסינכרוני
אחרי שיוצרים הודעה עם כרטיסים או מצרפים כרטיסים להודעה קיימת, אפשר לעדכן את הכרטיסים באופן אסינכרוני באמצעות אימות אפליקציה. כך האפליקציה יכולה לרענן את תוכן הכרטיס בלי שהמשתמש יצטרך לבצע פעולה. רק אפליקציית Chat שהוסיפה את הכרטיס להודעה של המשתמש יכולה להחליף אותו. אם משתמש עורך את טקסט ההודעה, הכרטיסים בבעלות האפליקציה מוסרים והאפליקציה לא יכולה יותר לעדכן אותם.
כשכרטיסים מתעדכנים באופן אסינכרוני, ליד השיוך של הכרטיס מוצג ב-Google Chat הסימן נערך, כדי ליידע את המשתמשים שהתוכן של הכרטיס התעדכן בנפרד מההודעה.
כדי לעדכן את הכרטיסים, קוראים לשיטת replaceCards עם הפרמטרים הבאים:
- היקף ההרשאה
chat.bot. - ה-
nameשל ההודעה לעדכון. - הרשימה החדשה
cardsV2. הפעולה הזו תחליף את כל הכרטיסים הקיימים בהודעה. אם מספקים רשימה ריקה, הכרטיסים מוסרים. אם מסירים את כל הכרטיסים, אי אפשר להשתמש ב-replaceCardsכדי להוסיף אותם מחדש. במקום זאת, צריך להשתמש ב-UpdateMessageעם אימות משתמש כדי לצרף כרטיסים חדשים.
בדוגמה הבאה אפשר לראות איך מעדכנים את הכרטיסים של הודעה:
Node.js
/**
* This sample shows how to update cards on a message.
*/
const {google} = require('googleapis');
const {auth} = require('google-auth-library');
async function main() {
// Create a client with app credentials
const authClient = await auth.getClient({
scopes: ['https://www.googleapis.com/auth/chat.bot']
});
google.options({auth: authClient});
// Initialize the Chat API
const chat = google.chat({version: 'v1'});
// The message to update.
const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
// Create the request
const request = {
name: messageName,
requestBody: {
cardsV2: [{
cardId: 'unique-card-id',
card: {
header: {
title: 'Updated Card Title',
subtitle: 'Updated Card Subtitle'
},
sections: [{
widgets: [{
textParagraph: {
text: 'The card content has been updated asynchronously.'
}
}]
}]
}
}]
}
};
// Call the API
await chat.spaces.messages.replaceCards(request);
console.log('Cards updated.');
}
main().catch(console.error);
Python
"""
This sample shows how to update cards on a message.
"""
from google.oauth2 import service_account
from googleapiclient.discovery import build
import google.auth
def replace_message_cards():
# Create a client with app credentials
scopes = ["https://www.googleapis.com/auth/chat.bot"]
credentials, _ = google.auth.default(scopes=scopes)
# Build the service endpoint for Chat API.
service = build('chat', 'v1', credentials=credentials)
# The message to update.
message_name = "spaces/SPACE_NAME/messages/MESSAGE_ID"
# Create the request
result = service.spaces().messages().replaceCards(
name=message_name,
body={
'cardsV2': [{
'cardId': 'unique-card-id',
'card': {
'header': {
'title': 'Updated Card Title',
'subtitle': 'Updated Card Subtitle'
},
'sections': [{
'widgets': [{
'textParagraph': {
'text': 'The card content has been updated asynchronously.'
}
}]
}]
}
}]
}
).execute()
print("Cards updated.")
if __name__ == "__main__":
replace_message_cards()
Java
/**
* This sample shows how to update cards on a message.
*/
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.gson.GsonFactory;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
public class ReplaceMessageCards {
public static void main(String[] args) throws Exception {
HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
GsonFactory jsonFactory = GsonFactory.getDefaultInstance();
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
.createScoped(Arrays.asList("https://www.googleapis.com/auth/chat.bot"));
HttpRequestFactory requestFactory = transport.createRequestFactory(new HttpCredentialsAdapter(credentials));
String messageName = "spaces/SPACE_NAME/messages/MESSAGE_ID";
GenericUrl url = new GenericUrl("https://chat.googleapis.com/v1/" + messageName + ":replaceCards");
// Construct the body
Map<String, Object> header = new HashMap<>();
header.put("title", "Updated Card Title");
header.put("subtitle", "Updated Card Subtitle");
Map<String, Object> textParagraph = new HashMap<>();
textParagraph.put("text", "The card content has been updated asynchronously.");
Map<String, Object> widget = new HashMap<>();
widget.put("textParagraph", textParagraph);
Map<String, Object> section = new HashMap<>();
section.put("widgets", Collections.singletonList(widget));
Map<String, Object> card = new HashMap<>();
card.put("header", header);
card.put("sections", Collections.singletonList(section));
Map<String, Object> cardWithId = new HashMap<>();
cardWithId.put("cardId", "unique-card-id");
cardWithId.put("card", card);
Map<String, Object> body = new HashMap<>();
body.put("cardsV2", Collections.singletonList(cardWithId));
HttpRequest request = requestFactory.buildPostRequest(url, new JsonHttpContent(jsonFactory, body));
request.execute();
System.out.println("Cards updated.");
}
}
Apps Script
/**
* This sample shows how to update cards on a message.
*/
function replaceMessageCards() {
const messageName = 'spaces/SPACE_NAME/messages/MESSAGE_ID';
const url = `https://chat.googleapis.com/v1/${messageName}:replaceCards`;
const request = {
cardsV2: [{
cardId: 'unique-card-id',
card: {
header: {
title: 'Updated Card Title',
subtitle: 'Updated Card Subtitle'
},
sections: [{
widgets: [{
textParagraph: {
text: 'The card content has been updated asynchronously.'
}
}]
}]
}
}]
};
const options = {
method: 'post',
headers: {
Authorization: 'Bearer ' + ScriptApp.getOAuthToken()
},
contentType: 'application/json',
payload: JSON.stringify(request),
muteHttpExceptions: true
};
try {
const response = UrlFetchApp.fetch(url, options);
console.log('Cards updated.');
} catch (err) {
console.log('Failed to update cards: ' + err.message);
}
}
מגבלות
כשיוצרים הודעות עם כרטיסים בשם משתמש או מעדכנים כרטיסים, אפליקציית Chat צריכה להיות חברה במרחב. הדרישה הזו חלה במקרים הבאים:
- יצירת הודעה עם כרטיסים מטעם משתמש.
- צירוף כרטיסים להודעה קיימת בשם משתמש.
- החלפה או עדכון של הכרטיסים בהודעה.
הדרישה הזו שונה מדרישות של ממשקי API אחרים שמשתמשים באימות משתמשים, שבדרך כלל לא מחייבים שהאפליקציה תהיה חברה במרחב.
כשמעדכנים הודעה באמצעות אימות משתמש, אם מציינים את
cards_v2ב-updateMask, אי אפשר לעדכן שדות אחרים (כמוtext) באותה בקשה.בשיטה
replaceCardsאפשר להחליף כרטיסים ולהסיר אותם, ואפשר להוסיף כרטיסים נוספים תוך כדי החלפה, אבל אי אפשר להוסיף כרטיסים להודעה שכבר יש בה כרטיסים. כדי לצרף כרטיסים להודעה שלא כוללת כרטיסים, צריך להשתמש ב-UpdateMessageעם אימות משתמש.שיוך ובעלות על הכרטיס:
- הכרטיסים שמצורפים להודעת משתמש משויכים לאפליקציית Chat שצרפה אותם ונמצאים בבעלותה, כפי שמצוין בשדה
CardWithId.ownerלקריאה בלבד. - אפליקציית Chat יכולה להחליף רק כרטיסים שהיא צירפה להודעה, ולא כרטיסים שאפליקציות אחרות של Chat צירפו.
- הכרטיסים שמצורפים להודעת משתמש משויכים לאפליקציית Chat שצרפה אותם ונמצאים בבעלותה, כפי שמצוין בשדה
אם משתמש עורך את הטקסט של ההודעה, הכרטיסים בבעלות אפליקציית Chat מוסרים, ואי אפשר לעדכן אותם יותר.