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

cURL

curl --request POST \
  --url https://www.greenflash.ai/api/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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."
    }
  ]
}
'

{
  "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"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request payload for logging conversations and messages.

externalUserId

string

required

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

messages

object[]

required

Array of conversation messages.

Minimum array length: 1

Show child attributes

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.

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.

Show child attributes

systemPrompt

System prompt for the conversation. Can be a simple string or a prompt object with components.

Minimum string length: 1

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.

Required range: 0 <= x <= 1

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

object

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.

Show child attributes

Response

Messages logged successfully

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<uuid>[]

required

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

messages

object[]

required

The messages that were processed.

Show child attributes

promptVariables

object

Template variables used or detected for this conversation.

Show child attributes

templateMatch

object

Template match info when content was auto-matched against an existing template.

Show child attributes

Capture User Feedback and RatingsRecord user feedback and ratings for conversations or individual messages. Use this endpoint to collect feedback about response quality or overall conversation experiences. You can rate either a specific message (using `messageId` or `externalMessageId`) or an entire conversation (using `conversationId` or `externalConversationId`).

cURL

curl --request POST \
  --url https://www.greenflash.ai/api/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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."
    }
  ]
}
'

{
  "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"
    }
  ]
}