useChatBot
Register a bot identity for posting into chat rooms
useChatBot registers a bot identity (a botId, display name and icon
as a URL or base64 data URI) that your product can post under in chat rooms.
data resolves to "New" or "Exists", exactly like
useChatRoom. The result is cached per botId,
so multiple components mounting the same bot share one registration, and
re-registering an existing bot simply resolves "Exists".
Chat is host-only. Running standalone the query result settles in the error
state with HostUnavailableError; gate bot UI with
useIsHost.
A typical bot registers its identity, posts messages carrying action
buttons, and reacts to the resulting ActionTriggered events via
useChatActions.
Usage
import { useChatBot, useSendChatMessage } from "@use-truapi/react";
function DiceBot({ roomId }: { roomId: string }) {
const { data: status, error } = useChatBot({
botId: "dice-bot",
name: "Dice",
icon: "https://example.com/dice.png",
});
const { send } = useSendChatMessage(roomId);
function offerRoll() {
void send({
tag: "Actions",
value: {
text: "Feeling lucky?",
actions: [{ actionId: "roll", title: "Roll the dice" }],
layout: "Column",
},
}).catch(() => {});
}
if (error) return <p>Chat unavailable: {error.message}</p>;
return (
<button type="button" onClick={offerRoll} disabled={status === undefined}>
Post roll prompt
</button>
);
}<script setup lang="ts">
import { useChatBot, useSendChatMessage } from "@use-truapi/vue";
const props = defineProps<{ roomId: string }>();
const { data: status, error } = useChatBot({
botId: "dice-bot",
name: "Dice",
icon: "https://example.com/dice.png",
});
const { send } = useSendChatMessage(() => props.roomId);
function offerRoll() {
void send({
tag: "Actions",
value: {
text: "Feeling lucky?",
actions: [{ actionId: "roll", title: "Roll the dice" }],
layout: "Column",
},
}).catch(() => {});
}
</script>
<template>
<p v-if="error">Chat unavailable: {{ error.message }}</p>
<button v-else type="button" :disabled="status === undefined" @click="offerRoll">
Post roll prompt
</button>
</template>See useChatActions for the other half of
this bot: reacting when a user presses the button.
See also
useChatRoomregisters the room the bot posts into.useSendChatMessageposts messages, including action buttons.
API reference
React
function useChatBot(bot, options?): UseQueryResult<"New" | "Exists", Error>;Register a bot identity for posting into rooms.
Parameters
| Parameter | Type |
|---|---|
bot | { botId: string; icon: string; name: string; } |
bot.botId | string |
bot.icon? | string |
bot.name? | string |
options? | { query?: QueryOptions<"New" | "Exists">; } |
options.query? | QueryOptions<"New" | "Exists"> |
Returns
UseQueryResult<"New" | "Exists", Error>
Vue
function useChatBot(bot, options?): QueryResult<"New" | "Exists">;Register a bot identity for posting into rooms.
Parameters
| Parameter | Type |
|---|---|
bot | { botId: string; icon: string; name: string; } |
bot.botId | string |
bot.icon? | string |
bot.name? | string |
options? | { query?: QueryOptions<"New" | "Exists">; } |
options.query? | QueryOptions<"New" | "Exists"> |
Returns
QueryResult<"New" | "Exists">