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

# Invoke (Stream)

> Send customer input events to a Connectly AI agent and receive a streaming NDJSON response ⌨️

Send customer input to a Connectly AI agent and receive the agent's reply as a streaming NDJSON response. Each line of the response body is a complete, self-contained JSON event. You must [initialise a session](/ai/agent-graph/init-session) and obtain a `sessionId` before calling this endpoint.

<Warning>
  The response body is NDJSON — one JSON object per line. Do not call `response.json()` on the raw response; it will throw a parse error. See [NDJSON streaming](/ai/ndjson-streaming) for the correct approach.
</Warning>

## Endpoint

```json theme={null}
POST https://api.connectly.ai/external/v1/ai/agent_graph/invoke
```

## Request body

<ParamField body="businessId" type="string" required>
  Your Connectly business identifier.
</ParamField>

<ParamField body="clientKey" type="string" required>
  The unique identifier for the customer in this conversation.
</ParamField>

<ParamField body="sessionId" type="string" required>
  The session ID returned by the [init](/ai/agent-graph/init-session) endpoint.
</ParamField>

<ParamField body="agentId" type="string">
  Optional override to target a specific agent within your configuration.
</ParamField>

<ParamField body="inputEvents" type="array" required>
  The list of events to pass to the agent. Include **all** events since the last call — for example, if an automated welcome message was sent, include it as an assistant `messageEvent` so the agent has full context.

  Each element is an object containing exactly one event key:

  <Expandable title="messageEvent">
    A message from the user. Set `role` to `"USER"`.

    The `content` object supports these content types:

    | Key               | Fields                                     | Description                                        |
    | ----------------- | ------------------------------------------ | -------------------------------------------------- |
    | `textContent`     | `text` (string)                            | Plain text message.                                |
    | `audioContent`    | `url` (string)                             | URL to an audio file (mp3, wav, ogg).              |
    | `imageContent`    | `url` (string), `caption` (string)         | URL to an image (jpeg, png) with optional caption. |
    | `locationContent` | `latitude`, `longitude`, `name`, `address` | Geographic location.                               |

    ```json theme={null}
    {
      "messageEvent": {
        "role": "USER",
        "content": {
          "textContent": { "text": "Hi, I need help" }
        }
      }
    }
    ```
  </Expandable>

  <Expandable title="buttonResponseEvent">
    The customer tapped a quick-reply button.

    ```json theme={null}
    {
      "buttonResponseEvent": {
        "id": "button-id",
        "title": "Button Title"
      }
    }
    ```
  </Expandable>

  <Expandable title="listReplyEvent">
    The customer selected an item from a list message.

    ```json theme={null}
    {
      "listReplyEvent": {
        "id": "list-item-id",
        "title": "Option Title",
        "description": "Option Description"
      }
    }
    ```
  </Expandable>

  <Expandable title="filledFormResponseEvent">
    The customer submitted a form.

    ```json theme={null}
    {
      "filledFormResponseEvent": {
        "formData": {
          "name": "João Silva",
          "email": "joao@example.com"
        }
      }
    }
    ```
  </Expandable>

  <Expandable title="storeEvent">
    Associates the conversation with a specific store location.

    ```json theme={null}
    {
      "storeEvent": {
        "storeId": "22473",
        "name": "Store Name",
        "city": "São Paulo",
        "state": "SP"
      }
    }
    ```
  </Expandable>
</ParamField>

## Response

A `200` status with a streaming NDJSON body. Read the response line by line; each line is a self-contained JSON event from the agent.

## Example

```python theme={null}
import requests, json

response = requests.post(
    "https://api.connectly.ai/external/v1/ai/agent_graph/invoke",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "businessId": "your-business-id",
        "clientKey": "customer-123",
        "sessionId": "your-session-id",
        "inputEvents": [{
            "messageEvent": {
                "role": "USER",
                "content": {"textContent": {"text": "Hi, I need help"}}
            }
        }]
    },
    stream=True
)

for raw_line in response.iter_lines():
    if raw_line:
        event = json.loads(raw_line.decode("utf-8"))
        print(event)
```

See [NDJSON streaming](/ai/ndjson-streaming) for a complete parsing guide.