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

# Send Chat Message

> Send a message to an AI agent and receive a response with optional streaming

## Overview

This endpoint enables text-based conversations with your AI agents. It supports both streaming and non-streaming responses, making it ideal for chatbots, customer support widgets, and interactive applications.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your eigi.ai API key. Must be prefixed with `vk_`.
</ParamField>

## Request Body

<ParamField body="agent_id" type="string" required>
  The unique identifier of the agent to chat with. Example:
  `68ea2517dbb84c09bae1ba0a`
</ParamField>

<ParamField body="message" type="string" required>
  The user's message to send to the agent. Must be between 1 and 4000
  characters. Example: `"Hello, I need help with my account"`
</ParamField>

<ParamField body="session_id" type="string">
  Session ID for continuing a conversation. If not provided, a new session will
  be created. Example: `58a6b549-ef07-4a31-86bc-0eb0e026840a`
</ParamField>

<ParamField body="streaming" type="boolean" default="true">
  Whether to stream the response in real-time or wait for the complete response.

  * `true`: Response streams as it's generated (recommended for chat UIs) -
    `false`: Returns complete response as JSON
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata to attach to the conversation. Useful for tracking user context.

  Example: `{"user_id": "user_123", "source": "website"}`
</ParamField>

## Response

### Streaming Response (streaming=true)

Returns a `text/plain` stream with the agent's response delivered word-by-word.

**Response Headers:**

| Header         | Description                                   |
| -------------- | --------------------------------------------- |
| `X-Session-ID` | The session ID to use for subsequent messages |
| `Content-Type` | `text/plain; charset=utf-8`                   |

**Stream Format:**

The response body contains the text as it's being generated, suitable for displaying in real-time.

### Non-Streaming Response (streaming=false)

<ResponseField name="response" type="string">
  The complete response from the AI agent.
</ResponseField>

<ResponseField name="session_id" type="string">
  The session ID to use for subsequent messages in this conversation.
</ResponseField>

## Examples

### Streaming Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.eigi.ai/v1/public/chat" \
    -H "X-API-Key: vk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "68ea2517dbb84c09bae1ba0a",
      "message": "Hello, how can you help me?",
      "streaming": true
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.eigi.ai/v1/public/chat",
      headers={
          "X-API-Key": "vk_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={
          "agent_id": "68ea2517dbb84c09bae1ba0a",
          "message": "Hello, how can you help me?",
          "streaming": True
      },
      stream=True
  )

  # Get session ID from headers
  session_id = response.headers.get("X-Session-ID")

  # Stream the response
  for chunk in response.iter_content(decode_unicode=True):
      print(chunk, end="", flush=True)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.eigi.ai/v1/public/chat", {
    method: "POST",
    headers: {
      "X-API-Key": "vk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: "68ea2517dbb84c09bae1ba0a",
      message: "Hello, how can you help me?",
      streaming: true,
    }),
  });

  // Get session ID from headers
  const sessionId = response.headers.get("X-Session-ID");

  // Stream the response
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value));
  }
  ```
</CodeGroup>

### Non-Streaming Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.eigi.ai/v1/public/chat" \
    -H "X-API-Key: vk_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "68ea2517dbb84c09bae1ba0a",
      "message": "What are your business hours?",
      "streaming": false
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.eigi.ai/v1/public/chat",
      headers={
          "X-API-Key": "vk_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={
          "agent_id": "68ea2517dbb84c09bae1ba0a",
          "message": "What are your business hours?",
          "streaming": False
      }
  )

  data = response.json()
  print(f"Response: {data['response']}")
  print(f"Session ID: {data['session_id']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.eigi.ai/v1/public/chat", {
    method: "POST",
    headers: {
      "X-API-Key": "vk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent_id: "68ea2517dbb84c09bae1ba0a",
      message: "What are your business hours?",
      streaming: false,
    }),
  });

  const data = await response.json();
  console.log("Response:", data.response);
  console.log("Session ID:", data.session_id);
  ```
</CodeGroup>

### Non-Streaming Response Example

