Invoke (Stream)

POST

external

agent_graph

invoke

Invoke (Stream)

curl --request POST \
  --url https://api.example.com/external/v1/ai/agent_graph/invoke \
  --header 'Content-Type: application/json' \
  --data '
{
  "businessId": "<string>",
  "clientKey": "<string>",
  "sessionId": "<string>",
  "agentId": "<string>",
  "inputEvents": [
    {}
  ]
}
'

import requests

url = "https://api.example.com/external/v1/ai/agent_graph/invoke"

payload = {
    "businessId": "<string>",
    "clientKey": "<string>",
    "sessionId": "<string>",
    "agentId": "<string>",
    "inputEvents": [{}]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    businessId: '<string>',
    clientKey: '<string>',
    sessionId: '<string>',
    agentId: '<string>',
    inputEvents: [{}]
  })
};

fetch('https://api.example.com/external/v1/ai/agent_graph/invoke', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/external/v1/ai/agent_graph/invoke",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'businessId' => '<string>',
    'clientKey' => '<string>',
    'sessionId' => '<string>',
    'agentId' => '<string>',
    'inputEvents' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/external/v1/ai/agent_graph/invoke"

	payload := strings.NewReader("{\n  \"businessId\": \"<string>\",\n  \"clientKey\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"agentId\": \"<string>\",\n  \"inputEvents\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/external/v1/ai/agent_graph/invoke")
  .header("Content-Type", "application/json")
  .body("{\n  \"businessId\": \"<string>\",\n  \"clientKey\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"agentId\": \"<string>\",\n  \"inputEvents\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/external/v1/ai/agent_graph/invoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"businessId\": \"<string>\",\n  \"clientKey\": \"<string>\",\n  \"sessionId\": \"<string>\",\n  \"agentId\": \"<string>\",\n  \"inputEvents\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

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

string

required

Your Connectly business identifier.

string

required

The unique identifier for the customer in this conversation.

string

required

The session ID returned by the init endpoint.

string

Optional override to target a specific agent within your configuration.

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.

Init Session

Invoke (Sync)

Get Started

Campaigns

Messaging

Webhooks

Assets

AI Features

Analytics

Business Management

Integrations

Resources

Endpoint

Request body

Response

Example

​Endpoint

​Request body

​Response

​Example

Endpoint

Request body

Response

Example