Overview
You can send text messages to the AI agent programmatically, either by sending events directly or using the convenient sendText
method.
Using sendText Method
The React SDK provides a convenient sendText
method that handles both events for you:
import { useConversation } from "@outspeed/react";
// inside a React component
const conversation = useConversation({});
// Send text and get AI response
await conversation.sendText("What's the weather like?");
// Cancel ongoing response and send new text
await conversation.sendText("What's the weather like?", { cancelOngoing: true });
sendText
will generate a response only if the model is currently not generating anything.
Options
The sendText
method accepts an optional second parameter with these options:
Option | Type | Default | Description |
---|
cancelOngoing | boolean | false | Cancel any ongoing response generation before sending the new text |
Cancel Ongoing Responses
When the AI is generating a response, you can cancel it and send a new message:
// This will cancel any ongoing response and send the new text
await conversation.sendText("Actually, tell me about the weather in Tokyo instead", {
cancelOngoing: true,
});
Using Events
To send a text message, you need to send two events:
// 1. Add text message to conversation context
const messageEvent = {
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [
{
type: "input_text",
text: "What's the weather like?",
},
],
},
};
await conversation.send(JSON.stringify(messageEvent));
// 2. Request AI response
const responseEvent = {
type: "response.create",
};
await conversation.send(JSON.stringify(responseEvent));
Example Usage
function ChatInput() {
const [message, setMessage] = useState("");
const conversation = useConversation({});
// add the logic to start & end a conversation session
const handleSubmit = async (e: FormEvent) => {
e.preventDefault();
if (!message.trim()) return;
try {
await conversation.sendText(message);
setMessage(""); // Clear input after sending
} catch (error) {
console.error("Failed to send message:", error);
}
};
return (
<form onSubmit={handleSubmit}>
<input value={message} onChange={(e) => setMessage(e.target.value)} placeholder="Type a message..." />
<button type="submit">Send</button>
</form>
);
}
Important Notes
Concurrent sendText Calls
By default, sendText
will generate a response only if the model is currently not generating anything.
If you call sendText
while the AI is responding, you have two options:
Option 1: Handle the error (default behavior)
const conversation = useConversation({});
conversation.on("error", (event) => {
if (event.error.code === "conversation_already_has_active_response") {
console.log("AI is currently responding, please wait");
// Show user feedback or queue the message
}
});
Option 2: Cancel ongoing response
// This will cancel the current response and send the new message
await conversation.sendText("New message", { cancelOngoing: true });
Error Response
If you don’t use cancelOngoing: true
, simultaneous calls will fail with this error:
{
"event_id": "b5ea58f4-8dfe-4590-959c-0c85ef108b9b",
"type": "error",
"server_sent": true,
"created_at_": 1756734784.1917815,
"error": {
"type": "invalid_request_error",
"code": "conversation_already_has_active_response",
"message": "Conversation already has an active response",
"param": null,
"event_id": null
}
}