Coze icon

Coze

Interact with Coze AI platform
Join our community

Actions12

Overview

The node integrates with the Coze AI platform to create and manage chat conversations using intelligent agents (bots) within specified workspaces. The "创建对话" (Create Chat) operation allows users to initiate a new conversation by sending a message to a selected bot, optionally including historical messages, custom variables, metadata, and additional parameters.

This node is beneficial in scenarios where automated conversational AI interactions are needed, such as customer support bots, virtual assistants, or interactive chat services embedded in applications. For example, a user can start a conversation with a sales bot to get product recommendations or with a support bot to troubleshoot issues.

Properties

Name Meaning
Authentication Method of authentication to use: "Service Token" or "OAuth2".
Workspace Name or ID The workspace containing the bot. Select from available workspaces or specify an ID.
智能体 ID（botId） Name or ID The ID of the intelligent agent (bot) to converse with. Select from bots available in the chosen workspace or specify an ID.
用户 ID Unique identifier representing the end user initiating the conversation.
消息内容 (Content) The current input message from the user to send to the bot.
会话 ID（conversationId） Optional ID specifying which conversation session this message belongs to, enabling continuation of existing conversations.
附加消息 (additionalMessages) Optional JSON array of historical messages to provide context for the conversation, e.g., [{"role": "user", "content": "你好"}].
自定义变量 (customVariables) Optional JSON object string defining variables used in the bot's prompt template.
自动保存历史记录 (autoSaveHistory) Boolean flag indicating whether to save the current conversation history; defaults to true.
元数据 (metaData) Optional JSON object string containing additional business-related key-value pairs passed along with the conversation but not returned in message lists.
附加参数 (extraParams) Optional JSON object string for extra parameters such as geolocation data.
快捷指令 (shortcutCommand) Optional JSON object string specifying shortcut command information.
自定义参数 (parameters) Optional JSON object string for custom parameters passed to the conversation flow.
启用卡片返回 (enableCard) Boolean flag to enable returning content in card format instead of plain text; defaults to false.

Output

The node outputs a JSON array where each item represents the response from the Coze AI platform after creating the chat conversation or sending the message. The output typically includes details about the conversation state, the bot's reply, and any relevant metadata.

If enabled, the node can return the content in a card format, which structures the response into rich UI elements rather than plain text.

No binary data output is indicated for this operation.

Dependencies

  • Requires access to the Coze AI platform API at https://api.coze.cn.
  • Needs either a service token or OAuth2 credentials configured in n8n for authentication.
  • The node dynamically loads options for workspaces and bots via API calls, so network connectivity and valid credentials are necessary.
  • No other external dependencies are indicated.

Troubleshooting

  • Common Issues:

    • Invalid or expired authentication tokens will cause request failures.
    • Specifying incorrect workspace or bot IDs may result in errors or empty responses.
    • Malformed JSON strings in properties like additionalMessages, customVariables, or metaData can cause parsing errors.
    • Omitting required fields such as userId or content will likely lead to validation errors.

  • Error Messages:

    • Errors related to authentication failure suggest checking and refreshing API credentials.
    • "Workspace not found" or "Bot not found" errors indicate invalid selection or missing permissions.
    • JSON parsing errors recommend verifying the syntax of JSON inputs.

  • Resolution Tips:

    • Ensure all required fields are provided and correctly formatted.
    • Use the built-in option loaders to select valid workspace and bot IDs.
    • Validate JSON strings with online tools before inputting.
    • Confirm that the API credentials have appropriate scopes and are active.

Links and References

Discussion