Chat Conversations

Base URL: https://api.cornerspot.net

Authentication: requests use a bearer token, for example Authorization: Bearer YOUR_API_KEY.

List chat conversations

GET /c/api/v1/chat/conversations

Returns a paginated list of live-chat conversations for the team, ordered by last_message_at desc then created_at desc. Requires chat_read scope and the Live Chat module.

Each conversation carries the AI-analysis fields surfaced in the inbox: sentiment, sentiment_trend, has_summary, summary, csat, and the auto-translation flags. The top-level stats object rolls up CSAT and sentiment across the filtered set (matching the admin inbox header).

Filters filter[status] — comma-separated statuses (open, closed, converted_to_ticket). filter[assignee_user_id] — show conversations assigned to this user. filter[queue]=unassigned or filter[unassigned]=true — only unassigned open conversations. filter[contact_id] — conversations whose visitor resolves to this contact. filter[account_id] — conversations whose visitor resolves to any contact on this account.

Query parameters

FIELD	TYPE	DESCRIPTION
`filter[status]`	string	Comma-separated statuses: open, closed, converted_to_ticket.
`filter[assignee_user_id]`	string	Filter to conversations assigned to this team-member user id.
`filter[queue]`	string one of `unassigned`	Pass `unassigned` to return only open, unassigned conversations.
`filter[unassigned]`	boolean	Boolean alternative to `filter[queue]=unassigned`.
`filter[contact_id]`	string	Return conversations whose visitor resolves to this contact.
`filter[account_id]`	string	Return conversations whose visitor resolves to any contact on this account.
`page`	integer	1-based page number.
`per_page`	integer	Page size (1–100, default 25).

Code samples

curl --request GET \
  --url 'https://api.cornerspot.net/c/api/v1/chat/conversations' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

// Node.js 18+ (native fetch)
const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

import json
import urllib.request

url = "https://api.cornerspot.net/c/api/v1/chat/conversations"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}

request = urllib.request.Request(url, headers=headers, method="GET")

with urllib.request.urlopen(request) as response:
    data = json.loads(response.read().decode("utf-8"))
    print(data)

require "json"
require "net/http"

uri = URI("https://api.cornerspot.net/c/api/v1/chat/conversations")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts JSON.parse(response.body)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.cornerspot.net/c/api/v1/chat/conversations',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);

Responses

STATUS	DESCRIPTION
`200` OK	a page of conversations
`401` Unauthorized	missing or invalid API key
`402` Payment Required	team plan does not include live chat
`403` Forbidden	key lacks chat_read scope

Get a chat conversation

GET /c/api/v1/chat/conversations/{id}

Returns a single conversation. Requires chat_read scope and the Live Chat module.

Path parameters

FIELD	TYPE	DESCRIPTION
`id`	string · required	Conversation id.

Code samples

curl --request GET \
  --url 'https://api.cornerspot.net/c/api/v1/chat/conversations/abc123' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations/abc123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

// Node.js 18+ (native fetch)
const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations/abc123', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

import json
import urllib.request

url = "https://api.cornerspot.net/c/api/v1/chat/conversations/abc123"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}

request = urllib.request.Request(url, headers=headers, method="GET")

with urllib.request.urlopen(request) as response:
    data = json.loads(response.read().decode("utf-8"))
    print(data)

require "json"
require "net/http"

uri = URI("https://api.cornerspot.net/c/api/v1/chat/conversations/abc123")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts JSON.parse(response.body)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.cornerspot.net/c/api/v1/chat/conversations/abc123',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);

Responses

STATUS	DESCRIPTION
`200` OK	the conversation
`401` Unauthorized	missing or invalid API key
`402` Payment Required	team plan does not include live chat
`403` Forbidden	key lacks chat_read scope
`404` Not Found	conversation not found in this team

Claim a conversation

POST /c/api/v1/chat/conversations/{id}/claim

Assigns an agent to an open, unassigned conversation. Uses a single Postgres UPDATE to avoid double-claim races: if two agents hit this simultaneously, exactly one wins and the other gets 409 already_claimed.

Requires chat_write scope and the Live Chat module.

Path parameters

FIELD	TYPE	DESCRIPTION
`id`	string · required	Conversation id.

Request body

FIELD	TYPE	DESCRIPTION
`user_id`	string · required	Required — the team-member user to assign.

Code samples

curl --request POST \
  --url 'https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/claim' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "user_id": "1f2e3d4c-5b6a-4789-9c0d-1e2f3a4b5c6d"
}'

const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/claim', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    "user_id": "1f2e3d4c-5b6a-4789-9c0d-1e2f3a4b5c6d"
  })
});

const data = await response.json();
console.log(data);

// Node.js 18+ (native fetch)
const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/claim', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    "user_id": "1f2e3d4c-5b6a-4789-9c0d-1e2f3a4b5c6d"
  })
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

import json
import urllib.request

url = "https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/claim"
payload = json.dumps({
  "user_id": "1f2e3d4c-5b6a-4789-9c0d-1e2f3a4b5c6d"
}).encode("utf-8")
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
}

request = urllib.request.Request(url, data=payload, headers=headers, method="POST")

with urllib.request.urlopen(request) as response:
    data = json.loads(response.read().decode("utf-8"))
    print(data)

require "json"
require "net/http"

uri = URI("https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/claim")

request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer YOUR_API_KEY"
request.body = JSON.generate({
  "user_id": "1f2e3d4c-5b6a-4789-9c0d-1e2f3a4b5c6d"
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts JSON.parse(response.body)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/claim',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer YOUR_API_KEY',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '1f2e3d4c-5b6a-4789-9c0d-1e2f3a4b5c6d',
]),
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);

Responses

STATUS	DESCRIPTION
`200` OK	conversation claimed and returned
`401` Unauthorized	missing or invalid API key
`402` Payment Required	team plan does not include live chat
`403` Forbidden	key lacks chat_write scope
`404` Not Found	conversation not found in this team
`409` Conflict	conversation is already claimed by another agent
`422` Unprocessable Content	conversation is not open (cannot be claimed)

Close a conversation

POST /c/api/v1/chat/conversations/{id}/close

Ends a conversation by setting its status to closed. Idempotent: calling close on an already-closed conversation returns 204 immediately. Requires chat_write scope and the Live Chat module.

Path parameters

FIELD	TYPE	DESCRIPTION
`id`	string · required	Conversation id.

Code samples

curl --request POST \
  --url 'https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/close' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/close', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

// Node.js 18+ (native fetch)
const response = await fetch('https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/close', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

import json
import urllib.request

url = "https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/close"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}

request = urllib.request.Request(url, headers=headers, method="POST")

with urllib.request.urlopen(request) as response:
    data = json.loads(response.read().decode("utf-8"))
    print(data)

require "json"
require "net/http"

uri = URI("https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/close")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts JSON.parse(response.body)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.cornerspot.net/c/api/v1/chat/conversations/abc123/close',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);
print_r($data);

Responses

STATUS	DESCRIPTION
`204` No Content	conversation closed (or was already closed)
`401` Unauthorized	missing or invalid API key
`402` Payment Required	team plan does not include live chat
`403` Forbidden	key lacks chat_write scope
`404` Not Found	conversation not found in this team

List chat conversations

Query parameters

Code samples

Responses

Get a chat conversation

Path parameters

Code samples

Responses

Claim a conversation

Path parameters

Request body

Code samples

Responses

Close a conversation

Path parameters

Code samples

Responses

Was this article helpful?