BotService

Chatto exposes this service below /api/connect.

Shared message and enum definitions are documented in Shared Types And Enums.

BotService

Creates and manages bot accounts owned by human users. Bot API keys can call this service with explicit permissions, bounded by their owner’s authority.

ListBotWebhookFailures

List retained failures for an endpoint of a bot you can manage. Returns full records in recording order, oldest first. Expired records are omitted. This history is diagnostic; an empty result does not prove successful delivery.

POST /api/connect/chatto.api.v1.BotService/ListBotWebhookFailures

Input: ListBotWebhookFailuresRequest

Read the retained failure history for a current endpoint.

Field	Type	Description
bot_user_id	string	No field description provided.
webhook_id	string	No field description provided.
page_size	uint32	Maximum records, from 1 to 100. Zero selects 20.
cursor	string	Opaque continuation from the previous response. Bound to viewer and endpoint.

Result: ListBotWebhookFailuresResponse

A bounded page of complete failure records. No per-record hydration is needed.

Field	Type	Description
failures	repeated BotWebhookFailure	No field description provided.
next_cursor	string	Empty at the end. Refresh without a cursor to include newer records.

ListBotOutboundWebhooks

Lists all endpoints, including paused endpoints. Requires bot ownership or bot.manage. Returns the complete bounded collection, so callers do not need batch hydration.

POST /api/connect/chatto.api.v1.BotService/ListBotOutboundWebhooks

Input: ListBotOutboundWebhooksRequest

Read all endpoints for one managed bot. At most 20 endpoints are returned.

Field	Type	Description
bot_user_id	string	Required managed bot ID.

Result: ListBotOutboundWebhooksResponse

All current endpoints, including paused ones.

Field	Type	Description
webhooks	repeated BotOutboundWebhook	Complete collection, ordered by creation time and ID. No pagination is needed.

GetBotOutboundWebhook

Gets one endpoint. Requires bot ownership or bot.manage. Missing endpoints return NOT_FOUND.

POST /api/connect/chatto.api.v1.BotService/GetBotOutboundWebhook

Input: GetBotOutboundWebhookRequest

Read one endpoint belonging to the given managed bot.

Field	Type	Description
bot_user_id	string	Required managed bot ID.
webhook_id	string	Required endpoint ID within this bot.

Result: GetBotOutboundWebhookResponse

Metadata for the requested endpoint.

Field	Type	Description
webhook	BotOutboundWebhook	Endpoint metadata without Authorization or signing credentials.

CreateBotOutboundWebhook

Creates an endpoint and returns its signing secret once. Requires bot ownership or bot.manage.

POST /api/connect/chatto.api.v1.BotService/CreateBotOutboundWebhook

Input: CreateBotOutboundWebhookRequest

Create an independent endpoint with its own signing secret.

Field	Type	Description
bot_user_id	string	Required managed bot ID.
url	string	Absolute HTTPS destination; HTTP is also allowed for localhost names.
authorization	string	Optional complete Authorization header value.
enabled	bool	False creates a paused endpoint.
name	string	Display name, fixed after creation.

Result: CreateBotOutboundWebhookResponse

New endpoint and its show-once request verification secret.

Field	Type	Description
webhook	BotOutboundWebhook	Endpoint metadata without Authorization or signing credentials.
signing_secret	string	Returned only at creation. Configure the receiver with this HMAC secret if it verifies requests.

UpdateBotOutboundWebhook

Edits delivery settings or pauses/resumes delivery. Requires ownership or bot.manage.

POST /api/connect/chatto.api.v1.BotService/UpdateBotOutboundWebhook

Input: UpdateBotOutboundWebhookRequest

Patch delivery settings or pause/resume one endpoint. update_mask selects fields to apply or reset. Name and signing secret stay fixed.

Field	Type	Description
bot_user_id	string	Required managed bot ID.
webhook_id	string	Required endpoint ID within this bot.
enabled	optional bool	Selected enabled state. False pauses delivery; resume accepts only new messages.
url	optional string	Selected new destination. Changing settings cancels queued retries.
authorization	optional string	Selected Authorization header. Absent or empty removes it. Never returned.
update_mask	google.protobuf.FieldMask	Editable fields to apply or reset: enabled, url, authorization. Omit to infer populated fields; * selects all editable fields. An explicit empty mask is invalid. Unselected values are ignored. Selected absent values reset the field to its default, subject to field validation.

Result: UpdateBotOutboundWebhookResponse

Endpoint state after the update.

Field	Type	Description
webhook	BotOutboundWebhook	Endpoint metadata without Authorization or signing credentials.

RevokeBotOutboundWebhook

Permanently revokes an endpoint. Requires ownership or bot.manage.

POST /api/connect/chatto.api.v1.BotService/RevokeBotOutboundWebhook

Input: RevokeBotOutboundWebhookRequest

Revoke one endpoint and cancel its queued retries. In-flight HTTP may finish.

Field	Type	Description
bot_user_id	string	Required managed bot ID.
webhook_id	string	Required endpoint ID within this bot.

Result: RevokeBotOutboundWebhookResponse

Revocation completed, or this endpoint was already absent.

ListBots

Lists bots visible to the authenticated caller.

POST /api/connect/chatto.api.v1.BotService/ListBots

Input: ListBotsRequest

Request bots visible to the caller. Owners see their own bots. Callers with bot.manage or user.manage-accounts see every bot.

Field	Type	Description
search	string	Optional case-insensitive login or display-name search.
page	PageRequest	Defaults to 20 results when absent or limit is zero. Maximum: 100.

