> ## Documentation Index > Fetch the complete documentation index at: https://dify-6c0370d8-docs-agent-app-service-api.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Send Agent App Message > Send a user message to an Agent app. Agent apps use streaming responses only and may return message chunks, agent reasoning/tool events, generated files, and a final `message_end` event. ## OpenAPI ````yaml /en/api-reference/openapi_agent.json post /chat-messages openapi: 3.0.1 info: title: Agent App API description: >- Agent apps expose a streaming service API for production integrations. Use the API key created from the Agent app API Access page. Public service API requests use the returned API base URL and do not include the Agent ID in the path; the API key identifies the backing app. version: 1.0.0 servers: - url: https://{api_base_url} description: >- Base URL of the Agent App API. Use the Service API Base URL shown in the Agent app API Access page. For self-hosted deployments, replace it with your own API base URL. variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - name: Agent Messages description: Send Agent app messages and stop running tasks. - name: Agent Files description: Upload files for Agent app conversations. - name: Agent Conversations description: List Agent app conversations and conversation messages. - name: Agent App description: Retrieve Agent app parameters and metadata. paths: /chat-messages: post: tags: - Agent Messages summary: Send Agent App Message description: >- Send a user message to an Agent app. Agent apps use streaming responses only and may return message chunks, agent reasoning/tool events, generated files, and a final `message_end` event. operationId: sendAgentAppMessage requestBody: description: Request body to send an Agent app message. required: true content: application/json: schema: $ref: '#/components/schemas/AgentChatRequest' examples: streaming_example: summary: Request Example value: inputs: customer_tier: enterprise query: >- Summarize the attached product feedback and suggest next steps. response_mode: streaming conversation_id: '' user: user-123 files: - type: document transfer_method: local_file upload_file_id: 72fa9618-8f89-4a37-9b33-7e1178a24a67 responses: '200': description: >- Successful streaming response. Agent apps return `text/event-stream` Server-Sent Events. Blocking JSON responses are not supported for Agent apps. content: text/event-stream: schema: type: string description: >- A stream of Server-Sent Events (SSE). **Parsing**: Each event is a line prefixed with `data: ` followed by a JSON object, terminated by `\n\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which arrive as `event: ping` lines (no `data:` payload) every 10 seconds to keep the connection alive. **Stream lifecycle**: The reply streams as `message` events (Chatbot apps), or as `agent_thought` and `agent_message` events (Agent apps), and ends with `message_end`. When text-to-speech auto-play is enabled, `tts_message` events interleave and `tts_message_end` becomes the final event. **Events**: Apart from `ping`, every event includes `conversation_id`, `message_id`, and `created_at` (Unix epoch seconds); all but `error` also include `task_id`. **Reply events** | Event | App | Fires on | Key fields | |:---|:---|:---|:---| | `message` | Chatbot | each answer chunk (concatenate in order) | `answer` | | `agent_message` | Agent | each answer chunk (concatenate in order) | `answer` | | `agent_thought` | Agent | each reasoning or tool-call step | `position`, `thought`, `tool`, `tool_input` (JSON), `observation`, `message_files` | | `message_replace` | Chatbot, Agent | output moderation replaces the answer so far | `answer` | | `message_file` | Chatbot, Agent | the assistant returns a file | `type`, `belongs_to`, `url` | | `message_end` | Chatbot, Agent | the answer is complete | `metadata` (`usage`, `retriever_resources`) | | `tts_message`, `tts_message_end` | Chatbot, Agent | audio chunk / end, when TTS auto-play is on | `audio` | **Transport events** | Event | App | Fires on | Key fields | |:---|:---|:---|:---| | `error` | Chatbot, Agent | a failure ends the stream; HTTP stays `200` | `status` (e.g. `400`), `code` (e.g. `invalid_param`), `message` | | `ping` | Chatbot, Agent | keep-alive every 10 seconds | none | examples: streamingResponseAgent: summary: Response Example - Streaming (Agent) value: >- data: {"event": "agent_thought", "id": "agent_thought_id_1", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "position": 1, "thought": "Thinking about calling a tool...", "tool": "dalle3", "tool_input": "{\"dalle3\": {\"prompt\": \"a cute cat\"}}", "created_at": 1705395332} data: {"event": "message_file", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "id": "file_id_1", "type": "image", "belongs_to": "assistant", "url": "https://example.com/cat.png", "created_at": 1705395332} data: {"event": "agent_message", "task_id": "task123", "message_id": "msg123", "conversation_id": "conv123", "answer": "Here is the image: ", "created_at": 1705395333} data: {"event": "message_end", "task_id":"task123", "message_id": "msg123", "conversation_id": "conv123", "metadata": {"usage": {"total_tokens": 50, "latency": 2.5}}} '400': description: >- - `app_unavailable` : App unavailable or misconfigured. - `not_chat_app` : App mode does not match the API route. - `conversation_completed` : The conversation has ended. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Text generation failed. content: application/json: examples: app_unavailable: summary: app_unavailable value: status: 400 code: app_unavailable message: App unavailable, please check your app configurations. not_chat_app: summary: not_chat_app value: status: 400 code: not_chat_app message: Please check if your app mode matches the right API route. conversation_completed: summary: conversation_completed value: status: 400 code: conversation_completed message: >- The conversation has ended. Please start a new conversation. provider_not_initialize: summary: provider_not_initialize value: status: 400 code: provider_not_initialize message: >- No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. provider_quota_exceeded: summary: provider_quota_exceeded value: status: 400 code: provider_quota_exceeded message: >- Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials. model_currently_not_support: summary: model_currently_not_support value: status: 400 code: model_currently_not_support message: >- Dify Hosted OpenAI trial currently not support the GPT-4 model. completion_request_error: summary: completion_request_error value: status: 400 code: completion_request_error message: Completion request failed. '404': description: '`not_found` : Conversation does not exist.' content: application/json: examples: conversation_not_exists: summary: not_found value: status: 404 code: not_found message: Conversation Not Exists. '429': description: >- - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. content: application/json: examples: too_many_requests: summary: too_many_requests value: status: 429 code: too_many_requests message: Too many requests. Please try again later. rate_limit_error: summary: rate_limit_error value: status: 429 code: rate_limit_error message: Rate Limit Error '500': description: '`internal_server_error` : Internal server error.' content: application/json: examples: internal_server_error: summary: internal_server_error value: status: 500 code: internal_server_error message: Internal server error. components: schemas: AgentChatRequest: type: object required: - inputs - query - user properties: query: type: string description: User message or task for the Agent app. inputs: type: object description: >- Values for variables configured in the Agent Soul. Call the Get Agent App Parameters API to discover expected variable names and input controls. additionalProperties: true response_mode: type: string enum: - streaming description: >- Agent apps support streaming mode only. Set this field to `streaming` or omit it. default: streaming user: type: string description: >- End-user identifier, unique within this Agent app. Conversations, messages, and uploaded files are scoped to the same `user` value. conversation_id: type: string description: >- Conversation ID to continue. Omit this field or pass an empty string to start a new conversation, then reuse the returned `conversation_id` in later requests. files: type: array description: >- Files for multimodal Agent input. To attach a local file, upload it with the Upload File API first, then pass the returned file `id` as `upload_file_id` with `transfer_method: local_file`. items: type: object required: - type - transfer_method properties: type: type: string enum: - image - document - audio - video - custom description: File type. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for file URL, `local_file` for uploaded file. url: type: string format: url description: File URL (required when `transfer_method` is `remote_url`). upload_file_id: type: string description: >- Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (required when `transfer_method` is `local_file`). auto_generate_name: type: boolean description: >- Auto-generate conversation title. If `false`, use the [Rename Conversation](/api-reference/conversations/rename-conversation) API with `auto_generate: true` for async title generation. default: true description: Request body for sending a message to an Agent app. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.** ````