Send a message in a conversation

POST

/conversations/{conversationId}/messages

const url = 'https://api.siteassist.io/v2/conversations/123e4567-e89b-12d3-a456-426614174000/messages';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"content":"Hello! Can you help me understand how to use this feature?","stream":false,"pageContext":{"url":"https://example.com/help","title":"Help Center - Getting Started","content":"Welcome to our help center. Here you can find answers to common questions..."}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.siteassist.io/v2/conversations/123e4567-e89b-12d3-a456-426614174000/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "content": "Hello! Can you help me understand how to use this feature?", "stream": false, "pageContext": { "url": "https://example.com/help", "title": "Help Center - Getting Started", "content": "Welcome to our help center. Here you can find answers to common questions..." } }'

Send a message to an AI assistant in a conversation. Supports both streaming and non-streaming responses. Rate limiting and usage quotas are enforced per project.

Authorizations

bearerAuth

Parameters

Path Parameters

conversationId

required

The unique identifier of the conversation to send the message to

string format: uuid

Example

123e4567-e89b-12d3-a456-426614174000

Request Body

application/json

Request body for sending a message to an AI assistant in a conversation

object

stream

If set to true, the model response data will be streamed to the client as it is generated using server-sent events. When streaming is enabled, the response will be sent as text/event-stream with incremental updates. When disabled, the complete response will be returned as application/json.

boolean

Example

false

content

required

The message content to send to the assistant. This is the user’s input that will be processed by the AI.

string

>= 1 characters <= 10000 characters

Example

Hello! Can you help me understand how to use this feature?

pageContext

Optional context information about the user’s current page and interaction. This helps the assistant provide more relevant responses.

object

url

The URL of the page where the message was sent from. Used to provide context to the assistant about the user’s current location.

string

nullable

Example

https://example.com/help

title

The title of the page where the message was sent from. Provides additional context about the user’s current page.

string

nullable

Example

Help Center - Getting Started

content

The content of the page where the message was sent from. Can be used to provide the assistant with relevant page information.

string

nullable

Example

Welcome to our help center. Here you can find answers to common questions...

textSelection

Any text that was selected by the user on the page before sending the message. This can provide specific context about what the user is asking about.

string

nullable

Example

How do I reset my password?

Example

{
  "content": "Hello! Can you help me understand how to use this feature?",
  "stream": false,
  "pageContext": {
    "url": "https://example.com/help",
    "title": "Help Center - Getting Started",
    "content": "Welcome to our help center. Here you can find answers to common questions..."
  }
}

Responses

200

Successfully processed the message and generated a response from the AI assistant

Server-sent events stream containing incremental updates of the AI assistant’s response. Each event contains a JSON object with type and relevant data. The stream includes start/end markers, text deltas, and completion information.

string

Example

data: {"type":"start"}

     data: {"type":"start-step"}

     data: {"type":"text-start","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","providerMetadata":{"openai":{"itemId":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18"}}}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"Hello! "}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"How "}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"can "}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"I "}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"assist "}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"you "}

     data: {"type":"text-delta","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18","delta":"today?"}

     data: {"type":"text-end","id":"msg_68c276dd2b3481a2bb6da153039cf9cd093857e78e8e8f18"}

     data: {"type":"finish-step"}

     data: {"type":"finish"}

     data: [DONE]

Complete response from the AI assistant when streaming is disabled. Contains the full response content, finish reason, and token usage statistics.

object

steps

required

Array of steps that make up the complete AI response

Array<object>

A single step in the AI response generation process

object

content

required

Array of content blocks in the response. Each block contains the generated content with its type and data.

Array<object>

object

key

additional properties

nullable

finishReason

required

The reason why the model stopped generating content. Common values include ‘stop’, ‘length’, ‘content_filter’, etc.

string

usage

required

Token usage statistics for this response

object

inputTokens

required

Number of tokens in the input prompt

number

outputTokens

required

Number of tokens in the generated response

number

totalTokens

required

Total number of tokens used (input + output)

number

reasoningTokens

required

Number of tokens used for reasoning (for models that support it)

number

cachedInputTokens

required

Number of input tokens that were cached and reused

number

Example

{
  "steps": [
    {
      "content": [
        {
          "type": "text",
          "text": "Hello! How can I assist you today?"
        }
      ],
      "finishReason": "stop",
      "usage": {
        "inputTokens": 2409,
        "outputTokens": 11,
        "totalTokens": 2420,
        "reasoningTokens": 0,
        "cachedInputTokens": 0
      }
    }
  ]
}

202

Message successfully received and queued for human agent handling. This response is returned when the conversation is marked for human intervention rather than AI processing.

text/plain

Simple text confirmation that the message was received and queued for human agent handling

string

Example

Message sent

400

Bad Request - The request body or parameters are invalid

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Invalid request body. Content is required.",
    "code": "INVALID_REQUEST_BODY",
    "details": {
      "field": "content"
    }
  }
}

401

Unauthorized - Authentication token is missing or invalid

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Authentication required",
    "code": "UNAUTHORIZED"
  }
}

402

Payment Required - A higher pricing plan is required to access the resource

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "A higher pricing plan is required to access this feature",
    "code": "PAYMENT_REQUIRED",
    "details": {
      "currentPlan": "free",
      "requiredPlan": "pro",
      "feature": "advanced_ai_models"
    }
  }
}

403

Forbidden - Access denied to the requested resource

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Access denied to this conversation",
    "code": "FORBIDDEN"
  }
}

404

Not Found - The requested resource was not found

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Conversation not found!",
    "code": "CONVERSATION_NOT_FOUND",
    "details": {
      "conversationId": "123e4567-e89b-12d3-a456-426614174000"
    }
  }
}

409

Conflict - The request could not be completed due to a conflict

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Resource already exists",
    "code": "CONFLICT",
    "details": {
      "resource": "conversation",
      "conflictingField": "id"
    }
  }
}

422

Unprocessable Entity - The request was well-formed but contains semantic errors

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "field": "content",
      "reason": "Content exceeds maximum length of 10000 characters"
    }
  }
}

429

Too Many Requests - Rate limit exceeded or quota reached

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retryAfter": 60
    }
  }
}

500

Internal Server Error - An unexpected error occurred

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "An internal server error occurred",
    "code": "INTERNAL_SERVER_ERROR"
  }
}

502

Bad Gateway - The server received an invalid response from an upstream server

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "BAD_GATEWAY",
    "details": {
      "service": "ai_model_service"
    }
  }
}

503

Service Unavailable - The server is temporarily unable to handle the request

application/json

object

error

required

object

message

required

Human-readable error message describing what went wrong

string

code

Machine-readable error code for programmatic handling

string

details

Additional error details and context

object

key

additional properties

nullable

Example

{
  "error": {
    "message": "Service temporarily unavailable",
    "code": "SERVICE_UNAVAILABLE",
    "details": {
      "retryAfter": 30
    }
  }
}