Result: ListBotsResponse

Page of visible bots.

Field	Type	Description
bots	repeated Bot	Visible bots by case-insensitive login, then user ID, in ascending order.
page	PageInfo	Page metadata.

GetBot

Gets one visible bot. Returns NOT_FOUND for an unknown bot. Returns PERMISSION_DENIED when the caller is not the owner and has neither bot.manage nor user.manage-accounts.

POST /api/connect/chatto.api.v1.BotService/GetBot

Input: GetBotRequest

Request one bot by stable user ID.

Field	Type	Description
bot_user_id	string	Required bot user ID.

Result: GetBotResponse

Response containing one bot.

Field	Type	Description
bot	Bot	Requested bot.

BatchGetBots

Gets several visible bots. Missing and inaccessible bots are omitted.

POST /api/connect/chatto.api.v1.BotService/BatchGetBots

Input: BatchGetBotsRequest

Request several bots by stable user ID.

Field	Type	Description
bot_user_ids	repeated string	Required bot user IDs. Missing or inaccessible bots are omitted.

Result: BatchGetBotsResponse

Response containing accessible bots in first-seen request order.

Field	Type	Description
bots	repeated Bot	Found bots.

CreateBot

Creates a bot owned by the human caller or a bot caller’s human owner. Requires bot.create. The new bot starts without permission grants.

POST /api/connect/chatto.api.v1.BotService/CreateBot

Input: CreateBotRequest

Request creation of a bot owned by the human caller or a bot caller’s human owner.

Field	Type	Description
login	string	Bot login. Uses the same username rules as a human account.
display_name	string	Public display name.
api_key_name	optional string	Optional name for the initial API key. Defaults to “Default key”.

Result: CreateBotResponse

Result of creating a bot. api_key is shown once and cannot be retrieved.

Field	Type	Description
bot	Bot	Created bot.
api_key	string	Newly issued API key.
api_key_metadata	BotApiKey	Safe metadata for the newly issued API key.

DeleteBot

Deletes a bot and invalidates all of its API keys.

POST /api/connect/chatto.api.v1.BotService/DeleteBot

Input: DeleteBotRequest

Request deletion of a bot account.

Field	Type	Description
bot_user_id	string	Required bot user ID.

Result: DeleteBotResponse

Result of deleting a bot account.

Field	Type	Description
deleted	bool	True when the bot was deleted.

CreateBotApiKey

Creates one named API key. A bot can have at most 20 active API keys. Requires bot ownership or bot.manage. The key uses the target bot’s authority, which can exceed the caller’s authority.

POST /api/connect/chatto.api.v1.BotService/CreateBotApiKey

Input: CreateBotApiKeyRequest

Request creation of one named API key for a bot.

Field	Type	Description
bot_user_id	string	Required bot user ID.
name	string	Required manager-defined name. Names do not need to be unique.

Result: CreateBotApiKeyResponse

Result of creating one API key. api_key is shown once and cannot be retrieved later.

Field	Type	Description
bot	Bot	Updated bot metadata.
api_key	string	Newly issued API key.
api_key_metadata	BotApiKey	Safe metadata for the newly issued API key.

RevokeBotApiKey

Revokes one API key without changing other active keys.

POST /api/connect/chatto.api.v1.BotService/RevokeBotApiKey

Input: RevokeBotApiKeyRequest

Request irreversible revocation of one bot API key.

Field	Type	Description
bot_user_id	string	Required bot user ID.
key_id	string	Required API-key credential ID.

Result: RevokeBotApiKeyResponse

Result of revoking one bot API key.

Field	Type	Description
bot	Bot	Updated bot metadata.

CreateBotIncomingWebhook

Creates a named incoming webhook. A bot can have at most 20 active incoming webhooks.

POST /api/connect/chatto.api.v1.BotService/CreateBotIncomingWebhook

Input: CreateBotIncomingWebhookRequest

Request creation of one named incoming webhook for a bot.

Field	Type	Description
bot_user_id	string	Required bot user ID.
name	string	Required manager-defined name. Names do not need to be unique.

Result: CreateBotIncomingWebhookResponse

Result of creating an incoming webhook. webhook_url is shown once and cannot be retrieved later.

Field	Type	Description
bot	Bot	Updated bot metadata.
webhook_url	string	Newly issued incoming webhook URL.

RevokeBotIncomingWebhook

Revokes one incoming webhook without changing other webhooks.

POST /api/connect/chatto.api.v1.BotService/RevokeBotIncomingWebhook

Input: RevokeBotIncomingWebhookRequest

Request irreversible revocation of one incoming webhook credential.

Field	Type	Description
bot_user_id	string	Required bot user ID.
webhook_id	string	Required webhook credential ID.

Result: RevokeBotIncomingWebhookResponse

Result of revoking an incoming webhook.

Field	Type	Description
bot	Bot	Updated bot metadata.

ReassignBotOwner

Reassigns a bot to another active human owner. Requires bot.manage. The current API keys and configured permission allowlist remain unchanged, while effective permissions immediately use the new owner’s ceiling.

POST /api/connect/chatto.api.v1.BotService/ReassignBotOwner

Input: ReassignBotOwnerRequest

Request an administrative reassignment of a bot to another human owner.

Field	Type	Description
bot_user_id	string	Required bot user ID.
owner_user_id	string	Required user ID of the new human owner.

Result: ReassignBotOwnerResponse

Result of reassigning a bot owner. The bot’s API keys and configured permission allowlist are unchanged.

Field	Type	Description
bot	Bot	Reassigned bot.