Conversations

Send message.

Changed on Nov 3, 2026

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.

post/api/v1/projects/{projectId}/conversations/{sessionId}/messages

Request

Base URL
https://app.customgpt.ai
Auth
HTTP bearer
TypeScript
https://skmtc.dev/poll-the-people/apis/customgpt-ai/docs/api/v1/projects/:projectId/conversations/:sessionId/messages/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

projectIdinteger required

Example:1

The ID of the agent to get the messages for

sessionIdstring required

Example:1

The session ID of the converstaions to get the messages for

Query parameters

streamboolean

When true, the response is sent as a stream of data-only server-sent events (SSE) as tokens are generated, terminated by a status: "finish" event. When false, the full response is returned in a single JSON object. See the streaming guide for client implementation examples.

langstring

The ISO 639-1 language code for the response language. Examples: es - Spanish, fr - French, de - German, ja - Japanese. The agent will attempt to respond in this language regardless of the query language.

external_idstring

The external ID of the prompt history.

Request body multipart/form-data

promptstring

Prompt to send to the agent

custom_personastring nullable

Custom persona to use for the conversation

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_contextstring nullable

Custom context to use for the conversation

child_project_idinteger 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.

filestring 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_exclusiveboolean

If true, search only pages with provided labels. If false, search pages with provided labels plus unlabeled pages.

Example request

{
  "prompt": "How do I reset my password?",
  "stream": false
}

Response

Send a message to a conversation

status'error' | 'success'

The status of the response

Example response

{
  "status": "success",
  "data": {
    "id": 101,
    "conversation_id": 42,
    "user_id": 1,
    "user_query": "What file formats does CustomGPT support?",
    "openai_response": "CustomGPT supports PDF, DOCX, TXT, and more. You can also ingest content via sitemap, URL, or file upload.",
    "citations": [
      3,
      7
    ],
    "citations_external": [
      {
        "source_id": "1-1",
        "type": "web",
        "action": "web_search",
        "title": "Paris - Wikipedia",
        "url": "https://en.wikipedia.org/wiki/Paris",
        "description": "Paris is the capital of France."
      }
    ],
    "citations_hidden": [
      12
    ],
    "tools": [],
    "metadata": {
      "user_ip": "203.0.113.12",
      "user_agent": "Mozilla/5.0",
      "external_id": "ext_id_abc123",
      "request_source": "web"
    },
    "response_feedback": {
      "created_at": "2024-08-27T21:07:20.000000Z",
      "updated_at": "2024-08-27T21:07:20.000000Z",
      "user_id": 1,
      "reaction": "liked"
    },
    "customer_intelligence": {
      "prompt_id": 101,
      "conversation_id": 42,
      "project_id": 7,
      "user_query": "What file formats does CustomGPT support?",
      "ai_response": "CustomGPT supports PDF, DOCX, TXT, and more.",
      "created_at": "2026-02-01T09:20:00.000000Z",
      "content_source": "in-context",
      "user_emotion": "neutral",
      "user_intent": "informational",
      "language": "en",
      "human_request": "false",
      "user_id": -2,
      "user_location": "US",
      "chatbot_deployment": "web",
      "risk_fidelity": "Good",
      "risk_jailbreak": "no_event",
      "risk_prompt_leakage": "no_event",
      "risk_profanity": "no_event",
      "accuracy": "-",
      "stakeholder_status": "UNKNOWN",
      "browser": "Chrome 121"
    },
    "created_at": "2026-02-01T09:20:00.000000Z",
    "updated_at": "2026-02-01T09:20:05.000000Z"
  }
}

Changes

Nov 3, 202677aab4354382 Revision changes
- breaking
  removed the media type application/json from the request body
- breaking
  the response property / became nullable for the status
- warning
  added the new 422.00 enum value to the / response property for the response status
- warning
  added the new 422.00 enum value to the / response property for the response status
- warning
  added the new 422.00 enum value to the / response property for the response status
- warning
  added the new 422.00 enum value to the / response property for the response status
- warning
  added the new 422.00 enum value to the / response property for the response status
- warning
  added the new disliked enum value to the // response property for the response status
- warning
  added the new liked enum value to the // response property for the response status
- warning
  added the new neutral enum value to the // response property for the response status
- info
  added the media type multipart/form-data to the request body
- info
  added the non-success response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  removed the neutral disliked liked enum value from the // response property for the response status
Jul 17, 2026b80e6dfcf78d Revision changes
- warning
  added the new Agent id is required enum value to the / response property for the response status
- warning
  added the new Agent with id {projectId} not found enum value to the / response property for the response status
- info
  added the new optional query request parameter external_id
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the non-success response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property / to the response with the status
- info
  removed the Project id is required enum value from the / response property for the response status
- info
  removed the Project with id {projectId} not found enum value from the / response property for the response status

Operation history (5 revisions)