Skip to content
SiteAssistSiteAssistSiteAssist

Start a new conversation

POST
/conversations
curl --request POST \
  --url https://api.siteassist.io/v2/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "context": { "pageUrl": "https://example.com/contact" } }'

Create a new conversation for a customer to interact with an AI assistant. This endpoint initializes a conversation session and returns the conversation details including a unique conversation ID that can be used for subsequent message exchanges.

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json

Request body for starting a new conversation

object
context

Optional context information about where the conversation is being started

object
pageUrl

The URL of the page where the conversation is being initiated from

string format: uri
Example
https://example.com/contact
Example
{
  "context": {
    "pageUrl": "https://example.com/contact"
  }
}

Responses

Section titled “Responses”

201

Section titled “201”

Successfully created a new conversation. The conversation is now ready to receive messages from the customer.

Media typeapplication/json

The newly created conversation object containing conversation metadata, status, and associated information.

object
object

The type of object returned, always ‘conversation’

string
default: conversation
Allowed values: conversation
id
required
string format: uuid
createdAt
required
string
updatedAt
required
string
status
required
string
Allowed values: open closed
closedAt
required
string
nullable
closeReason
required
string
nullable
lastInteractionAt
required
string
isHumanHandled

Whether this conversation is being handled by a human agent instead of AI

boolean
humanAgent

Information about the human agent assigned to this conversation, if any

object
name
required
string
nullable
image
required
string
nullable
messages

Array of messages in this conversation

Array<object>
default:
object
object
string
default: message
Allowed values: message
id
required
string format: uuid
createdAt
required
string
chatId
required
string format: uuid
role
required
string
Allowed values: assistant human_agent user
parts
required

The parts of the message.

Array
status
required
string
nullable
Allowed values: streaming complete error
error
required
string
nullable
feedback
required
string
nullable
Allowed values: like dislike
feedbackAt
required
string
nullable
metadata
required
Any of:
string
humanAgent
object
name
required
string
nullable
image
required
string
nullable
pageUrl
required
string
nullable
pageTitle
required
string
nullable
textSelection
required
string
nullable
title
required
string
nullable
Example
{
  "object": "conversation",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "status": "open",
  "closedAt": null,
  "closeReason": null,
  "lastInteractionAt": "2024-01-15T10:30:00.000Z",
  "isHumanHandled": false,
  "humanAgent": null,
  "messages": []
}

400

Section titled “400”

Bad Request - The request body or parameters are invalid

Media typeapplication/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

Section titled “401”

Unauthorized - Authentication token is missing or invalid

Media typeapplication/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

Section titled “402”

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

Media typeapplication/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

Section titled “403”

Forbidden - Access denied to the requested resource

Media typeapplication/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

Section titled “404”

Not Found - The requested resource was not found

Media typeapplication/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

Section titled “409”

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

Media typeapplication/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

Section titled “422”

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

Media typeapplication/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

Section titled “429”

Too Many Requests - Rate limit exceeded or quota reached

Media typeapplication/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

Section titled “500”

Internal Server Error - An unexpected error occurred

Media typeapplication/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

Section titled “502”

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

Media typeapplication/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

Section titled “503”

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

Media typeapplication/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
    }
  }
}