---
title: "Capture Interactions and Messages"
method: POST
path: "/messages"
tags: ["Interactions"]
---

# Capture Interactions and Messages

`POST /messages`

Send us your AI conversations so we can analyze them for you. Works with everything from simple chatbots to complex agentic systems — text or voice.

**Getting Started (Simple Chat):**
Just provide the `role` ("user", "assistant", or "system") and `content` for each message, along with an `externalConversationId` and your `productId`. That's it!

**Advanced Usage (Agentic Workflows):**
Capture the full execution trace of your AI agents using `messageType` for tool calls, thoughts, observations, and more. Include structured data via `input`/`output` fields to track what your agents are doing.

**Voice Agents:**
For voice conversations, include a `voiceCall` object on the request (call duration, recording URL, ended reason, latency stats, structured outputs) and a `voice` object on each message (per-turn timing, ASR confidence, prosody, interruption signals). Native webhook integrations are available for Vapi, Retell, ElevenLabs, Bland AI, Synthflow, and Simple.ai — point your provider at `/v1/integrations/<provider>?productId=<uuid>` and we'll handle the transform. See the voice example below for the canonical shape.

**Key Features:**
- **Automatic Ordering:** Messages are stored with sequential timestamps, or provide your own `createdAt` timestamps for historical data.
- **Threading:** Create nested conversations by referencing parent messages using `parentMessageId` or `parentExternalMessageId`.
- **Organization Tracking:** Associate users with organizations via `externalOrganizationId`. We'll create the organization automatically if it doesn't exist.
- **Automatic De-duplication:** Messages with an `externalMessageId` that already exists in the conversation are automatically skipped. This allows you to safely resend a batch of messages with new messages appended — previously ingested messages will be deduplicated and only new messages will be inserted. Each message in the response includes a `status` field ("created" or "deduplicated") so you know what happened.

Perfect for understanding how your AI is performing in production and identifying areas for improvement.

## Request body

