Create conversation

veryfront__create_conversation

Requires project.conversations.create.

Access

No external-service connection is required. Use a Veryfront credential with access to the requested resources.

Call type: Can change resources.

Arguments

FieldTypeRequiredDescription and constraints
project_referencestringNoProject ID or slug; required unless the token is project-scoped. Create the conversation optionally with a first user message and an idempotency key. Minimum length: 1.
typestringNoProvide the type. Values: "chat", "default_chat", "plan", "research", "agent_task", "support"; see schema for the complete list.
titlestringNoShort human-readable title for the record. Maximum length: 500.
idempotency_keystringNoRetrying with the same key and the same arguments returns the same conversation; different arguments fail with an idempotency conflict. Minimum length: 1. Maximum length: 255.
metadataobjectNoAdditional structured metadata for the request.
initial_messageobjectNoA first user message stored atomically with the conversation, as on REST POST /conversations.

Example request

Send this JSON-RPC request through an initialized MCP client. Replace sample identifiers and values before calling the tool. See MCP client setup.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "veryfront__create_conversation",
    "arguments": {}
  }
}

Result

The published output shape is summarized below. Inspect both the MCP response content and isError when handling a call.

FieldTypeRequiredDescription and constraints
idstringYesConversation identifier.
project_idstring or nullNoProject identifier that owns the conversation, or null for global/system conversations.
responding_agent_idstring or nullNoAgent currently responding in the conversation, or null when no agent has responded. Default: null.
typestringYesConversation type, such as agent, support, or workflow conversation. Values: "chat", "default_chat", "plan", "research", "agent_task", "support"; see schema for the complete list.
titlestring or nullNoHuman-readable conversation title.
summarystring or nullNoShort summary of the conversation state or topic.
statusstringYesLifecycle status of the conversation. Values: "active", "archived", "deleted".
current_nodestring or nullNoSelected conversation message node for the active branch, or null when no message is selected.
message_countnumberYesNumber of persisted messages in the conversation.
last_message_atstring or nullNoTimestamp of the most recent message in the conversation.
metadataobject or nullNoAdditional machine-readable conversation metadata.
created_bystring or nullYesUser or actor identifier that created the conversation.
archived_atstring or nullNoTimestamp when the conversation was archived, or null when active.
created_atstringYesTimestamp when the conversation was created.
updated_atstringYesTimestamp when the conversation was last updated.
participantsobject[]NoParticipants of the conversation. Empty on the confirmation body of delete_conversation. Default: [].
initial_message_idstring or nullYesThe first message stored with the conversation, when initial_message was sent.

Full schemas

