Send a message and wait for the result

POST /api/v1/llm/send-message-sync

Sends a message and waits for a bounded interval, returning generated messages inline when available. Use it when you need the assistant reply in the HTTP response, such as structured output or a classification.

Inspect status even on HTTP 200: a queued message, a pause for client tools or the bounded wait ending can return before the run finishes. A transport timeout or unknown status does not authorize resending the message; reconcile the accepted run.

See Messages and run outcomes for status interpretation and recovery.

Use this in a guide: Let a customer navigate your app through chat · Check a chat integration before customers use it · Replay datasets and runs · Turn a task description into a validated summary object · Build an assistant that researches the web · Get a customer’s reply and recover an interrupted send · Tool policy resolution and lifecycle · Automate recurring agent work · Signed callbacks and receiver acknowledgement · Show one correct chat history as updates arrive · Messages and runs

Request

Responses

Run status returned; generation may still be active or waiting

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

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

Request example

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

Guide request for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-core-platform-scheduling-build-scheduled-agents-01-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Generate the daily briefing."
      }
    ]
  }
}

Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-developer-experience-local-tooling-testing-01-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Navigate to my profile."
      }
    ]
  }
}

Guide request for 4. Run both configurations and retain their outcomes. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-insights-evaluation-datasets-and-runs-05-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "What is the return window?"
      }
    ]
  },
  "experiment": {
    "datasetId": "ds_771",
    "runName": "nightly-2026-08-14",
    "datasetItemId": "di_001",
    "profileRevisionHash": "a1b2c3…"
  }
}

Guide request for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-managed-agents-conversations-generation-03-request

Request example

{
  "conversationKey": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Summarize this thread as JSON."
      }
    ]
  }
}

Guide request for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-managed-agents-delegation-approvals-using-tools-03-request

Request example

{
  "conversationKey": "support-chat-001",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "Navigate to my profile."
      }
    ]
  }
}

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

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

Response example

{
  "runId": "example_123",
  "interruptedPriorRun": true,
  "messages": [
    {
      "role": "ROLE_SYSTEM",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "Example text",
          "cachePreferred": true
        }
      ],
      "toolCalls": [
        {
          "id": "example_123",
          "name": "example",
          "status": "TOOL_EXECUTION_STATUS_PENDING",
          "serverId": "example_123",
          "isClientTool": true,
          "description": "example",
          "approvedBy": "example",
          "endReason": "example"
        }
      ],
      "name": "example",
      "timestamp": "2026-09-16T12:00:00Z",
      "messageId": "example_123",
      "annotations": [
        {
          "kind": "ANNOTATION_KIND_URL_CITATION"
        }
      ],
      "sequence": "1",
      "generatedBy": "example",
      "usage": {
        "promptTokens": 1,
        "completionTokens": 1,
        "totalTokens": 1,
        "costEstimate": 1,
        "isByok": true
      },
      "model": "example",
      "generationContext": {
        "languagePreference": "en-US",
        "resolvedSystemPrompt": "Example text",
        "profileId": "example_123",
        "model": "example",
        "promptSource": "PROMPT_SOURCE_CLIENT_OVERRIDE",
        "profileVersion": 1,
        "fragmentsVersion": 1,
        "profileRenderFailed": true,
        "resolvedPromptHash": "Example text",
        "resolvedUserContext": "Example text"
      },
      "clientContext": {},
      "feedback": [
        {
          "kind": "FEEDBACK_KIND_THUMB",
          "thumbUp": true,
          "reason": "example",
          "ratedBy": "example"
        }
      ],
      "sourceUserMessageId": "example_123",
      "finishReason": "example"
    }
  ],
  "status": "AGENT_STATUS_ACTIVE",
  "aggregateUsage": {
    "promptTokens": 1,
    "completionTokens": 1,
    "totalTokens": 1,
    "costEstimate": 1,
    "completionTokensDetails": {
      "reasoningTokens": 1,
      "imageTokens": 1,
      "audioTokens": 1
    },
    "promptTokensDetails": {
      "cachedTokens": 1,
      "cacheWriteTokens": 1,
      "audioTokens": 1,
      "videoTokens": 1
    },
    "costDetails": {
      "upstreamInferenceCost": 1,
      "upstreamInferencePromptCost": 1,
      "upstreamInferenceCompletionCost": 1
    },
    "isByok": true
  },
  "error": {
    "code": "ERROR_CODE_CANCELLED",
    "message": "example",
    "isTerminal": true,
    "details": {}
  },
  "pendingClientTools": [
    {
      "id": "example_123",
      "name": "example",
      "argumentsJson": {
        "example": "value"
      },
      "status": "TOOL_EXECUTION_STATUS_PENDING",
      "resultJson": {
        "example": "value"
      },
      "executedAt": "2026-09-16T12:00:00Z",
      "serverId": "example_123",
      "isClientTool": true,
      "description": "example",
      "parametersJsonSchema": {
        "example": "value"
      },
      "requiresApprovalAt": "2026-09-16T12:00:00Z",
      "approvedAt": "2026-09-16T12:00:00Z",
      "approvedBy": "example",
      "executionDuration": "1s",
      "endReason": "example",
      "clientToolDeadlineAt": "2026-09-16T12:00:00Z"
    }
  ],
  "clientToolCursor": 1
}

