--- title: "Send message." method: POST path: "/api/v1/projects/{projectId}/conversations/{sessionId}/messages" tags: ["Conversations"] --- # Send message. `POST /api/v1/projects/{projectId}/conversations/{sessionId}/messages` ## Request - Base URL: `https://app.customgpt.ai` - URL: `https://app.customgpt.ai/api/v1/projects/{projectId}/conversations/{sessionId}/messages` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Sends a user message to an agent and returns the agent's response. Supports streaming for real-time display, file attachments for document analysis, and persona overrides for dynamic behavior. This is the primary endpoint for chat interactions. Notes: Add ?stream=true to receive the response in real-time chunks. ## Path parameters - `projectId` integer, required - `sessionId` string, required ## Query parameters - `stream` boolean - `lang` string - `external_id` string ## Request body `multipart/form-data` - object - `prompt` string: Prompt to send to the agent - `custom_persona` string, nullable: Custom persona to use for the conversation - `sub_personas` object, nullable: Request-only sub-persona overrides keyed by sub-persona slug. Omitted keys use the saved generated/project value. For multipart/form-data, send bracket notation like sub_personas[persona-summary]=... - `persona-summary` string, nullable - `task-planner` string, nullable - `chatbot_model` 'gpt-4-1' | 'gpt-6-sol-none' | 'gpt-5.6-sol-none' | 'gpt-5.6-terra-none' | 'gpt-6-luna-none' | 'gpt-5.6-luna-none' | 'gpt-4-o' | 'gpt-5.1-none' | 'gpt-5.1-low' | 'gpt-5.2-none' | 'gpt-5.2-low' | 'gpt-5.4-low' | 'gpt-4-1-mini' | 'gpt-4o-mini' | 'claude-5.5-opus' | 'claude-5-opus' | 'claude-5-sonnet-thinking' | 'claude-5-sonnet' | 'claude-4.8-opus' | 'claude-4.6-opus' | 'claude-4.5-opus' | 'claude-4.6-sonnet' | 'claude-4.6-sonnet-thinking' | 'claude-4.5-sonnet' | 'claude-4.5-haiku' | 'gpt-o4-mini-low' | 'gpt-o4-mini-medium' | 'gpt-o4-mini-high' | 'gemini-3.1-pro' | 'gemini-3-pro' | 'gemini-3.5-flash', nullable: Agent model to use for the conversation - `response_source` 'default' | 'own_content' | 'openai_content', nullable: Controls which knowledge the agent draws from. Values: - `default` / `own_content` — agent answers using only your indexed content (recommended). - `openai_content` — agent supplements your indexed content with general knowledge from the underlying model. - `custom_context` string, nullable: Custom context to use for the conversation - `child_project_id` integer, nullable: Optional child agent id for master agents. Provide it to route the message to a specific child agent. Omit it to let Auto / Smart Routing resolve the child agent when enabled. - `file` string, binary, nullable: File to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp) - `files[]` string[], nullable: Multiple files to upload (Allowed types: pdf, docx, doc, odt, txt, jpg, jpeg, png, webp) - `agent_capability` 'fastest-responses' | 'optimal-choice' | 'advanced-reasoning' | 'complex-tasks', nullable: Agent capability preset. Values: - `fastest-responses` — prioritises speed; best for simple, high-volume tasks. - `optimal-choice` (default) — balances speed and quality for most tasks. - `advanced-reasoning` — uses extended thinking for multi-step or analytical tasks. - `complex-tasks` — maximum capability for long-horizon, deeply complex tasks; slowest and most resource-intensive. Ignored when `use_planner_mode` is enabled. - `labels[]` union[], nullable: Optional source-label filter (IDs or names). - Single group (OR): `labels[0][]=A&labels[0][]=B` - Multiple groups (AND-of-ORs, inner OR / outer AND): `labels[0][]=A&labels[0][]=B&labels[1][]=C&labels[1][]=D` → (A OR B) AND (C OR D) Limits: max 20 groups, 50 per group, 500 total. Unknown labels are dropped; a group emptied by dropping matches nothing. - union - string - string[] - `labels_exclusive` boolean: If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages. - `action_overrides` object, nullable: Override agent actions for this query only. Provide enabled and disabled action IDs. When using multipart/form-data, send action_overrides as a JSON-encoded object. - `enabled` string[]: Action IDs to enable for this request (built-in tool keys or custom tool keys). - `disabled` string[]: Action IDs to disable for this request (built-in tool keys or custom tool keys). ## Response `200` Send a message to a conversation - object - `status` 'error' | 'success': The status of the response - `data` PromptHistory - `id` integer: The unique identifier of the prompt history. - `conversation_id` integer: The unique identifier of the conversation. - `user_id` integer: The unique identifier of the user. - `user_query` string: The user prompt query. - `openai_response` string: The OpenAI response to the user prompt query. - `citations` integer[]: The citations for the prompt history. - `citations_external` object[]: External (web/agentic) source citations referenced in the response. Empty when the response cited no external sources. - `source_id` string: Opaque per-type identifier of the external source. - `type` string: External source type (e.g. web, mcp, file, sharepoint). - `action` string, nullable: The agentic action that produced the citation. - `title` string: Title of the external source. - `url` string: Absolute http(s) URL of the external source. - `description` string: Short snippet/description of the external source. - `citations_hidden` integer[]: Page ids the response drew on that were hidden from the citations shown to the user, either by the agent-level sources setting or per page. Debugging aid, never rendered in the chat UI. - `tools` string[]: Array of tools invoked during response generation (e.g., web search, document retrieval). Returns an empty array if no tools were used. - `metadata` object: Additional metadata associated with this message, such as custom session attributes passed via the API. Returns null if no metadata was set. - `user_ip` string: The IP address of the user. - `user_agent` string: The user agent of the user. - `external_id` string: The external ID of the prompt history. - `request_source` string: The source of the request. - `response_feedback` object, nullable: User feedback submitted for this response. Includes the reaction rating and any text feedback. Returns null if the user has not provided feedback. - `created_at` string, date-time: The timestamp when the feedback was created - `updated_at` string, date-time: The timestamp when the feedback was last updated - `user_id` integer, nullable: The ID of the user who provided the feedback - `reaction` 'neutral' | 'disliked' | 'liked': User reaction to this response. - `customer_intelligence` CustomerIntelligence: Customer intelligence data captured for this conversation turn, populated when the lead capture feature is enabled. Contains contact information and intent signals. Returns null if lead capture is disabled. - `prompt_id` integer: Unique identifier for the prompt - `conversation_id` integer: Unique identifier for the conversation - `project_id` integer: Unique identifier for the project - `user_query` string: The user's original query - `ai_response` string: The AI's response to the query - `created_at` string: Timestamp when the interaction occurred - `content_source` string: Detected content source - `user_emotion` string: Detected user emotion - `user_intent` string: Detected user intent - `language` string: Detected language - `human_request` 'true' | 'false' | 'unclear': Whether the user requested a human - `user_id` integer: Sent-by user identifier. -2 indicates SSO Guest, -1 indicates Guest, and positive values indicate team member user IDs. - `feedback` string, nullable: User feedback on the response - `user_location` string: User's location (country code) - `chatbot_deployment` string: Chatbot deployment source - `risk_fidelity` string: Risk fidelity level - `risk_jailbreak` string: Jailbreak risk assessment - `risk_prompt_leakage` string: Prompt leakage risk assessment - `risk_profanity` string: Profanity risk assessment - `accuracy` string: Response accuracy assessment - `stakeholder_status` string: Stakeholder status classification - `browser` string: User's browser information - `created_at` string, date-time: The date and time the prompt history was created. - `updated_at` string, date-time: The date and time the prompt history was last updated. ## Other responses - `400`: Bad Argument - `401`: API Token is either missing or invalid - `404`: Agent not found - `409`: Bad Argument - `429`: Resource Exhausted when sending a message to a conversation - `500`: Internal Server Error ## Changes - **2026-11-03** `77aab4354382`: 2 breaking, 8 warning, 7 info - removed the media type `application/json` from the request body - the response property `data/response_feedback` became nullable for the status `200` - added the new `422.00` enum value to the `data/code` response property for the response status `400` - added the new `422.00` enum value to the `data/code` response property for the response status `401` - …13 more - **2026-07-17** `b80e6dfcf78d`: 2 warning, 10 info - added the new `Agent id is required` enum value to the `data/message` response property for the response status `404` - added the new `Agent with id {projectId} not found` enum value to the `data/message` response property for the response status `404` - added the new optional `query` request parameter `external_id` - added the new optional request property `chatbot_model` - …8 more - **2023-07-27** `2cd2d58839d0`: 2 info - added the non-success response with the status `400` - added the optional property `data/metadata` to the response with the `200` status - **2023-07-12** `1675fc6aa16a`: 1 warning, 8 info - removed the optional property `data/message` from the response with the `200` status - added the optional property `data/citations` to the response with the `200` status - added the optional property `data/conversation_id` to the response with the `200` status - added the optional property `data/created_at` to the response with the `200` status - …5 more - …earlier changes not shown [Operation history](https://skmtc.dev/poll-the-people/apis/customgpt-ai/changes/api/v1/projects/:projectId/conversations/:sessionId/messages/post.md) --- [API](https://skmtc.dev/poll-the-people/apis/customgpt-ai.md) - [All operations](https://skmtc.dev/poll-the-people/apis/customgpt-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/poll-the-people/apis/customgpt-ai/revisions/77aab4354382?raw)