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:
OptionTypeDefaultDescription
cancelOngoingbooleanfalseCancel 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
  }
}