Create a response

POST /conversations/:id/response

Body Parameters

---

message string Required

The message to send to the conversation.

---

stream boolean

Whether to stream the response. When true, returns a stream of server-sent events. See the streaming guide for more details.

---

Response Type

type InconvoResponse = {
  id: string;
  conversationId: string;
  message: string;
  type: "text" | "chart" | "table";
  chart?: {
    $schema: 'https://vega.github.io/schema/vega-lite/v5.json'
  };
  table?: {
    head: string[];
    body: string[][];
  };
};

Request

Node.js

import Inconvo from "@inconvoai/node";

const inconvo = new Inconvo({
  apiKey: process.env.INCONVO_API_KEY
});

const response = await inconvo.conversations.response.create("convo_abc123", {
  message: "What is our most popular product?"
});

console.log(response);

Response

{
  "id": "57ad0f60-617d-4d4c-a2ed-63e3bf0413ff",
  "conversationId": "convo_abc123",
  "type": "text",
  "message": "Your most popular product is the iPhone 15, with a total of 24,840 orders."
}

curl -X POST "https://app.inconvo.ai/api/v1/conversations/convo_abc123/response" \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is our most popular product?"}'

Response

{
  "id": "57ad0f60-617d-4d4c-a2ed-63e3bf0413ff",
  "conversationId": "convo_abc123",
  "type": "text",
  "message": "Your most popular product is the iPhone 15, with a total of 24,840 orders."
}

Chart Example

Request

Node.js

const response = await inconvo.conversations.response.create("convo_abc123", {
  message: "Show me our revenue trend for this year."
});

curl -X POST 'https://app.inconvo.ai/api/v1/conversations/convo_abc123/response' \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"message": "Show me our revenue trend for this year."}'

Response

{
  "id": "19ab658b-94f7-45c1-97b7-777711446194",
  "conversationId": "convo_abc123",
  "type": "chart",
  "message": "Here’s your monthly revenue trend for last calendar year (2025), based on the total value of all orders for your organisation. Revenue increased steadily through the year, with the strongest month in October and a slight dip afterwards.",
  "chart": {
    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
    "description": "Monthly revenue trend for last calendar year",
    "data": {
      "values": [
        {
          "month": "2025-01",
          "revenue": 2894895.6800000053
        },
        {
          "month": "2025-02",
          "revenue": 2885349.179999997
        },
        {
          "month": "2025-03",
          "revenue": 3458996.8199999994
        },
        {
          "month": "2025-04",
          "revenue": 3773775.299999997
        },
        {
          "month": "2025-05",
          "revenue": 4402430.889999996
        },
        {
          "month": "2025-06",
          "revenue": 4548979.190000007
        },
        {
          "month": "2025-07",
          "revenue": 5201820.640000008
        },
        {
          "month": "2025-08",
          "revenue": 6217228.449999997
        },
        {
          "month": "2025-09",
          "revenue": 6982467.749999985
        },
        {
          "month": "2025-10",
          "revenue": 9350447.370000003
        },
        {
          "month": "2025-11",
          "revenue": 5860067.179999998
        }
      ]
    },
    "mark": {
      "type": "line",
      "point": true
    },
    "encoding": {
      "x": {
        "field": "month",
        "type": "ordinal",
        "title": "Month (2025)",
        "sort": "ascending",
        "axis": {
          "labelAngle": -40
        }
      },
      "y": {
        "field": "revenue",
        "type": "quantitative",
        "title": "Revenue (USD)"
      },
      "tooltip": [
        {
          "field": "month",
          "type": "ordinal",
          "title": "Month"
        },
        {
          "field": "revenue",
          "type": "quantitative",
          "title": "Revenue (USD)",
          "format": ",.0f"
        }
      ]
    }
  }
}

Table Example

Request

Node.js

const response = await inconvo.conversations.response.create("convo_abc123", {
  message: "What were my top 5 selling products last quarter?"
});

curl -X POST 'https://app.inconvo.ai/api/v1/conversations/convo_abc123/response' \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"message": "What were my top 5 selling products last quarter?"}'

Response

{
  "id": "2dc27a80-5ef9-4d6a-b1a4-c0f45f5f8aba",
  "conversationId": "convo_abc123",
  "type": "table",
  "message": "Here are your top 5 selling products from last quarter:",
  "table": {
    "head": [
      "Product",
      "Units Sold"
    ],
    "body": [
      [
        "iPhone 15",
        "4366"
      ],
      [
        "MacBook Pro",
        "1793"
      ],
      [
        "AirPods Pro",
        "1354"
      ],
      [
        "iPad Pro",
        "1212"
      ],
      [
        "Apple Watch",
        "1019"
      ]
    ]
  }
}