> ## Documentation Index > Fetch the complete documentation index at: https://docs.greenflash.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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/?productId=` 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. ## OpenAPI ````yaml https://www.greenflash.ai/api/openapi post /messages openapi: 3.1.0 info: title: Greenflash API Reference version: 1.0.0 description: >- Greenflash endpoints for capturing interactions, managing prompts, and identifying users. servers: - url: https://www.greenflash.ai/api/v1 description: Greenflash API v1 security: [] tags: - name: Interactions description: Capture interactions between users and AI - name: Business Events description: Capture business events - name: Analytics description: Understand chat and agentic interactions analyses - name: Inbox description: Review flagged conversations - name: Segments description: Manage user segments - name: Prompts description: Manage prompts - name: Chat description: Stream chat and agentic conversations - name: Models description: Manage AI models - name: Products description: Manage products - name: Users description: Manage users - name: Organizations description: Manage organizations paths: /messages: post: tags: - Interactions summary: Capture Interactions and Messages description: >- 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/?productId=` 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. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MessagesRequest' examples: Text agent: summary: Standard chat / agentic workflow value: externalUserId: user-123 externalOrganizationId: org-789 externalConversationId: conv-456 productId: 123e4567-e89b-12d3-a456-426614174001 versionId: 123e4567-e89b-12d3-a456-426614174003 model: gpt-greenflash-1 properties: campaign: summer-sale systemPrompt: promptId: 123e4567-e89b-12d3-a456-426614174004 components: - content: You are a helpful assistant. type: system source: customer messages: - externalMessageId: user-msg-1 role: user content: Hello! - externalMessageId: assistant-msg-1 role: assistant content: Hi there! How can I help you? - externalMessageId: tool-call-1 messageType: tool_call content: Calling search tool toolName: web_search input: query: weather forecast - externalMessageId: tool-result-1 messageType: observation content: Search completed output: results: - Sunny, 75°F parentExternalMessageId: tool-call-1 - externalMessageId: final-1 messageType: final_response content: >- Based on the search, today will be sunny with a high of 75°F. Voice agent: summary: >- Voice call (Vapi/Retell/ElevenLabs/Bland/Synthflow/Simple.ai or DIY) value: externalUserId: '+15555550100' externalConversationId: call_abc123 productId: 123e4567-e89b-12d3-a456-426614174001 properties: campaign: inbound-sales voiceCall: platform: vapi platformCallId: call_abc123 durationMs: 47500 recordingUrl: https://recordings.example.com/call_abc123.mp3 endedReason: customer-ended-call latency: e2eMs: 950 asrMs: 220 llmMs: 480 ttsMs: 250 callSuccessful: true structuredOutputs: booked: true intent: demo messages: - externalMessageId: call_abc123:0 role: assistant content: Hi, this is Aria — how can I help you today? voice: startedAt: 1700000000000 endedAt: 1700000002400 durationMs: 2400 speaker: agent responseLatencyMs: 0 - externalMessageId: call_abc123:1 role: user content: I'd like to book a demo. voice: startedAt: 1700000003100 endedAt: 1700000004900 durationMs: 1800 speaker: user asrConfidence: 0.97 silenceBeforeMs: 700 prosody: sentimentLabel: positive sentimentScore: 0.6 arousal: 0.4 responses: '200': description: Messages logged successfully content: application/json: schema: $ref: '#/components/schemas/MessagesResponse' example: success: true conversationId: 123e4567-e89b-12d3-a456-426614174000 systemPromptPromptId: 123e4567-e89b-12d3-a456-426614174004 systemPromptComponentIds: - 123e4567-e89b-12d3-a456-426614174005 - 123e4567-e89b-12d3-a456-426614174006 messages: - messageId: msg-001 externalMessageId: user-msg-1 messageType: user_message status: created - messageId: msg-002 externalMessageId: assistant-msg-1 messageType: assistant_message status: created - messageId: msg-003 externalMessageId: tool-call-1 messageType: tool_call status: created - messageId: msg-004 externalMessageId: tool-result-1 messageType: observation status: created - messageId: msg-005 externalMessageId: final-1 messageType: final_response status: created '429': description: Rate limit exceeded content: application/json: schema: type: object properties: success: type: boolean description: Whether the API call was successful (false for errors). error: type: string description: Error message describing what went wrong. description: Error response for message logging operations. example: success: false error: Rate limit exceeded. Please try again later. '500': description: Server error content: application/json: schema: type: object properties: success: type: boolean description: Whether the API call was successful (false for errors). error: type: string description: Error message describing what went wrong. description: Error response for message logging operations. example: success: false error: Internal server error security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: |- import Greenflash from 'greenflash'; const client = new Greenflash({ apiKey: process.env['GREENFLASH_API_KEY'], // This is the default and can be omitted }); const createMessageResponse = await client.messages.create({ externalUserId: 'user-123', messages: [ { externalMessageId: 'user-msg-1', role: 'user', content: 'Hello!', }, { externalMessageId: 'assistant-msg-1', role: 'assistant', content: 'Hi there! How can I help you?', }, { externalMessageId: 'tool-call-1', messageType: 'tool_call', content: 'Calling search tool', toolName: 'web_search', input: { query: 'weather forecast' }, }, { externalMessageId: 'tool-result-1', messageType: 'observation', content: 'Search completed', output: { results: ['Sunny, 75°F'] }, parentExternalMessageId: 'tool-call-1', }, { externalMessageId: 'final-1', messageType: 'final_response', content: 'Based on the search, today will be sunny with a high of 75°F.', }, ], externalConversationId: 'conv-456', externalOrganizationId: 'org-789', model: 'gpt-greenflash-1', productId: '123e4567-e89b-12d3-a456-426614174001', properties: { campaign: 'summer-sale' }, systemPrompt: { promptId: '123e4567-e89b-12d3-a456-426614174004', components: [ { content: 'You are a helpful assistant.', type: 'system', source: 'customer', }, ], }, }); console.log(createMessageResponse.conversationId); - lang: Python source: |- import os from greenflash import Greenflash client = Greenflash( api_key=os.environ.get("GREENFLASH_API_KEY"), # This is the default and can be omitted ) create_message_response = client.messages.create( external_user_id="user-123", messages=[{ "external_message_id": "user-msg-1", "role": "user", "content": "Hello!", }, { "external_message_id": "assistant-msg-1", "role": "assistant", "content": "Hi there! How can I help you?", }, { "external_message_id": "tool-call-1", "message_type": "tool_call", "content": "Calling search tool", "tool_name": "web_search", "input": { "query": "weather forecast" }, }, { "external_message_id": "tool-result-1", "message_type": "observation", "content": "Search completed", "output": { "results": ["Sunny, 75°F"] }, "parent_external_message_id": "tool-call-1", }, { "external_message_id": "final-1", "message_type": "final_response", "content": "Based on the search, today will be sunny with a high of 75°F.", }], external_conversation_id="conv-456", external_organization_id="org-789", model="gpt-greenflash-1", product_id="123e4567-e89b-12d3-a456-426614174001", properties={ "campaign": "summer-sale" }, system_prompt={ "prompt_id": "123e4567-e89b-12d3-a456-426614174004", "components": [{ "content": "You are a helpful assistant.", "type": "system", "source": "customer", }], }, ) print(create_message_response.conversation_id) components: schemas: MessagesRequest: type: object properties: productId: type: string format: uuid description: >- The Greenflash product this conversation belongs to. Either conversationId, externalConversationId, productId must be provided. conversationId: type: string format: uuid description: >- The Greenflash conversation ID. When provided, updates an existing conversation instead of creating a new one. Either conversationId, externalConversationId, productId must be provided. externalConversationId: type: string description: >- Your external identifier for the conversation. Either conversationId, externalConversationId, productId must be provided. externalUserId: type: string description: Your external user ID that will be mapped to a user in our system. externalOrganizationId: type: string description: >- Your unique identifier for the organization this user belongs to. If provided, the user will be associated with this organization. model: type: string description: The AI model used for the conversation. properties: type: object additionalProperties: {} description: Additional data about the conversation. systemPrompt: $ref: '#/components/schemas/SystemPrompt' sampleRate: type: number minimum: 0 maximum: 1 description: >- 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: type: boolean description: >- When true, bypasses sampling and ensures this request is always ingested regardless of sampleRate. Use for critical conversations that must be captured. voiceCall: $ref: '#/components/schemas/VoiceCall' messages: type: array items: $ref: '#/components/schemas/MessageItem' minItems: 1 description: Array of conversation messages. required: - externalUserId - messages description: Request payload for logging conversations and messages. MessagesResponse: type: object properties: success: type: boolean description: Whether the API call was successful. conversationId: type: string format: uuid description: The ID of the conversation that was created or updated. systemPromptPromptId: type: string format: uuid description: The prompt ID used internally to track the system prompt. systemPromptComponentIds: type: array items: type: string format: uuid description: >- The component IDs used internally to track the system prompt components. messages: type: array items: type: object properties: messageId: type: string description: The internal Greenflash message ID. externalMessageId: type: string description: Your external identifier for the message, if provided. messageType: type: string description: The type of the message that was created. status: type: string enum: - created - deduplicated description: >- 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". required: - messageId - messageType - status description: The messages that were processed. promptVariables: type: object additionalProperties: type: string description: Template variables used or detected for this conversation. templateMatch: type: object properties: matched: type: boolean confidence: type: string enum: - exact - high - medium promptId: type: string format: uuid detectedVariables: type: object additionalProperties: type: string required: - matched description: >- Template match info when content was auto-matched against an existing template. required: - success - conversationId - systemPromptPromptId - systemPromptComponentIds - messages description: Success response for message logging. SystemPrompt: anyOf: - $ref: '#/components/schemas/SystemPromptString' - $ref: '#/components/schemas/SystemPromptObject' description: >- System prompt for the conversation. Can be a simple string or a prompt object with components. VoiceCall: type: object properties: platform: type: string enum: - vapi - retell - elevenlabs - openai_realtime - livekit - bland - synthflow - simpleai - other description: Identifier of the voice platform that produced the call. platformCallId: type: string description: >- The voice platform’s native call ID. Useful for cross-referencing back to the source. durationMs: type: integer minimum: 0 description: Total call duration in milliseconds. recordingUrl: type: string format: uri description: >- Optional URL to the full call recording. Greenflash does not store audio; the URL is embedded in the UI as a pass-through. endedReason: type: string description: >- How the call ended (platform-specific string, e.g. "user_hangup", "assistant_hangup", "timeout"). latency: $ref: '#/components/schemas/VoiceCallLatency' interruptionCount: type: integer minimum: 0 description: Number of barge-ins / interruptions detected over the call. silenceCount: type: integer minimum: 0 description: Number of long silence segments detected over the call. callSuccessful: type: boolean description: >- Optional platform-supplied success determination (e.g. Retell’s `call_successful`). structuredOutputs: type: object additionalProperties: {} description: >- Optional structured data extracted from the call by the platform (e.g. Vapi structured outputs, Retell custom analysis data). description: >- 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. MessageItem: type: object properties: externalMessageId: type: string description: >- Your external identifier for this message. Used to reference the message in other API calls. role: type: string enum: - user - assistant - system description: >- Simple message role for basic chat: user, assistant, or system. Cannot be used with messageType. messageType: type: string enum: - 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 description: >- 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: type: string description: The message content. Required for language-based analyses. context: type: - string - 'null' description: Additional context (e.g., RAG data) used to generate the message. toolName: type: string description: Name of the tool being called. Required for tool_call messages. input: type: object additionalProperties: {} description: >- Structured input data for tool calls, retrievals, or other operations. output: type: object additionalProperties: {} description: >- Structured output data from tool calls, retrievals, or other operations. parentMessageId: type: string format: uuid description: >- The internal ID of the parent message for threading. Cannot be used with parentExternalMessageId. parentExternalMessageId: type: string description: >- The external ID of the parent message for threading. Cannot be used with parentMessageId. properties: type: object additionalProperties: {} description: Custom message properties. model: type: string description: >- 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: type: - string - 'null' format: date description: >- 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: $ref: '#/components/schemas/VoiceTurn' SystemPromptString: type: string minLength: 1 description: System prompt as a simple string (will be converted to a prompt object). SystemPromptObject: type: object properties: promptId: type: string format: uuid description: >- Greenflash's internal prompt ID. Can be used to reference an existing prompt created via system prompt APIs. externalPromptId: type: string description: >- Your external identifier for the prompt. Can be used to reference an existing prompt created via system prompt APIs. content: type: string minLength: 1 description: >- Simple string content (shorthand for a single system component). Mutually exclusive with components. components: type: array items: $ref: '#/components/schemas/ComponentInput' description: >- Array of component objects. When provided with promptId/externalPromptId, will upsert the prompt. When omitted with promptId/externalPromptId, will reference an existing prompt. variables: type: object additionalProperties: type: string description: >- Template variables for {{placeholder}} interpolation in component content. description: >- System prompt as a prompt object. Can reference an existing prompt by ID or define new components inline. VoiceCallLatency: type: object properties: asrMs: type: integer minimum: 0 description: Average ASR (speech-to-text) latency in ms. llmMs: type: integer minimum: 0 description: Average LLM inference latency in ms. ttsMs: type: integer minimum: 0 description: Average TTS (text-to-speech) latency in ms. e2eMs: type: integer minimum: 0 description: >- Average end-to-end latency from user end-of-turn to agent first audio (ms). description: Component and end-to-end latency aggregates for the call. VoiceTurn: type: object properties: startedAt: type: integer minimum: 0 description: When this turn started speaking, as Unix epoch milliseconds. endedAt: type: integer minimum: 0 description: When this turn finished speaking, as Unix epoch milliseconds. durationMs: type: integer minimum: 0 description: Length of this turn in milliseconds. speaker: type: string description: >- Optional speaker label (e.g. "agent", "user", or a diarization-assigned ID like "Speaker 0"). asrConfidence: type: number minimum: 0 maximum: 1 description: >- ASR transcription confidence for this turn, 0 (uncertain) to 1 (fully confident). responseLatencyMs: type: integer minimum: 0 description: >- Time between the previous speaker ending and this turn starting (ms). Useful for measuring agent response latency. wasInterrupted: type: boolean description: True when this turn was cut off by the other speaker. bargeIn: type: boolean description: >- True when this turn began while the other speaker was still talking (a barge-in / overlap). silenceBeforeMs: type: integer minimum: 0 description: Silence duration immediately before this turn (ms). audioUrl: type: string format: uri description: >- 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: $ref: '#/components/schemas/VoiceProsody' description: >- Voice-specific signals for this turn (latency, interruption, ASR confidence, prosody, etc.). Stored alongside `properties` and analyzed by voice-aware pipelines. ComponentInput: type: object properties: content: type: string minLength: 1 description: The content of the component. componentId: type: string format: uuid description: The Greenflash component ID. externalComponentId: type: string description: Your external identifier for the component. type: type: string enum: - system - user - tool - guardrail - rag - agent - other default: system description: >- Component type: system, user, tool, guardrail, rag, agent, or a custom type (other). source: type: string enum: - customer - participant - greenflash - agent default: customer description: 'Component source: customer, participant, greenflash, or agent.' name: type: string description: Component name. isDynamic: type: boolean description: Whether the component content changes dynamically. required: - content VoiceProsody: type: object properties: sentimentScore: type: number minimum: -1 maximum: 1 description: >- Prosody-derived sentiment score from -1 (negative) to 1 (positive). Distinct from text-derived sentiment — captures tone/intonation rather than word choice. sentimentLabel: type: string enum: - positive - neutral - negative description: Prosody-derived sentiment label. arousal: type: number minimum: 0 maximum: 1 description: Vocal energy / intensity, 0 (calm) to 1 (highly energetic). emotion: type: string description: >- Optional fine-grained emotion label provided by an upstream prosody model. description: >- Optional prosody / tone signals from upstream voice infrastructure (Deepgram, Hume, Retell, etc.). securitySchemes: bearerAuth: type: http scheme: bearer ````