Actions

The ballerinax/googleapis.chat package exposes the following client:

Client	Purpose
`Client`	Space, message, member, and attachment management on the Google Chat REST API.

Client

Configuration

Field	Type	Default	Description
`auth`	`ServiceAccountAuthConfig\|OAuth2Config\|http:BearerTokenConfig`	Required	Authentication configuration: service account, OAuth2, or bearer token.
`httpVersion`	`http:HttpVersion`	`http:HTTP_2_0`	The HTTP version understood by the client.
`timeout`	`decimal`	`30`	The maximum time to wait (in seconds) for a response.
`forwarded`	`string`	`"disable"`	The choice of setting `forwarded`/`x-forwarded` header.
`retryConfig`	`http:RetryConfig`	`()`	Retry configuration for failed requests.
`cache`	`http:CacheConfig`		HTTP caching-related configurations.

Initializing the client

import ballerinax/googleapis.chat;

configurable chat:OAuth2Config oauthAuth = ?;

final chat:Client chatClient = check new ({auth: oauthAuth});

Operations

Most Client operations are resource functions, invoked with the HTTP method and resource path shown in each signature.

Spaces

get spaces

GET /spaces

Lists spaces the app has access to.

Parameters:

Name	Type	Required	Description
`pageSize`	`int?`	No	The maximum number of spaces to return.
`filter`	`string?`	No	A filter query, for example by space type.

Returns: ListSpacesResponse|error

Sample code:

chat:ListSpacesResponse spaces = check chatClient->/spaces();

Sample response:

{
    "spaces": [{"name": "spaces/AAAA", "displayName": "Engineering", "spaceType": "SPACE"}]
}

get spaces/[spaceId]

GET /spaces/[spaceId]

Gets details of a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name, for example `spaces/AAAA`.

Returns: Space|error

Sample code:

chat:Space space = check chatClient->/spaces/[spaceId]();

post spaces

POST /spaces

Creates a named space (requires user authentication).

Parameters:

Name	Type	Required	Description
`payload`	`Space`	Yes	The space to create.

Returns: Space|error

Sample code:

chat:Space created = check chatClient->/spaces.post({displayName: "Engineering", spaceType: "SPACE"});

patch spaces/[spaceId]

PATCH /spaces/[spaceId]

Updates a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The ID of the space to update.
`payload`	`Space`	Yes	The updated space fields.
`updateMask`	`string?`	No	The field paths to update (comma-separated).

Returns: Space|error

Sample code:

chat:Space updated = check chatClient->/spaces/[spaceId].patch({displayName: "Engineering Team"},
    updateMask = "displayName");

delete spaces/[spaceId]

DELETE /spaces/[spaceId]

Deletes a named space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The ID of the space to delete.

Returns: error?

Sample code:

check chatClient->/spaces/[spaceId].delete();

get spaces/findDirectMessage

GET /spaces:findDirectMessage

Finds an existing direct message space with a specified user.

Parameters:

Name	Type	Required	Description
`name`	`string?`	No	Resource name of the user to find a DM with, for example `users/[email protected]`.

Returns: Space|error

Sample code:

chat:Space dm = check chatClient->/spaces/findDirectMessage(name = "users/[email protected]");

get spaces/search

GET /spaces:search

Searches for spaces in a Google Workspace organization. Requires the caller to be a Workspace administrator with the manage chat and spaces conversations privilege, and the chat.admin.spaces or chat.admin.spaces.readonly OAuth scope.

Parameters:

Name	Type	Required	Description
`query`	`string`	Yes	A search query, for example `customer = "customers/my_customer" AND spaceType = "SPACE"`. `customer` and `spaceType` are required fields in the query.
`useAdminAccess`	`boolean`	Yes	Must be `true`. Runs the method using the caller's admin privileges.
`pageSize`	`int?`	No	Maximum number of spaces to return (default 100, max 1000).
`pageToken`	`string?`	No	Page token from a previous search request.
`orderBy`	`string?`	No	How to order results, for example `lastActiveTime DESC`.

Returns: SearchSpacesResponse|error

Sample code:

chat:SearchSpacesResponse results = check chatClient->/spaces/search(
    query = "customer = \"customers/my_customer\" AND spaceType = \"SPACE\"", useAdminAccess = true);

post spaces/setup

POST /spaces:setup

Creates a space and adds specified users or Google Groups to it in one call. The calling user is added automatically and shouldn't be listed in memberships. Requires user authentication with the chat.spaces or chat.spaces.create OAuth scope.

Parameters:

Name	Type	Required	Description
`payload`	`SetUpSpaceRequest`	Yes	The space to create (`space.spaceType` is required: `SPACE`, `GROUP_CHAT`, or `DIRECT_MESSAGE`), plus optional `requestId` and up to 49 initial `memberships`.

