---
title: "Run an agent (send a message)"
method: POST
path: "/public/v1/agents/{agentId}/messages"
tags: ["Agents"]
---

# Run an agent (send a message)

`POST /public/v1/agents/{agentId}/messages`

Sends a message to an agent and returns its reply — the same way the in-app Overview/Playground tests an agent and its flow (runs over the OVERVIEW channel, against the active OR draft flow). Omit `message` on a new conversation to just open it and run the Start flow; pass `conversation_id` + `message` to continue. Requires a USER API key.

## Path parameters

- `agentId` string, required

## Request body

- PublicAgentMessageInput
  - `message` string — The message to send. Omit on a NEW conversation to just open it and run the agent's Start flow (like the Overview/Playground). Required when continuing an existing conversation (conversation_id present).
  - `conversation_id` integer — Continue an existing conversation. Omit to start a new one.
  - `contact_id` string — Link the conversation to a People (contact) record.
  - `initial_variables` object — Variables to seed the conversation with when starting a new one (HMAC is computed server-side).

## Response `201`

The agent's reply messages and the conversation id

- PublicAgentRunOutput
  - `conversation_id` number, nullable
  - `messages` PublicAgentRunMessage[], required
    - `id` number, nullable
    - `role` 'USER' | 'ASSISTANT' | 'SYSTEM', required
    - `type` 'MESSAGE' | 'TRIGGER_INTENT' | 'RESPONSE_AI' | 'SAY_AI' | 'API' | 'ENTER_FLOW' | 'EXIT_FLOW' | 'ERROR_MESSAGE' | 'SET_VARIABLES' | 'OFF_TOPIC' | 'CONVERSATION_ENDED' | 'CONVERSATION_IDLE' | 'CONDITIONAL_ROUTING' | 'PROCESSED_MEDIA_WITH_AI' | 'AGENT_TOOL' | 'START_CONVERSATION' | 'WHATSAPP_TEMPLATE_MESSAGE' | 'WHATSAPP_FLOW_COMPLETED' | 'MESSAGE_REACTION' | 'CHANNEL_CONTEXT' | 'ABORTED_MESSAGE' | 'MAX_PLAN_PROPOSED' | 'MAX_PLAN_STARTED' | 'MAX_PLAN_COMPLETED' | 'MAX_PLAN_CANCELLED' | 'MAX_PLAN_QUESTIONS_PROPOSED' | 'MAX_PLAN_QUESTIONS_RESOLVED', required
    - `text` string, required
    - `created_at` string, nullable

---

[API](https://skmtc.net/getfrontline/apis/public-api.md) · [All operations](https://skmtc.net/getfrontline/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getfrontline/public-api/revisions/9d33b6aad674/schema)