Send Event

Send various types of events to channels, including streaming text messages and custom events

POST /event

Try it

Start Streaming Text Message

curl -X POST "http://localhost:5001/event" \
  -H "Content-Type: application/json" \
  -d '{
    "client_msg_no": "msg_001_stream_start",
    "channel_id": "group_ai_chat",
    "channel_type": 2,
    "from_uid": "ai_assistant",
    "event": {
      "type": "___TextMessageStart",
      "data": "{\"type\":1,\"content\":\"Starting AI response...\"}"
    }
  }'

Success Response

{
  "status": "ok"
}

Overview

Send various types of events to channels, including streaming text messages and custom events. Supports AG-UI protocol events for real-time streaming communication.

Query Parameters

force · string · default: "0"

Force end existing streams in the channel before starting a new one

• 0 - Do not force end
• 1 - Force end existing streams

Request Body

Required Parameters

client_msg_no · string · required

Client message number - must be unique and not repeated. Used to identify and track the message/stream. For streaming messages, all events in the same stream should use the same client_msg_no. UUID format is recommended.

channel_id · string · required

Target channel ID where the event will be sent. For person channels, this should be the target user ID. For group channels, this should be the group ID.

channel_type · integer · required

Channel type

• 1 - Person channel
• 2 - Group channel

event · object · required

Event object

Show event fields

event.type · string · required

Event type - supports AG-UI protocol events and custom events

AG-UI Protocol Events:

• ___TextMessageStart - Initiates a streaming text message session
• ___TextMessageContent - Sends content chunks during streaming
• ___TextMessageEnd - Terminates a streaming text message session
• ___ToolCallStart - Begins a tool/function call event
• ___ToolCallArgs - Sends arguments for tool calls
• ___ToolCallEnd - Ends a tool call event
• ___ToolCallResult - Returns results from tool execution

Custom Events: Any string not starting with ___ is treated as a custom event type

event.id · string

Event ID (optional, auto-generated for some event types)

event.timestamp · integer

Event timestamp (optional, Unix timestamp in milliseconds)

event.data · string

Event data content. The format depends on the event type:

For Text Message Events:

• ___TextMessageStart - Initial message content or metadata
• ___TextMessageContent - Text chunk for streaming
• ___TextMessageEnd - Final content or completion marker

For Tool Call Events:

• ___ToolCallStart - Tool name or metadata
• ___ToolCallArgs - JSON string with function arguments
• ___ToolCallEnd - Completion status
• ___ToolCallResult - JSON string with execution results

For Custom Events: Any string data relevant to your application

Optional Parameters

from_uid · string

Sender user ID. If not provided or empty, defaults to the system UID. This identifies who is sending the event.

Start Streaming Text Message

curl -X POST "http://localhost:5001/event" \
  -H "Content-Type: application/json" \
  -d '{
    "client_msg_no": "msg_001_stream_start",
    "channel_id": "group_ai_chat",
    "channel_type": 2,
    "from_uid": "ai_assistant",
    "event": {
      "type": "___TextMessageStart",
      "data": "{\"type\":1,\"content\":\"Starting AI response...\"}"
    }
  }'

Success Response

{
  "status": "ok"
}

Response Fields

status · string · required

Operation status, returns "ok" on success

Status Codes

Status Code	Description
200	Event sent successfully
400	Bad request - invalid parameters or event data
500	Internal server error

Streaming Message Flow

Streaming Message Process

1. Start Stream: Send ___TextMessageStart event to initiate a stream
2. Send Content: Send multiple ___TextMessageContent events with message chunks
3. End Stream: Send ___TextMessageEnd event to close the stream

Important Notes

• The same client_msg_no must be used for all events in a streaming session
• Only one stream can be active per channel unless force=1 is used
• For person channels, the system automatically handles fake channel ID generation
• Events are automatically routed to the appropriate cluster node

Event Types

AG-UI Protocol Events

AG-UI protocol events enable real-time streaming communication for AI applications:

Event Type	Purpose	Data Format
___TextMessageStart	Initiates a streaming text message session	Initial content or metadata
___TextMessageContent	Sends content chunks during streaming	Text chunk content
___TextMessageEnd	Terminates a streaming text message session	Completion marker
___ToolCallStart	Begins a tool/function call event	Tool name or metadata
___ToolCallArgs	Sends arguments for tool calls	JSON formatted arguments
___ToolCallEnd	Ends a tool call event	Completion status
___ToolCallResult	Returns results from tool execution	JSON formatted results

Custom Events

Any event type not starting with ___ is treated as a custom event, useful for:

• User status updates
• System notifications
• Business logic events
• Application-specific interactions

Use Cases

AI Chatbot

# Simulate AI typing effect
curl -X POST "/event" -d '{
  "client_msg_no": "ai_response_001",
  "channel_id": "user_123",
  "channel_type": 1,
  "from_uid": "ai_bot",
  "event": {
    "type": "___TextMessageStart",
    "data": "Thinking..."
  }
}'

# Gradually send response content
curl -X POST "/event" -d '{
  "client_msg_no": "ai_response_001",
  "channel_id": "user_123", 
  "channel_type": 1,
  "from_uid": "ai_bot",
  "event": {
    "type": "___TextMessageContent",
    "data": "Based on your question, I recommend..."
  }
}'

Real-time Collaboration

# Document editing status
curl -X POST "/event" -d '{
  "client_msg_no": "doc_edit_001",
  "channel_id": "doc_room_456",
  "channel_type": 2,
  "from_uid": "user_789",
  "event": {
    "type": "document_editing",
    "data": "{\"action\": \"start_edit\", \"section\": \"paragraph_1\"}"
  }
}'

System Notifications

# User online notification
curl -X POST "/event" -d '{
  "client_msg_no": "status_update_001",
  "channel_id": "group_general",
  "channel_type": 2,
  "from_uid": "system",
  "event": {
    "type": "user_online",
    "timestamp": 1640995200000,
    "data": "{\"user_id\": \"user_123\", \"status\": \"online\"}"
  }
}'

Best Practices

1. Unique Identification: Use UUID format for client_msg_no to ensure uniqueness
2. Stream Management: Close unused streams promptly to avoid resource waste
3. Error Handling: Handle stream conflicts and send failures
4. Permission Verification: Ensure sender has channel send permissions
5. Data Format: Use JSON format strings for complex data
6. Performance Optimization: Control streaming message send frequency reasonably

Error Handling

Common Errors

Error	Cause	Solution
Event type cannot be empty	No event.type provided	Ensure valid event type is provided
Stream already running in channel	Trying to start new stream when one is active	Use force=1 or wait for existing stream to end
Stream does not exist	Trying to send content to non-existent stream	Check if stream was created correctly
Stream is already closed	Sending content to closed stream	Start a new stream

Retry Mechanism

For temporary errors, implement exponential backoff retry mechanism:

async function sendEventWithRetry(eventData, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch('/event', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(eventData)
      });
      
      if (response.ok) return await response.json();
      
      if (response.status >= 400 && response.status < 500) {
        // Client error, don't retry
        throw new Error(`Client error: ${response.status}`);
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }
}