Illustrative response for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-core-platform-scheduling-build-scheduled-agents-json-02-response

Response example

{
  "runId": "9d4c2e1f-...",
  "status": "AGENT_STATUS_COMPLETED",
  "messages": [
    {
      "role": "ROLE_ASSISTANT",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "Here is your daily briefing…"
        }
      ],
      "generatedBy": "9d4c2e1f-..."
    }
  ],
  "aggregateUsage": {
    "promptTokens": 412,
    "completionTokens": 88,
    "totalTokens": 500
  }
}

Illustrative response for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-managed-agents-conversations-generation-json-04-response

Response example

{
  "runId": "9d4c...",
  "status": "AGENT_STATUS_COMPLETED",
  "messages": [
    {
      "role": "ROLE_ASSISTANT",
      "content": [
        {
          "type": "CONTENT_PART_TYPE_TEXT",
          "content": "…"
        }
      ],
      "generatedBy": "9d4c..."
    }
  ],
  "aggregateUsage": {
    "promptTokens": 412,
    "completionTokens": 88,
    "totalTokens": 500
  }
}

Illustrative response for Recover a summary that failed or returned no explanation. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-managed-agents-conversations-generation-json-05-response

Response example

{
  "runId": "9d4c...",
  "status": "AGENT_STATUS_FAILED"
}

Illustrative response for Step 2: Ask to open the profile and retain the pending call. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-managed-agents-delegation-approvals-build-agent-with-tools-json-02-response

Response example

{
  "runId": "64403669-5989-4ec3-ad9c-d84223f9679f",
  "status": "AGENT_STATUS_AWAITING_CLIENT_TOOLS",
  "clientToolCursor": 1,
  "pendingClientTools": [
    {
      "id": "call_abc123",
      "name": "navigate_to",
      "argumentsJson": {
        "screen": "/profile"
      },
      "isClientTool": true,
      "clientToolDeadlineAt": "2026-08-10T10:04:11Z"
    }
  ]
}

Illustrative response for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.

Section ID: DOC-MA-conversations-api-sendMessageSync#example-cookbook-managed-agents-delegation-approvals-using-tools-json-02-response

Response example

{
  "runId": "cf9f08e7-4486-41e1-bac1-b9428d1aeb85",
  "status": "AGENT_STATUS_AWAITING_CLIENT_TOOLS",
  "clientToolCursor": 1,
  "pendingClientTools": [
    {
      "id": "call_306135",
      "name": "navigate_to",
      "argumentsJson": {
        "screen": "/profile"
      },
      "isClientTool": true,
      "clientToolDeadlineAt": "2026-09-02T06:43:24.304Z"
    }
  ]
}

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

Section	Stable reference
Send a message and wait for the result	`DOC-MA-conversations-api-sendMessageSync#overview`
Request	`DOC-MA-conversations-api-sendMessageSync#request`
Responses	`DOC-MA-conversations-api-sendMessageSync#responses`

Send a message and wait for the result

/api/v1/llm/send-message-sync

Request​

Responses​

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

Guide request for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.​

Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values.​

Guide request for 4. Run both configurations and retain their outcomes. Replace example resource identifiers with your own authorized values.​

Guide request for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.​

Guide request for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.​

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

Illustrative response for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.​

Illustrative response for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.​

Illustrative response for Recover a summary that failed or returned no explanation. Replace example resource identifiers with your own authorized values.​

Illustrative response for Step 2: Ask to open the profile and retain the pending call. Replace example resource identifiers with your own authorized values.​

Illustrative response for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.​

Request

Responses

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

Guide request for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.

Guide request for Verify that an in-app action returns control to the conversation. Replace example resource identifiers with your own authorized values.

Guide request for 4. Run both configurations and retain their outcomes. Replace example resource identifiers with your own authorized values.

Guide request for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.

Guide request for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.

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

Illustrative response for Step 3: Drive an agent turn from the callback. Replace example resource identifiers with your own authorized values.

Illustrative response for Separate recipe: wait for a backend summary in the response. Replace example resource identifiers with your own authorized values.

Illustrative response for Recover a summary that failed or returned no explanation. Replace example resource identifiers with your own authorized values.

Illustrative response for Step 2: Ask to open the profile and retain the pending call. Replace example resource identifiers with your own authorized values.

Illustrative response for Step 1: Receive the complete navigation call. Replace example resource identifiers with your own authorized values.