Returns: Space|error

Sample code:

chat:Space created = check chatClient->/spaces/setup.post({
    space: {displayName: "Engineering", spaceType: "SPACE"},
    memberships: [{member: {name: "users/[email protected]", 'type: "HUMAN"}}]
});

Messages

post spaces/[spaceId]/messages

POST /spaces/[spaceId]/messages

Sends a message to a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`payload`	`Message`	Yes	The message content.

Returns: Message|error

Sample code:

chat:Message sent = check chatClient->/spaces/[spaceId]/messages.post({
    text: "Hello from Ballerina!"
});

Sample response:

{
    "name": "spaces/AAAA/messages/BBBB",
    "text": "Hello from Ballerina!"
}

get spaces/[spaceId]/messages

GET /spaces/[spaceId]/messages

Lists messages in a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`pageSize`	`int?`	No	Maximum number of messages to return (max 1000).
`pageToken`	`string?`	No	Page token from a previous list request.
`filter`	`string?`	No	A query filter.
`orderBy`	`string?`	No	Ordering of results, for example `createTime desc`.
`showDeleted`	`boolean?`	No	Whether to include deleted messages in the response.

Returns: ListMessagesResponse|error

Sample code:

chat:ListMessagesResponse messages = check chatClient->/spaces/[spaceId]/messages();

get spaces/[spaceId]/messages/[messageId]

GET /spaces/[spaceId]/messages/[messageId]

Returns details about a message.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.

Returns: Message|error

Sample code:

chat:Message message = check chatClient->/spaces/[spaceId]/messages/[messageId]();

patch spaces/[spaceId]/messages/[messageId]

PATCH /spaces/[spaceId]/messages/[messageId]

Updates an existing message.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.
`payload`	`UpdateMessageRequest`	Yes	The updated message fields: `text`, `cardsV2`, `fallbackText`, and `accessoryWidgets`.
`updateMask`	`string`	Yes	The field paths to update, comma-separated (for example, `text,cardsV2`), or `*` to update all supported paths.
`allowMissing`	`boolean?`	No	If `true`, creates the message if it doesn't already exist.

Returns: Message|error

Sample code:

chat:Message updated = check chatClient->/spaces/[spaceId]/messages/[messageId].patch({
    text: "Updated text"
}, updateMask = "text");

delete spaces/[spaceId]/messages/[messageId]

DELETE /spaces/[spaceId]/messages/[messageId]

Deletes a message.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.

Returns: error?

Sample code:

check chatClient->/spaces/[spaceId]/messages/[messageId].delete();

Members

post spaces/[spaceId]/members

POST /spaces/[spaceId]/members

Adds a member to a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`payload`	`Membership`	Yes	The member to add.

Returns: Membership|error

Sample code:

chat:Membership membership = check chatClient->/spaces/[spaceId]/members.post({
    member: {name: "users/[email protected]", 'type: "HUMAN"}
});

get spaces/[spaceId]/members

GET /spaces/[spaceId]/members

Lists memberships in a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`pageSize`	`int?`	No	Maximum number of memberships to return (max 1000).
`pageToken`	`string?`	No	Page token from a previous list request.
`filter`	`string?`	No	A query filter, for example `role = "ROLE_MANAGER"`.
`showGroups`	`boolean?`	No	Whether to include Google Group memberships.
`showInvited`	`boolean?`	No	Whether to include invited memberships.
`useAdminAccess`	`boolean?`	No	Whether to use the caller's Workspace admin privileges for the request.

Returns: ListMembershipsResponse|error

Sample code:

chat:ListMembershipsResponse members = check chatClient->/spaces/[spaceId]/members();

get spaces/[spaceId]/members/[memberId]

GET /spaces/[spaceId]/members/[memberId]

Returns details about a membership.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`memberId`	`string`	Yes	The member resource name.
`useAdminAccess`	`boolean?`	No	Runs the method using the caller's Workspace admin privileges. Not supported for app memberships.

Returns: Membership|error

Sample code:

chat:Membership member = check chatClient->/spaces/[spaceId]/members/[memberId]();

patch spaces/[spaceId]/members/[memberId]

PATCH /spaces/[spaceId]/members/[memberId]

Updates a membership, for example to change a member's role in a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`memberId`	`string`	Yes	The member resource name.
`payload`	`Membership`	Yes	The membership with updated fields.
`updateMask`	`string`	Yes	The field paths to update. Currently only `role` is supported.
`useAdminAccess`	`boolean?`	No	Runs the method using the caller's Workspace admin privileges.

Returns: Membership|error

Sample code:

chat:Membership updated = check chatClient->/spaces/[spaceId]/members/[memberId].patch(
    {role: "ROLE_MANAGER"}, updateMask = "role");

delete spaces/[spaceId]/members/[memberId]

DELETE /spaces/[spaceId]/members/[memberId]

Removes a user or Chat app from a space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`memberId`	`string`	Yes	The member resource name.

Returns: error?

Sample code:

check chatClient->/spaces/[spaceId]/members/[memberId].delete();

Reactions

post spaces/[spaceId]/messages/[messageId]/reactions

POST /spaces/[spaceId]/messages/[messageId]/reactions

Creates a reaction on a message.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.
`payload`	`Reaction`	Yes	The reaction to create, for example `{emoji: {unicode: "👍"}}`.

Returns: Reaction|error

Sample code:

chat:Reaction reaction = check chatClient->/spaces/[spaceId]/messages/[messageId]/reactions.post({
    emoji: {unicode: "👍"}
});

get spaces/[spaceId]/messages/[messageId]/reactions

GET /spaces/[spaceId]/messages/[messageId]/reactions

Lists reactions on a message.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.
`pageSize`	`int?`	No	Maximum number of reactions to return (max 25).
`pageToken`	`string?`	No	Page token from a previous list request.
`filter`	`string?`	No	A query filter, for example by emoji.

Returns: ListReactionsResponse|error

Sample code:

chat:ListReactionsResponse reactions = check chatClient->/spaces/[spaceId]/messages/[messageId]/reactions();

delete spaces/[spaceId]/messages/[messageId]/reactions/[reactionId]

DELETE /spaces/[spaceId]/messages/[messageId]/reactions/[reactionId]

Deletes a reaction from a message.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.
`reactionId`	`string`	Yes	The reaction resource name.

Returns: error?

Sample code:

check chatClient->/spaces/[spaceId]/messages/[messageId]/reactions/[reactionId].delete();

Attachments

post spaces/[spaceId]/attachments/upload

POST /spaces/[spaceId]/attachments:upload

Uploads an attachment to a Google Chat space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The ID of the space that will own the uploaded attachment.
`payload`	`UploadAttachmentRequest`	Yes	`filename` and the raw `mediaBytes` to upload.

Returns: UploadAttachmentResponse|error

Sample code:

chat:UploadAttachmentResponse uploaded = check chatClient->/spaces/[spaceId]/attachments/upload.post({
    filename: "report.pdf",
    mediaBytes: fileBytes
});

get spaces/[spaceId]/messages/[messageId]/attachments/[attachmentId]

GET /spaces/[spaceId]/messages/[messageId]/attachments/[attachmentId]

Gets the metadata of a message attachment.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`messageId`	`string`	Yes	The message resource name.
`attachmentId`	`string`	Yes	The attachment resource name.

Returns: Attachment|error

Sample code:

chat:Attachment attachment = check chatClient->/spaces/[spaceId]/messages/[messageId]/attachments/[attachmentId]();

downloadMedia

Downloads attachment media bytes given its resource name.

Parameters:

Name	Type	Required	Description
`resourceName`	`string`	Yes	The attachment media resource name from a message's `attachment.downloadUri` or `attachment.name`.

Returns: byte[]|error

Sample code:

byte[] mediaBytes = check chatClient->downloadMedia(resourceName);

Space events

get spaces/[spaceId]/spaceEvents/[spaceEventId]

GET /spaces/[spaceId]/spaceEvents/[spaceEventId]

Returns an event from a Google Chat space, from the Workspace Events API.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`spaceEventId`	`string`	Yes	The space event resource name.

Returns: SpaceEvent|error

Sample code:

chat:SpaceEvent event = check chatClient->/spaces/[spaceId]/spaceEvents/[spaceEventId]();

get spaces/[spaceId]/spaceEvents

GET /spaces/[spaceId]/spaceEvents

Lists events from a Google Chat space.

Parameters:

Name	Type	Required	Description
`spaceId`	`string`	Yes	The space resource name.
`filter`	`string`	Yes	An event type filter, for example `eventTypes:"google.workspace.chat.message.v1.created"`.
`pageSize`	`int?`	No	Maximum number of events to return.
`pageToken`	`string?`	No	Page token from a previous list request.

Returns: ListSpaceEventsResponse|error

Sample code:

chat:ListSpaceEventsResponse events = check chatClient->/spaces/[spaceId]/spaceEvents(
    filter = string `eventTypes:"google.workspace.chat.message.v1.created"`);

What's next

Trigger Reference: react to interaction events using the webhook listener.
Example: complete example integrations for the Google Chat connector and trigger.
Setup Guide: create a GCP project and configure the Chat app.

Client​

Configuration​

Initializing the client​

Operations​

Spaces​

Messages​

Members​

Reactions​

Attachments​

Space events​

What's next​

Client

Configuration

Initializing the client

Operations

Spaces

Messages

Members

Reactions

Attachments

Space events

What's next