Skip to navigation
Runtime API TemplateChannels

Open a user-delegated agent DM channel

Creates a fresh human-to-agent DM conversation and channel-linked session for the authenticated user on every successful call; it does not reuse an earlier DM. The agentId must exist in the published app configuration, even when a Workspace runtime source is selected; promote a Workspace-only agent before using it here. The response field created is always true. If content is supplied and createOnly is not true, posts the first message as that user.

Authentication

AuthorizationBearer

OAuth/JWT bearer with the ‘runtime’ scope that resolves to a user principal. API keys and agent service tokens are rejected by user-delegated operations.

Headers

X-CES-Workspace-IDstringOptionalformat: "^ws_[A-Za-z0-9_-]+$"
Optional Workspace runtime selector header. If supplied with workspaceId, both values must match.

Query parameters

workspaceIdstringOptionalformat: "^ws_[A-Za-z0-9_-]+$"

Optional Workspace runtime selector for preview or validation calls. If supplied with X-CES-Workspace-ID, both values must match.

Request

This endpoint expects an object.
agentIdstringRequired
contentstringOptional
Optional initial user message.
createOnlybooleanOptionalDefaults to false
When true, open the DM channel without posting content.
messageIdstringOptional

Optional caller-provided idempotency/message id.

attachmentslist of maps from strings to anyOptional
pageContextmap from strings to anyOptional
agentTurnContextobjectOptional

Private, turn-scoped agent orientation for the associated channel message. It is not returned by channel message APIs.

agentSessionContextobjectOptional
Compatibility alias for agentTurnContext. Send only one of these fields.

Response

DM channel created
channelIdstring
sessionIdstring
createdboolean
Always true because this operation creates a fresh conversation.
messageIdstringOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error