- MessagesRequest — Request payload for logging conversations and messages.
  - `productId` string, uuid — The Greenflash product this conversation belongs to. Either conversationId, externalConversationId, productId must be provided.
  - `conversationId` string, uuid — The Greenflash conversation ID. When provided, updates an existing conversation instead of creating a new one. Either conversationId, externalConversationId, productId must be provided.
  - `externalConversationId` string — Your external identifier for the conversation. Either conversationId, externalConversationId, productId must be provided.
  - `externalUserId` string, required — Your external user ID that will be mapped to a user in our system.
  - `externalOrganizationId` string — Your unique identifier for the organization this user belongs to. If provided, the user will be associated with this organization.
  - `model` string — The AI model used for the conversation.
  - `properties` object — Additional data about the conversation.
  - `systemPrompt` union — System prompt for the conversation. Can be a simple string or a prompt object with components.
    - string — System prompt as a simple string (will be converted to a prompt object).
    - SystemPromptObject — System prompt as a prompt object. Can reference an existing prompt by ID or define new components inline.
      - `promptId` string, uuid — Greenflash's internal prompt ID. Can be used to reference an existing prompt created via system prompt APIs.
      - `externalPromptId` string — Your external identifier for the prompt. Can be used to reference an existing prompt created via system prompt APIs.
      - `content` string — Simple string content (shorthand for a single system component). Mutually exclusive with components.
      - `components` ComponentInput[] — Array of component objects. When provided with promptId/externalPromptId, will upsert the prompt. When omitted with promptId/externalPromptId, will reference an existing prompt.
        - `content` string, required — The content of the component.
        - `componentId` string, uuid — The Greenflash component ID.
        - `externalComponentId` string — Your external identifier for the component.
        - `type` 'system' | 'user' | 'tool' | 'guardrail' | 'rag' | 'agent' | 'other' — Component type: system, user, tool, guardrail, rag, agent, or a custom type (other).
        - `source` 'customer' | 'participant' | 'greenflash' | 'agent' — Component source: customer, participant, greenflash, or agent.
        - `name` string — Component name.
        - `isDynamic` boolean — Whether the component content changes dynamically.
      - `variables` object — Template variables for {{placeholder}} interpolation in component content.
  - `sampleRate` number — Controls the percentage of requests that are ingested (0.0 to 1.0). For example, 0.1 means 10% of requests will be stored. Defaults to 1.0 (all requests ingested). Sampling is deterministic based on conversation ID.
  - `forceSample` boolean — When true, bypasses sampling and ensures this request is always ingested regardless of sampleRate. Use for critical conversations that must be captured.
  - `voiceCall` VoiceCall — Voice-specific signals for the full call/conversation (platform, duration, latency aggregates, recording URL, etc.). Stored on the conversation alongside `properties` and analyzed by voice-aware pipelines.
    - `platform` 'vapi' | 'retell' | 'elevenlabs' | 'openai_realtime' | 'livekit' | 'bland' | 'synthflow' | 'simpleai' | 'other' — Identifier of the voice platform that produced the call.
    - `platformCallId` string — The voice platform’s native call ID. Useful for cross-referencing back to the source.
    - `durationMs` integer — Total call duration in milliseconds.
    - `recordingUrl` string, uri — Optional URL to the full call recording. Greenflash does not store audio; the URL is embedded in the UI as a pass-through.
    - `endedReason` string — How the call ended (platform-specific string, e.g. "user_hangup", "assistant_hangup", "timeout").
    - `latency` VoiceCallLatency — Component and end-to-end latency aggregates for the call.
      - `asrMs` integer — Average ASR (speech-to-text) latency in ms.
      - `llmMs` integer — Average LLM inference latency in ms.
      - `ttsMs` integer — Average TTS (text-to-speech) latency in ms.
      - `e2eMs` integer — Average end-to-end latency from user end-of-turn to agent first audio (ms).
    - `interruptionCount` integer — Number of barge-ins / interruptions detected over the call.
    - `silenceCount` integer — Number of long silence segments detected over the call.
    - `callSuccessful` boolean — Optional platform-supplied success determination (e.g. Retell’s `call_successful`).
    - `structuredOutputs` object — Optional structured data extracted from the call by the platform (e.g. Vapi structured outputs, Retell custom analysis data).
  - `messages` MessageItem[], required — Array of conversation messages.
    - `externalMessageId` string — Your external identifier for this message. Used to reference the message in other API calls.
    - `role` 'user' | 'assistant' | 'system' — Simple message role for basic chat: user, assistant, or system. Cannot be used with messageType.
    - `messageType` 'user_message' | 'assistant_message' | 'system_message' | 'final_response' | 'thought' | 'tool_call' | 'observation' | 'retrieval' | 'memory_read' | 'memory_write' | 'chain_start' | 'chain_end' | 'embedding' | 'tool_error' | 'callback' | 'llm' | 'task' | 'workflow' — Detailed message type for agentic workflows. Cannot be used with role. Available types: user_message, assistant_message, system_message, final_response, thought, tool_call, observation, retrieval, memory_read, memory_write, chain_start, chain_end, embedding, tool_error, callback, llm, task, workflow
    - `content` string — The message content. Required for language-based analyses.
    - `context` string, nullable — Additional context (e.g., RAG data) used to generate the message.
    - `toolName` string — Name of the tool being called. Required for tool_call messages.
    - `input` object — Structured input data for tool calls, retrievals, or other operations.
    - `output` object — Structured output data from tool calls, retrievals, or other operations.
    - `parentMessageId` string, uuid — The internal ID of the parent message for threading. Cannot be used with parentExternalMessageId.
    - `parentExternalMessageId` string — The external ID of the parent message for threading. Cannot be used with parentMessageId.
    - `properties` object — Custom message properties.
    - `model` string — The AI model used for this specific message. Use for multi-agent scenarios where different messages use different models. Overrides the conversation-level model for this message.
    - `createdAt` string, date, nullable — When this message was created. Accepts a Date or an ISO-8601 string. If not provided, messages get sequential timestamps. Use for importing historical data — and required when you want the voice analysis pipeline to derive response-latency / silence-before signals from inter-message gaps on uninstrumented voice transcripts.
    - `voice` VoiceTurn — Voice-specific signals for this turn (latency, interruption, ASR confidence, prosody, etc.). Stored alongside `properties` and analyzed by voice-aware pipelines.
      - `startedAt` integer — When this turn started speaking, as Unix epoch milliseconds.
      - `endedAt` integer — When this turn finished speaking, as Unix epoch milliseconds.
      - `durationMs` integer — Length of this turn in milliseconds.
      - `speaker` string — Optional speaker label (e.g. "agent", "user", or a diarization-assigned ID like "Speaker 0").
      - `asrConfidence` number — ASR transcription confidence for this turn, 0 (uncertain) to 1 (fully confident).
      - `responseLatencyMs` integer — Time between the previous speaker ending and this turn starting (ms). Useful for measuring agent response latency.
      - `wasInterrupted` boolean — True when this turn was cut off by the other speaker.
      - `bargeIn` boolean — True when this turn began while the other speaker was still talking (a barge-in / overlap).
      - `silenceBeforeMs` integer — Silence duration immediately before this turn (ms).
      - `audioUrl` string, uri — Optional URL to the audio segment for this turn. Greenflash does not store audio; the URL is embedded in the UI as a pass-through.
      - `prosody` VoiceProsody — Optional prosody / tone signals from upstream voice infrastructure (Deepgram, Hume, Retell, etc.).
        - `sentimentScore` number — Prosody-derived sentiment score from -1 (negative) to 1 (positive). Distinct from text-derived sentiment — captures tone/intonation rather than word choice.
        - `sentimentLabel` 'positive' | 'neutral' | 'negative' — Prosody-derived sentiment label.
        - `arousal` number — Vocal energy / intensity, 0 (calm) to 1 (highly energetic).
        - `emotion` string — Optional fine-grained emotion label provided by an upstream prosody model.

