Converse API

The Converse API sends messages to agents. Use it to start or continue conversations.

Endpoint

POST /api/v1/agents/:slug/converse

Headers

Header	Required	Description
Content-Type	Yes	application/json
tenant-id	Yes	Tenant identifier
user-id	No	External user id (fallback)
x-request-id	No	Trace id

Path Parameters

Parameter	Required	Description
slug	Yes	Agent slug

Request Body

{
  "message": "string",
  "conversation_id": "uuid",
  "context": {
    "version": "v1",
    "context": {
      "identity": {
        "user_id": "u_123",
        "user_name": "Jane Lee",
        "user_email": "jane@example.com"
      },
      "preferences": {"language": "en"},
      "entitlements": {"tier": "premium"},
      "customAttributes": {"account_id": "acct_789"}
    }
  }
}

Required Fields

• message
• context.identity.user_id (recommended)

If context.identity.user_id is missing, the platform uses the user-id header as a fallback.

Starting A New Conversation

curl -X POST https://api.example.com/api/v1/agents/support-assistant/converse \
  -H "Content-Type: application/json" \
  -H "tenant-id: your-tenant-id" \
  -d '{
    "message": "I need help with my order",
    "context": {
      "version": "v1",
      "context": {
        "identity": {"user_id": "u_123"}
      }
    }
  }'

Continuing A Conversation

curl -X POST https://api.example.com/api/v1/agents/support-assistant/converse \
  -H "Content-Type: application/json" \
  -H "tenant-id: your-tenant-id" \
  -d '{
    "conversation_id": "e0c1f7b4-7b45-4a24-9f4b-1f5d6f5a3fdd",
    "message": "The order ID is ORD-12345"
  }'

Response

{
  "conversation_id": "e0c1f7b4-7b45-4a24-9f4b-1f5d6f5a3fdd",
  "response": {
    "message": "I found your order. It is in transit.",
    "phase": "phase_collect",
    "awaiting_input": true,
    "options": []
  },
  "state": {
    "status": "active",
    "capability": "check-order-status"
  }
}

Status Values

active, paused, completed, escalated, abandoned