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

# Stream Conversation AI Agent Response (SSE)

⚠️ This is a streaming endpoint using [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events).

Opens a live SSE stream to receive real-time response messages from the conversational agent after sending a message.

Use the temporary token received from `/generate_secret` or `/get_inference` as applicable to authenticate the stream.

The stream sends `event.data` messages that include control signals or agent-generated content.

***

## 1. Connection Closing

* `close_connection`/`[DONE]`: Indicates the normal end of the stream. The client **must close** the `EventSource` connection.

***

## 2. Stream Continuation

* `call_again`: Indicates a tool/function call occurred. You've to set your message loading state to true and new message chunks will be sent in the stream.

***

## 3. Error / Restriction Signals

These indicate problems or user restrictions. In all cases, the client must close the connection.

* `no_message_found`: The agent was unable to generate a response as no user message corresponding to request found.
* `close_connection_incomplete_content`: AI model exceeded its response context window.
* `close_connection_incomplete_tool_calls`: Context overflow occurred while generating tool call arguments.
* `close_connection_incomplete_request`: Context overflow occurred while generating response.
* `__ERROR__: ....`: An error occurred while processing the request.
* `[FROZEN]` / `[BLACKLISTED]`: User access restrictions triggered.

***

## 4. AI Agent Response Content

* JSON payloads: Contain AI Agent Response message content. When streaming is **ON you will receive message chunks**, and when streaming is **OFF you will get the full response in a single JSON payload**.

**When Streaming is ON:**

```txt theme={null}
id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": "How"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": " can"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": " I"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": " assist"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": " you"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": " today"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": "?"}

id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"signal": "close_connection", "new_message_time": "2025-09-04T08:55:06.298621", "new_message_id": "44cabb53-1253-46db-8c77-d36fa098773f"}

data: [DONE]
```

When Streaming is OFF:

```txt theme={null}
id: 725e1f05-6142-467e-bdec-47862d50da79
data: {"content": "How can I assist you today?"}

data: {"signal": "close_connection", "new_message_time": "2025-09-04T08:55:06.298621", "new_message_id": "44cabb53-1253-46db-8c77-d36fa098773f"}

data: [DONE]
```

Example Implementation

```js theme={null}
const displayNewMessageHandler = (id, message) => {
  setConversationMessages((prev) => {
    // set your messages state here
    const lastMessage = prev[prev.length - 1];
    if (lastMessage.role === 'assistant' && lastMessage.id === id) {
      // same id -> chunks of message is to be appended
      // last message is assistant and has the same token -> chunks of message is to be appended
      const updatedData = [...prev];
      updatedData[prev.length - 1] = {
        ...lastMessage,
        content: lastMessage.content + message,
      };
      return updatedData;
    } else {
      // new assistant message
      const newMessage = { role: 'assistant', content: message, time: new Date().toLocaleString('en-IN'), id: id };
      return [...prev, newMessage];
    }
  });

  // you have to save the conversationMessages to local storage or any other persistent storage, chatzy AI doesn't expose any API to fetch conversation history
};

const callSourceHandler = (token) => {
  // token is the temp token retrieved by `/get_inference`
  const source = new EventSource(`https://backend-1.chatzy.ai/get-response?token=${token}`);

  source.onmessage = (event) => {
    const id = event.lastEventId;

    if (event.data === '[DONE]') {
      // End of stream
      source.close();
    } else if (event.data === 'no_message_found') {
      source.close();
    } else if (['[FROZEN]', '[BLACKLISTED]'].includes(event.data)) {
      source.close();
    } else if (event.data.includes('__ERROR__')) {
      const errorMessage = event.data.replace('__ERROR__:', '');
      console.error('Error occurred while processing the request:', errorMessage);
      source.close();
    } else {
      let dataObject;
      try {
        dataObject = JSON.parse(event.data);
      } catch {
        // console.error('Error parsing JSON data:', event.data);
      }

      if (dataObject?.content) {
        displayNewMessageHandler(id, dataObject.content);
      } else if (dataObject?.signal === 'close_connection') {
        source.close();
      } else if (dataObject?.signal === 'call_again') {
        // Tool call executed
        // show your message loading
      } else if (dataObject?.signal === 'close_connection_incomplete_content') {
        source.close();
        // show error message to user
      } else if (dataObject?.signal === 'close_connection_incomplete_tool_calls') {
        source.close();
        // show error message to user
      } else if (dataObject?.signal === 'close_connection_incomplete_request') {
        source.close();
        // show error message to user
      }
    }
  };

  source.onerror = function (error) {
    source.close();
    console.error(`EventSource failed:`, error);
  };
};
```


## OpenAPI

````yaml get /get-response
openapi: 3.0.0
info:
  title: Chatzy AI API
  version: 1.0.0
  description: >-
    Chatzy AI REST API for messaging, contact conversations, and agent
    interactions.
  contact:
    name: Chatzy
    url: https://chatzy.ai
    email: support@chatzy.ai
servers:
  - url: https://vevdoh3hve.execute-api.us-east-1.amazonaws.com/prod
    description: Production Server
security: []
tags:
  - name: Authentication
    description: Authentication to access the API
  - name: Contact Conversations
    description: Get contact conversations
  - name: Conversational AI Agent Interactions
    description: Interact with the conversational AI agent
  - name: Authorized iframe Access
    description: APIs for authorized iframe access
paths:
  /get-response:
    get:
      tags:
        - Conversational AI Agent Interactions
      summary: Stream Conversation AI Agent Response (SSE)
      parameters:
        - name: token
          in: query
          required: true
          description: >-
            **Temporary access token** used to authenticate the Server-Sent
            Events (SSE) stream.


            This token is obtained from the `/generate_secret` endpoint and also
            after sending a message to the AI agent via `/get_inference`.


            Pass it as a query parameter like this:


            ```

            /get-response?token=YOUR_TEMP_TOKEN

            ```


            If the token is missing or invalid, the server will respond with a
            `401 Unauthorized` error.
          schema:
            type: string
            example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
      responses:
        '200':
          description: >-
            SSE stream opened. Messages will be sent continuously as
            `text/event-stream`.
          content:
            text/event-stream:
              schema:
                type: string
                example: |+
                  data: {"content": "How"}

                  data: {"content": " can"}

                  data: {"content": " I"}

                  data: {"content": " assist"}

                  data: {"content": " you"}

                  data: {"content": " today"}

                  data: {"content": "?"}

                  data: close_connection

      servers:
        - url: https://backend-1.chatzy.ai
          description: SSE Streaming Host

````