## Response `200`

Messages logged successfully

- MessagesResponse — Success response for message logging.
  - `success` boolean, required — Whether the API call was successful.
  - `conversationId` string, uuid, required — The ID of the conversation that was created or updated.
  - `systemPromptPromptId` string, uuid, required — The prompt ID used internally to track the system prompt.
  - `systemPromptComponentIds` string[], required — The component IDs used internally to track the system prompt components.
  - `messages` object[], required — The messages that were processed.
    - `messageId` string, required — The internal Greenflash message ID.
    - `externalMessageId` string — Your external identifier for the message, if provided.
    - `messageType` string, required — The type of the message that was created.
    - `status` 'created' | 'deduplicated', required — Whether the message was newly created or deduplicated. Messages with an externalMessageId that already exists in the conversation are automatically skipped and returned with status "deduplicated".
  - `promptVariables` object — Template variables used or detected for this conversation.
  - `templateMatch` object — Template match info when content was auto-matched against an existing template.
    - `matched` boolean, required
    - `confidence` 'exact' | 'high' | 'medium'
    - `promptId` string, uuid
    - `detectedVariables` object

## Other responses

- `429` — Rate limit exceeded
- `500` — Server error

## Changes

- **2026-05-01** `c566e560677d` — 3 info
  - added the new optional request property `messages/items/voice`
  - added the new optional request property `voiceCall`
  - the request property `messages/items/createdAt` became nullable
- **2026-03-12** `51d576458472` — 1 breaking
  - the `messages/items/createdAt` request property type/format changed from `string`/`date-time` to `string`/`date`
- **2026-02-18** `3ecf972e1294` — 1 breaking, 1 info
  - removed `#/components/schemas/SystemPrompt` from the `systemPrompt` request property `anyOf` list
  - added `#/components/schemas/SystemPromptObject` to the `systemPrompt` request property `anyOf` list
- **2026-02-18** `d5edd18f9685` — 5 info
  - added the new optional request property `messages/items/model`
  - the `messages/items/createdAt` request property type/format was generalized from `string`/`date` to `string`/`date-time`
  - added the optional property `promptVariables` to the response with the `200` status
  - added the optional property `templateMatch` to the response with the `200` status
  - …1 more
- **2025-12-12** `b43d4cbb1301` — 2 info
  - added the new optional request property `forceSample`
  - added the new optional request property `sampleRate`

[Full history](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/changes/messages/post.md)

---

[API](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference.md) · [All operations](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenflash-ai/greenflash-api-reference/revisions/c566e560677d/schema)