Skip to main content

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
  }
}
I