Conversations API

The Conversations API allows you to create, retrieve, and manage conversations and messages programmatically.

Endpoints

POST /api/conversations/get_or_create
POST /api/conversations/:id/message
GET /api/conversations/:id/messages
PATCH /api/conversations/:id

POST Get or Create Conversation

Create a new conversation or retrieve an existing one.

POST /api/conversations/get_or_create

Request Body

json

{
    "user_id": "string (optional)",
    "conversation_id": "string (optional)",
    "metadata": {
        "key": "value"
    } // optional
}

Parameters:

user_id (string, optional) - Unique identifier for the user
conversation_id (string, optional) - Existing conversation ID to retrieve
metadata (object, optional) - Custom metadata key-value pairs (string, number, boolean, or null values)

Response

Status: 200 OK (existing) or 201 Created (new)

json

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_123",
    "user_id": "user_456",
    "is_closed": false,
    "resolve_status": null,
    "overall_emotion_rating": null,
    "metadata": {
        "userId": "user_456",
        "plan": "premium"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z",
    "organization": {
        "name": "Acme Corp",
        "metadata": "{\"targetOrigin\":\"https://example.com\"}"
    }
}

Example

bash

curl -X POST https://api.kindflow.ai/api/conversations/get_or_create \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "user_id": "user_123",
    "metadata": {
      "source": "website",
      "page": "/pricing"
    }
  }'

POST Send Message

Send a message to an existing conversation and trigger AI processing.

POST /api/conversations/:id/message

URL Parameters

id (string, required) - Conversation UUID

Request Body

json

{
    "message": "string (required)",
    "message_role": "USER | AGENT | AI (required)"
}

Parameters:

message (string, required) - The message text (minimum 1 character)
message_role (string, required) - Role of the message sender
- USER - End user message
- AGENT - Human agent message (marks conversation as taken over)
- AI - AI-generated message

Note: When an AGENT sends a message, the conversation is automatically marked as "takenover" if not already resolved.

Response

Status: 200 OK

json

{
    "success": true,
    "aiProcessing": true
}

Response Fields:

success (boolean) - Whether the message was received
aiProcessing (boolean) - Whether the AI will process this message
- true - AI will generate a response
- false - Message saved but not processed (e.g., interaction limit exceeded)

Example

bash

curl -X POST https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "message": "What are your business hours?",
    "message_role": "USER"
  }'

GET Conversation Messages

Retrieve messages from a conversation with pagination support.

GET /api/conversations/:id/messages

URL Parameters

id (string, required) - Conversation UUID

Query Parameters

limit (string, optional) - Number of messages to return (default: 20)
offset (string, optional) - Offset for pagination (default: 0)
before_id (string, optional) - Message ID for cursor-based pagination

Pagination Methods:

Offset-based (backwards compatibility):
- Use limit and offset parameters
- Example: ?limit=20&offset=40
Cursor-based (recommended):
- Use limit and before_id parameters
- Returns messages created before the specified message ID
- More efficient for large datasets
- Example: ?limit=20&before_id=msg_123

Response

Status: 200 OK

Returns an array of messages in chronological order (oldest first).

json

[
    {
        "id": "msg_001",
        "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
        "message": "What are your business hours?",
        "message_role": "USER",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
        "id": "msg_002",
        "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
        "message": "We're open Monday-Friday, 9 AM to 6 PM EST.",
        "message_role": "AI",
        "createdAt": "2024-01-15T10:30:15Z",
        "updatedAt": "2024-01-15T10:30:15Z"
    }
]

Examples

Offset-based pagination:

bash

curl -X GET "https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/messages?limit=20&offset=0" \
  -H "x-api-key: your_api_key_here"

Cursor-based pagination:

bash

curl -X GET "https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/messages?limit=20&before_id=msg_123" \
  -H "x-api-key: your_api_key_here"

PATCH Update Conversation

Update conversation properties including metadata, status, and user information.

PATCH /api/conversations/:id

URL Parameters

id (string, required) - Conversation UUID

Request Body

All fields are optional. Only include fields you want to update.

json

{
    "user_id": "string (optional)",
    "metadata": {
        "key": "value"
    }, // optional
    "is_closed": false, // optional
    "resolve_status": "deflected | escalated | takenover | null (optional)",
    "overall_emotion_rating": 4.5 // optional, number or null
}

Parameters:

user_id (string, optional) - Update the user ID
metadata (object, optional) - Metadata to merge with existing metadata
is_closed (boolean, optional) - Whether the conversation is closed
resolve_status (string, optional) - Resolution status
- deflected - Resolved by AI
- escalated - Escalated to human
- takenover - Taken over by human agent
- null - No resolution yet
overall_emotion_rating (number, optional) - Emotion rating (or null)

Important: Metadata is merged with existing values, not replaced.

Response

Status: 200 OK

json

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "org_123",
    "user_id": "user_456",
    "is_closed": false,
    "resolve_status": "deflected",
    "overall_emotion_rating": 4.5,
    "metadata": {
        "userId": "user_456",
        "plan": "premium",
        "satisfaction": "high"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T11:00:00Z",
    "organization": {
        "name": "Acme Corp",
        "metadata": "{\"targetOrigin\":\"https://example.com\"}"
    }
}

Example

bash

curl -X PATCH https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "metadata": {
      "satisfaction": "high",
      "resolved": true
    },
    "resolve_status": "deflected"
  }'

Common Use Cases

Creating a Conversation with User Context

bash

curl -X POST https://api.kindflow.ai/api/conversations/get_or_create \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "user_id": "user_789",
    "metadata": {
      "email": "customer@example.com",
      "plan": "enterprise",
      "account_age_days": 365
    }
  }'

Sending a User Message and Getting AI Response

bash

# 1. Send user message
curl -X POST https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/message \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "message": "I need help with my order",
    "message_role": "USER"
  }'

# 2. Fetch messages to get AI response (after a brief delay)
curl -X GET "https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/messages?limit=10" \
  -H "x-api-key: your_api_key_here"

Updating Conversation Metadata Dynamically

bash

curl -X PATCH https://api.kindflow.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "metadata": {
      "cart_value": 299.99,
      "items_in_cart": 5,
      "checkout_page_visited": true
    }
  }'

Best Practices

Use Metadata Wisely: Store relevant context that your Tools can use
Merge Metadata: Use PATCH to incrementally update metadata instead of replacing
Poll for Responses: After sending a message, poll the messages endpoint to get AI responses
Handle aiProcessing=false: Implement fallback logic when AI processing is unavailable
Cursor Pagination: Use before_id for better performance with large message histories

Conversations API ​

Endpoints ​

POST Get or Create Conversation ​

Request Body ​

Response ​

Example ​

POST Send Message ​

URL Parameters ​

Request Body ​

Response ​

Example ​

GET Conversation Messages ​

URL Parameters ​

Query Parameters ​

Response ​

Examples ​

PATCH Update Conversation ​

URL Parameters ​

Request Body ​

Response ​

Example ​

Common Use Cases ​

Creating a Conversation with User Context ​

Sending a User Message and Getting AI Response ​

Updating Conversation Metadata Dynamically ​

Best Practices ​

Conversations API

Endpoints

POST Get or Create Conversation

Request Body

Response

Example

POST Send Message

URL Parameters

Request Body

Response

Example

GET Conversation Messages

URL Parameters

Query Parameters

Response

Examples

PATCH Update Conversation

URL Parameters

Request Body

Response

Example

Common Use Cases

Creating a Conversation with User Context

Sending a User Message and Getting AI Response

Updating Conversation Metadata Dynamically

Best Practices