```json theme={null}
{
  "response": "Hello! I'd be happy to help you. Our business hours are Monday through Friday, 9 AM to 6 PM EST. Is there something specific I can assist you with today?",
  "session_id": "58a6b549-ef07-4a31-86bc-0eb0e026840a"
}
```

### Continuing a Conversation

Use the `session_id` from previous responses to maintain conversation context:

```bash cURL theme={null}
curl -X POST "https://api.eigi.ai/v1/public/chat" \
  -H "X-API-Key: vk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "session_id": "58a6b549-ef07-4a31-86bc-0eb0e026840a",
    "message": "What about weekends?",
    "streaming": false
  }'
```

## Error Responses

| Status Code          | Description                                          |
| -------------------- | ---------------------------------------------------- |
| **400 Bad Request**  | Agent has no LLM configuration or message is invalid |
| **401 Unauthorized** | Missing, invalid, inactive, or expired API key       |
| **403 Forbidden**    | API key owner doesn't have access to this agent      |
| **404 Not Found**    | Agent not found                                      |

```json Example Error Response theme={null}
{
  "detail": "Agent does not have LLM configuration"
}
```

## Best Practices

<Tip>
  **Use Streaming for Chat UIs**: Streaming provides a more responsive user
  experience by showing the response as it's generated.
</Tip>

<Tip>
  **Persist Session IDs**: Store session IDs to maintain conversation context
  across multiple messages.
</Tip>

<Tip>
  **Include Metadata**: Use the metadata field to track user context, which can
  help with personalization and analytics.
</Tip>

<Warning>
  Messages are limited to 4000 characters. For longer content, consider breaking
  it into multiple messages.
</Warning>


## OpenAPI

````yaml POST /v1/public/chat
openapi: 3.0.0
info:
  title: eigi.ai API
  description: REST API for managing AI voice agents and conversations
  version: 1.0.0
  contact:
    email: buddy@eigi.ai
    url: https://eigi.ai
servers:
  - url: https://api.eigi.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v1/public/chat:
    post:
      tags:
        - Chat
      summary: Send Chat Message
      description: >-
        Send a message to an AI agent and receive a response with optional
        streaming
      operationId: sendChatMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
            examples:
              streaming:
                summary: Streaming chat request
                value:
                  agent_id: 68ea2517dbb84c09bae1ba0a
                  message: Hello, how can you help me?
                  streaming: true
              non_streaming:
                summary: Non-streaming chat request
                value:
                  agent_id: 68ea2517dbb84c09bae1ba0a
                  message: What are your business hours?
                  streaming: false
              with_session:
                summary: Continue existing conversation
                value:
                  agent_id: 68ea2517dbb84c09bae1ba0a
                  session_id: 58a6b549-ef07-4a31-86bc-0eb0e026840a
                  message: Tell me more about that
                  streaming: false
      responses:
        '200':
          description: >-
            Chat response (JSON for non-streaming, text/plain stream for
            streaming)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatResponse'
            text/plain:
              schema:
                type: string
                description: Streaming response text
          headers:
            X-Session-ID:
              description: Session ID for subsequent messages (streaming mode)
              schema:
                type: string
        '400':
          description: Agent has no LLM configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Access denied to agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ChatRequest:
      type: object
      required:
        - agent_id
        - message
      properties:
        agent_id:
          type: string
          description: The ID of the agent to chat with
          example: 68ea2517dbb84c09bae1ba0a
        message:
          type: string
          minLength: 1
          maxLength: 4000
          description: User message to send to the agent
          example: Hello, how can you help me?
        session_id:
          type: string
          description: Session ID for continuing a conversation (created if not provided)
          example: 58a6b549-ef07-4a31-86bc-0eb0e026840a
        streaming:
          type: boolean
          default: true
          description: >-
            If true, response streams in real-time. If false, returns complete
            JSON response.
        metadata:
          type: object
          description: Additional metadata for the conversation
          example:
            user_id: user_123
            source: website
    ChatResponse:
      type: object
      properties:
        response:
          type: string
          description: The AI agent's response
        session_id:
          type: string
          description: Session ID for subsequent messages
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get your API key from the eigi.ai Dashboard
        under Settings → API Keys.

````