Sign in

v28

latestOpenAPI 3.1.0raw.githubusercontent.com2026-05-013593344.3 KB
Interactions

Capture Interactions and 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.

post/messages

Request body

productIdstring uuid

The Greenflash product this conversation belongs to. Either conversationId, externalConversationId, productId must be provided.

conversationIdstring uuid

The Greenflash conversation ID. When provided, updates an existing conversation instead of creating a new one. Either conversationId, externalConversationId, productId must be provided.

externalConversationIdstring

Your external identifier for the conversation. Either conversationId, externalConversationId, productId must be provided.

externalUserIdstring required

Your external user ID that will be mapped to a user in our system.

externalOrganizationIdstring

Your unique identifier for the organization this user belongs to. If provided, the user will be associated with this organization.

modelstring

The AI model used for the conversation.

propertiesobject

Additional data about the conversation.

sampleRatenumber

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.

forceSampleboolean

When true, bypasses sampling and ensures this request is always ingested regardless of sampleRate. Use for critical conversations that must be captured.

Response

Messages logged successfully

successboolean required

Whether the API call was successful.

conversationIdstring uuid required

The ID of the conversation that was created or updated.

systemPromptPromptIdstring uuid required

The prompt ID used internally to track the system prompt.

systemPromptComponentIdsstring[] required

The component IDs used internally to track the system prompt components.

promptVariablesobject

Template variables used or detected for this conversation.

All 35 operations