json
{
  "type": "object",
  "properties": {
    "project_reference": {
      "type": "string",
      "minLength": 1,
      "description": "Project ID or slug; required unless the token is project-scoped. Create the conversation optionally with a first user message and an idempotency key."
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "default_chat",
        "plan",
        "research",
        "agent_task",
        "support",
        "channel",
        "project_agent"
      ],
      "description": "Provide the type."
    },
    "title": {
      "type": "string",
      "maxLength": 500,
      "description": "Short human-readable title for the record."
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Retrying with the same key and the same arguments returns the same conversation; different arguments fail with an idempotency conflict."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "description": "Additional structured values supplied to the tool."
      },
      "description": "Additional structured metadata for the request."
    },
    "initial_message": {
      "type": "object",
      "properties": {
        "composing_user_id": {
          "type": "string",
          "format": "uuid",
          "description": "Provide the composing user id."
        },
        "role": {
          "type": "string",
          "const": "user",
          "description": "Always user; may be omitted."
        },
        "parts": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "text",
                    "description": "Provide the type."
                  },
                  "text": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "Provide the text."
                  }
                },
                "required": [
                  "type",
                  "text"
                ],
                "additionalProperties": false,
                "description": "Structured option 1 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "image",
                    "description": "Provide the type."
                  },
                  "upload_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Provide the upload id."
                  },
                  "media_type": {
                    "type": "string",
                    "description": "Provide the media type."
                  },
                  "url": {
                    "type": "string",
                    "description": "Provide the url."
                  }
                },
                "required": [
                  "type",
                  "upload_id",
                  "media_type"
                ],
                "additionalProperties": false,
                "description": "Structured option 2 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "file",
                    "description": "Provide the type."
                  },
                  "upload_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Provide the upload id."
                  },
                  "media_type": {
                    "type": "string",
                    "description": "Provide the media type."
                  },
                  "filename": {
                    "type": "string",
                    "description": "Provide the filename."
                  },
                  "url": {
                    "type": "string",
                    "description": "Provide the url."
                  }
                },
                "required": [
                  "type",
                  "media_type"
                ],
                "additionalProperties": false,
                "description": "Structured option 3 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "tool_call",
                    "description": "Provide the type."
                  },
                  "id": {
                    "type": "string",
                    "description": "Unique identifier for the target record."
                  },
                  "name": {
                    "type": "string",
                    "description": "Human-readable name for the target record."
                  },
                  "input": {
                    "type": "object",
                    "additionalProperties": {
                      "description": "Additional structured values supplied to the tool."
                    },
                    "description": "Structured input details used by the tool."
                  },
                  "state": {
                    "type": "string",
                    "enum": [
                      "streaming",
                      "pending",
                      "completed",
                      "error"
                    ],
                    "description": "Provide the state."
                  }
                },
                "required": [
                  "type",
                  "id",
                  "name",
                  "input",
                  "state"
                ],
                "additionalProperties": false,
                "description": "Structured option 4 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "tool_result",
                    "description": "Provide the type."
                  },
                  "tool_call_id": {
                    "type": "string",
                    "description": "Tool call identifier that links this request to a prior tool invocation."
                  },
                  "output": {
                    "description": "Provide the output."
                  },
                  "is_error": {
                    "type": "boolean",
                    "description": "Provide the is error."
                  }
                },
                "required": [
                  "type",
                  "tool_call_id"
                ],
                "additionalProperties": false,
                "description": "Structured option 5 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "reasoning",
                    "description": "Provide the type."
                  },
                  "text": {
                    "type": "string",
                    "maxLength": 100000,
                    "description": "Provide the text."
                  },
                  "signature": {
                    "type": "string",
                    "description": "Provide the signature."
                  }
                },
                "required": [
                  "type",
                  "text"
                ],
                "additionalProperties": false,
                "description": "Structured option 6 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "citation",
                    "description": "Provide the type."
                  },
                  "source_id": {
                    "type": "string",
                    "description": "Provide the source id."
                  },
                  "url": {
                    "type": "string",
                    "description": "Provide the url."
                  },
                  "title": {
                    "type": "string",
                    "description": "Short human-readable title for the record."
                  },
                  "quote": {
                    "type": "string",
                    "description": "Provide the quote."
                  }
                },
                "required": [
                  "type",
                  "source_id"
                ],
                "additionalProperties": false,
                "description": "Structured option 7 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "source_document",
                    "description": "Provide the type."
                  },
                  "source_id": {
                    "type": "string",
                    "description": "Provide the source id."
                  },
                  "media_type": {
                    "type": "string",
                    "description": "Provide the media type."
                  },
                  "title": {
                    "type": "string",
                    "description": "Short human-readable title for the record."
                  },
                  "filename": {
                    "type": "string",
                    "description": "Provide the filename."
                  }
                },
                "required": [
                  "type",
                  "source_id",
                  "media_type",
                  "title"
                ],
                "additionalProperties": false,
                "description": "Structured option 8 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "step_start",
                    "description": "Provide the type."
                  }
                },
                "required": [
                  "type"
                ],
                "additionalProperties": false,
                "description": "Structured option 9 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "error",
                    "description": "Provide the type."
                  },
                  "code": {
                    "type": "string",
                    "description": "Provide the code."
                  },
                  "message": {
                    "type": "string",
                    "description": "Provide the message."
                  }
                },
                "required": [
                  "type",
                  "code",
                  "message"
                ],
                "additionalProperties": false,
                "description": "Structured option 10 details used by the tool."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "data",
                    "description": "Provide the type."
                  },
                  "name": {
                    "type": "string",
                    "description": "Human-readable name for the target record."
                  },
                  "value": {
                    "description": "Provide the value."
                  }
                },
                "required": [
                  "type",
                  "name"
                ],
                "additionalProperties": false,
                "description": "Structured option 11 details used by the tool."
              }
            ],
            "description": "One part item supplied to the tool."
          },
          "minItems": 1,
          "maxItems": 200,
          "description": "Provide one or more part values."
        },
        "idempotency_key": {
          "type": "string",
          "maxLength": 255,
          "description": "Provide the idempotency key."
        },
        "metadata": {
          "type": "object",
          "additionalProperties": {
            "description": "Additional structured values supplied to the tool."
          },
          "description": "Additional structured metadata for the request."
        }
      },
      "required": [
        "parts"
      ],
      "additionalProperties": false,
      "description": "A first user message stored atomically with the conversation, as on REST POST /conversations."
    }
  },
  "additionalProperties": false,
  "description": "Arguments for the create_conversation tool.",
  "$schema": "http://json-schema.org/draft-07/schema#"
}
json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Conversation identifier."
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Project identifier that owns the conversation, or null for global/system conversations."
    },
    "responding_agent_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Agent currently responding in the conversation, or null when no agent has responded.",
      "default": null
    },
    "type": {
      "type": "string",
      "enum": [
        "chat",
        "default_chat",
        "plan",
        "research",
        "agent_task",
        "support",
        "channel",
        "project_agent"
      ],
      "description": "Conversation type, such as agent, support, or workflow conversation."
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Human-readable conversation title."
    },
    "summary": {
      "type": [
        "string",
        "null"
      ],
      "description": "Short summary of the conversation state or topic."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "archived",
        "deleted"
      ],
      "description": "Lifecycle status of the conversation."
    },
    "current_node": {
      "type": [
        "string",
        "null"
      ],
      "description": "Selected conversation message node for the active branch, or null when no message is selected."
    },
    "message_count": {
      "type": "number",
      "description": "Number of persisted messages in the conversation."
    },
    "last_message_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Timestamp of the most recent message in the conversation."
    },
    "metadata": {
      "anyOf": [
        {
          "type": "object",
          "additionalProperties": {
            "description": "Additional structured values associated with this result."
          },
          "description": "Additional structured metadata returned by the tool."
        },
        {
          "type": "null",
          "description": "Additional structured metadata returned by the tool."
        }
      ],
      "description": "Additional machine-readable conversation metadata."
    },
    "created_by": {
      "type": [
        "string",
        "null"
      ],
      "description": "User or actor identifier that created the conversation."
    },
    "archived_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Timestamp when the conversation was archived, or null when active."
    },
    "created_at": {
      "type": "string",
      "description": "Timestamp when the conversation was created."
    },
    "updated_at": {
      "type": "string",
      "description": "Timestamp when the conversation was last updated."
    },
    "participants": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the returned record."
          },
          "participant_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "participant_type": {
            "type": "string",
            "enum": [
              "user",
              "agent"
            ],
            "default": "user"
          },
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "agent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "agent_kind": {
            "anyOf": [
              {
                "type": "string",
                "const": "project"
              },
              {
                "type": "null",
                "description": "The agent kind returned by the tool."
              }
            ]
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "member",
              "viewer"
            ]
          }
        },
        "required": [
          "id",
          "role"
        ],
        "additionalProperties": false
      },
      "description": "Participants of the conversation. Empty on the confirmation body of delete_conversation.",
      "default": []
    },
    "initial_message_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null",
          "description": "The initial message id returned by the tool."
        }
      ],
      "description": "The first message stored with the conversation, when initial_message was sent."
    }
  },
  "required": [
    "id",
    "type",
    "status",
    "message_count",
    "created_by",
    "created_at",
    "updated_at",
    "initial_message_id"
  ],
  "additionalProperties": false,
  "description": "Conversation record returned by MCP conversation tools.",
  "$schema": "http://json-schema.org/draft-07/schema#"
}