Skip to main content

Send a message to a conversation

POST 
/api/v1/llm/send-message

Sends a user message to the specified conversation thread. This appends the message to history and starts a generation workflow run. If a run is already in progress, behavior depends on the conversation's interrupt policy.

See Messages and run outcomes for status interpretation and recovery.

Use this in a guide: API Reference · Build a support conversation the user can return to · Let a customer navigate your app through chat · Approve a tool action and finish the conversation · Build a reusable assistant profile · Recover when no model can serve the request · Build a research, bulk-summary or structured-summary flow · Route an image question to a capable model · Keep a model on the providers you choose · Add an optional reasoning panel to a chat reply · Configuration precedence and plugins · Model routing and selection · Control access with scopes · Build an assistant that researches the web · MCP server selection · Summarize a customer’s uploaded report · Build a signed-in support chat that survives reconnects · Explain the setting the customer is looking at · Configure a support conversation that stays predictable · Get a customer’s reply and recover an interrupted send · Complete your first support-chat turn · Restore a chat after the connection drops · Answer questions about a website using your own Firecrawl account · Messages and runs · Profile selection and prompt versions

Request​

Responses​

Message accepted and generation initiated

Schema-valid request illustration; replace example identifiers and confirm operation prerequisites.​

Section ID: DOC-MA-conversations-api-sendMessage#example-conversations-sendMessage-request

Request example

{
  "conversationKey": "example_123",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Hello"
      }
    ]
  }
}

Guide request for The `users:impersonate` scope and `X-On-Behalf-Of`. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-core-platform-identity-access-scopes-permissions-01-request

Request example

{
  "conversationKey": "conv_abc",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Hello"
      }
    ]
  }
}

Guide request for 4. Ask about the page in a conversation. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-integrations-tools-connections-custom-mcp-servers-05-request

Request example

{
  "conversationKey": "support-chat-001",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Read https://www.firecrawl.dev/pricing and summarize the pricing options. Link to the source."
      }
    ]
  },
  "overrideMcpServers": [
    {
      "serverId": "custom:firecrawl",
      "enabled": true
    }
  ]
}

Guide request for Send the message. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-conversations-build-chat-assistant-03-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "What can you help me with?"
      }
    ]
  }
}

Guide request for Step 1: Send once and read the same conversation. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-conversations-generation-01-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Hello, what can you help me with?"
      }
    ]
  }
}

Guide request for Step 2: Send the customer’s first question. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-conversations-index-02-request

Request example

{
  "conversationKey": "support-chat-001",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "How do I reset my password?"
      }
    ]
  }
}

Guide request for Recipe: summarize support notes with a catalog price filter. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-model-controls-examples-02-request

Request example

{
  "conversationKey": "bulk-task-001",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Summarize this support note: The customer reset their password and can now sign in."
      }
    ]
  },
  "overrideGenerationConfig": {
    "models": [
      "google/gemini-3.6-flash:nitro",
      "google/gemini-3.1-flash-lite",
      "google/gemini-3-flash-preview"
    ],
    "modelRoutingFilter": {
      "maxPromptCost": 0.000005,
      "maxCompletionCost": 0.00002
    }
  }
}

Guide request for Recipe: return a task summary after tool-assisted work. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-model-controls-examples-03-request

Request example

{
  "conversationKey": "<your-thread-id>",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Summarize the task we just discussed."
      }
    ]
  },
  "overrideGenerationConfig": {
    "models": [
      "google/gemini-3.6-flash:nitro",
      "anthropic/claude-sonnet-4.6:nitro"
    ],
    "responseFormat": {
      "jsonSchema": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "string"
          }
        },
        "required": [
          "summary"
        ],
        "additionalProperties": false
      },
      "schemaName": "task_summary",
      "validate": true
    },
    "modelRoutingFilter": {
      "requiredParameters": [
        "tools",
        "response_format"
      ]
    }
  }
}

Guide request for Step 1: send the image with its required capability. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-model-controls-filtering-01-request

Request example

{
  "conversationKey": "research-001",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_IMAGE_BASE64",
        "content": "<base64_image>"
      },
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "What is in this image?"
      }
    ]
  },
  "overrideGenerationConfig": {
    "models": [
      "google/gemini-3.6-flash:nitro",
      "anthropic/claude-sonnet-4.6:nitro",
      "anthropic/claude-sonnet-5"
    ],
    "modelRoutingFilter": {
      "requiredInputModalities": [
        "image"
      ]
    }
  }
}

Guide request for Variant: reuse the same assistant setup across conversations. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-conversations-configuration-json-02-request

Request example

{
  "conversationKey": "thread_abc",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "..."
      }
    ]
  },
  "setActiveProfileId": "profile_escalation"
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.​

Section ID: DOC-MA-conversations-api-sendMessage#example-conversations-sendMessage-response

Response example

{
  "runId": "example_123",
  "interruptedPriorRun": true
}

Illustrative response for Send the message. Replace example resource identifiers with your own authorized values.​

Section ID: DOC-MA-conversations-api-sendMessage#example-cookbook-managed-agents-conversations-build-chat-assistant-json-03-response

Response example

{
  "runId": "64403669-5989-4ec3-ad9c-d84223f9679f"
}

Document ID: DOC-MA-conversations-api-sendMessage. Section identities and revisions.

SectionStable reference
Send a message to a conversationDOC-MA-conversations-api-sendMessage#overview
RequestDOC-MA-conversations-api-sendMessage#request
ResponsesDOC-MA-conversations-api-sendMessage#responses