Create Conversation

POST /agents/{agentId}/conversations

Path Parameters

---

agentId string Required

The agent id

---

Body Parameters

---

userIdentifier string Required

A unique identifier for the end-user (1-256 characters). This is used to scope datasets and conversations to specific users. Allowed characters: alphanumeric, underscore, hyphen, colon, period, or at symbol.
Examples: user_123, john.doe@example.com, org:tenant-456

userContext object

An optional object used for additional context—commonly used for multi-tenant filtering. Each key-value pair can be used to apply data filters across your schema. For example, pass {"organisationId": 1} to ensure that queries only use data from that organisation to inform responses. This assumes a context filter has been configured on relevant tables. Context values can also be used for context-scoped datasets.

---

Request

Node.js

import Inconvo from "@inconvoai/node";

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

const conversation = await inconvo.agents.conversations.create(
  "agt_123",
  {
    userIdentifier: "user_123",
    userContext: {
      organisationId: 1
    }
  }
);

console.log(conversation);

Response

{
  "id": "convo_2c4d3456-e1f7-4d36-a8fd-f5cf15491d00"
}

curl -X POST "https://app.inconvo.ai/api/v1/agents/agt_123/conversations" \
  -H "Authorization: Bearer $INCONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userIdentifier": "user_123",
    "userContext": {
      "organisationId": 1
    }
  }'

Response

{
  "id": "convo_2c4d3456-e1f7-4d36-a8fd-f5cf15491d00"
}