Invoke (Stream) - Connectly

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 and obtain a sessionId before calling this endpoint.

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 for the correct approach.

Endpoint

POST https://api.connectly.ai/external/v1/ai/agent_graph/invoke

Request body

businessId

string

required

Your Connectly business identifier.

clientKey

string

required

The unique identifier for the customer in this conversation.

sessionId

string

required

The session ID returned by the init endpoint.

agentId

string

Optional override to target a specific agent within your configuration.

inputEvents

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:

Show 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.

{
  "messageEvent": {
    "role": "USER",
    "content": {
      "textContent": { "text": "Hi, I need help" }
    }
  }
}

Show buttonResponseEvent

The customer tapped a quick-reply button.

{
  "buttonResponseEvent": {
    "id": "button-id",
    "title": "Button Title"
  }
}

Show listReplyEvent

The customer selected an item from a list message.

{
  "listReplyEvent": {
    "id": "list-item-id",
    "title": "Option Title",
    "description": "Option Description"
  }
}

Show filledFormResponseEvent

The customer submitted a form.

{
  "filledFormResponseEvent": {
    "formData": {
      "name": "João Silva",
      "email": "joao@example.com"
    }
  }
}

Show storeEvent

Associates the conversation with a specific store location.

{
  "storeEvent": {
    "storeId": "22473",
    "name": "Store Name",
    "city": "São Paulo",
    "state": "SP"
  }
}

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

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 for a complete parsing guide.

​Endpoint

​Request body

​Response

​Example

Endpoint

Request body

Response

Example