> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outspeed.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Text Messages

> Send text messages to the AI agent programmatically

## 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:

```typescript theme={null}
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 });
```

<Note>`sendText` will generate a response only if the model is currently **not** generating anything.</Note>

## 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:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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

```typescript theme={null}
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)**

```typescript theme={null}
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**

```typescript theme={null}
// 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:

```json theme={null}
{
  "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
  }
}
```