Events and business tools

Events tell the AI what happened. Tools let the AI query or execute capabilities in your system.

Events

Create and enable an event in the console, including its code, description, parameters, and respond or record behavior. Then submit it through the chat API. Ordinary text uses type: message and does not require a custom event definition.

Three tool execution modes

Configure the tool name, description, parameters, invocation conditions, and delivery modes in the console. Gift sending and balance lookup are examples; the platform does not implement your business operations for you.

delivery	Behavior
["CALLBACK"]	Invoke the tool URL synchronously, then generate the reply using the result. Query tools only support this mode
["MESSAGE"]	Plan during generation; after successful reply commit, deliver text, assets, and actions in that order through the message callback for execution
["CALLBACK","MESSAGE"]	Execute synchronously, then send a display-only action message after success. Do not execute the display message again

Synchronous tool URLs are stored in tool configuration and share the workspace's TOOL signing configuration. They must have the same origin as the verified tool URL (scheme, hostname, port). Message-only execution requires a message callback but no tool URL.

Synchronous tool request

The platform POSTs to the configured URL with OC-Event-Type: tool.execute. OC-Event-Id and Idempotency-Key equal callId. Use the callback signing format with the tool callback secret.

{"type":"action","context":{"workspaceId":"1","conversationId":"456","personaId":"11","personaUid":"anchor-001","userId":"u-1001"},"action":{"callId":"stable-call-id","code":"send_gift","name":"Send gift","mode":"EXECUTE","arguments":{"giftId":"rose","count":1}}}

Action field	Meaning
callId	Stable tool call identifier for execution deduplication
code / name	Configured tool identifier and display name
mode	EXECUTE performs the operation; NOTIFY displays it only
arguments	Business parameters validated against the definition
result	Display messages carry the completed synchronous result

Business result

Return top-level business JSON in an HTTP 2xx response:

{"status":"SUCCEEDED","data":{"giftId":"rose","count":1}}

{"status":"FAILED","message":"Insufficient balance"}

For uncertainty, return {"status":"UNKNOWN","message":"Reconcile the original transaction"}. Your system must validate permissions, balances, and other constraints, and persist idempotency IDs together with business outcomes.

Respond within the configured 1–30-second timeout and 8,000 UTF-8 bytes. Non-2xx responses, invalid statuses, and timeouts are treated as unknown. Unknown synchronous business operations are not directly retried automatically; they restrict further use of that tool in the conversation pending reconciliation. Queries can be repeated.

Delivery through messages

The message callback uses OC-Event-Type: chat.message:

{"actionId":"125","conversationId":"456","messageId":"791","type":"action","context":{"workspaceId":"1","conversationId":"456","personaId":"11","personaUid":"anchor-001","userId":"u-1001"},"action":{"callId":"stable-call-id","code":"send_gift","name":"Send gift","mode":"EXECUTE","arguments":{"giftId":"rose","count":1}}}

For EXECUTE, return the business result above; message retry rules apply. For NOTIFY, accept reliably and return 2xx without executing again; action.result contains the earlier synchronous outcome.

Actions in the console test inbox return a simulated result with simulated: true; no real business execution occurs there. Validate the complete flow through the public API and your receiving system.