Chats

A chat is a live conversation with a customer on your website widget or a messenger account connected to Replyco. Unlike a ticket, it happens in real time: your system finds the open chats, reads their messages, and either sends a message straight to the customer or leaves a draft that an agent sees in the chat. When the conversation is over, the chat is closed.

Fields that matter

Field	Meaning
id	The chat’s id. Pass it as chatId to the other chat operations.
status	0 open or 1 closed; see States.
title	The chat’s title; term searches it.
accountId, widgetId	The messenger account or the website widget the chat came in on.
createdDate	When the chat started.
customerId	The customer linked to the chat, when there is one; see Customers.

States

State	Meaning
0 (open)	The conversation is going on.
1 (closed)	The conversation is over. Closing a chat also marks all its messages as read.

Change the state with POST /openapi/chat/status/{chatId}/{status}, where status is 0 or 1. The change is recorded in the change history.

Listing and filtering

POST /openapi/chat/paged lists the chats your system should look at. It takes a JSON body:

Field	What it does	Default	Limits
type	0 open chats, 1 closed chats, 2 open chats assigned to you, the user the token belongs to.	0	—
assignedUsers	With type 0 or 1: only chats assigned to one of these users.	none: the chats you are assigned to or responsible for	User ids from GET /openapi/user/id_name.
accounts	Only chats from these accounts or widgets.	every account	—
term	Only chats whose title or description contains this text, ignoring case.	none	—
page	The page to return, from 1.	1	Stop at pagesCount.
count	Chats per page.	10	—

Chats come newest activity first. Leave sort out to keep that order.

curl -X POST https://open-api.replyco.com/openapi/chat/paged \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": 0, "accounts": ["3f1c2a9e-7b4d-4e8a-9c21-5d6f0a1b2c3d"], "page": 1, "count": 50}'

{ "accounts": ["3f1c2a9e-7b4d-4e8a-9c21-5d6f0a1b2c3d"], "page": 1, "count": 50 }

GET /openapi/chat/paged lists every chat of your company in any state, with the query parameters page, count (at most 100), term, sort (createdDate, status, marketId, marketplace or title) and asc. Operations whose path ends in /paged allows one user 15 calls a minute (see Rate limits).

GET /openapi/chat/{id} returns one chat, and answers 204 with no body when no chat has that id.

A chat’s messages

GET /openapi/chat/pagedchatmessages/{chatId} returns one page of a chat’s messages. Each message has text, date, isFromCompany (true for your team’s messages) and any files.

Parameter	What it does	Default	Limits
sort	Send date to get the messages in time order.	none: an order that has no meaning	date or status; other values are rejected with 400.
asc	true oldest first, false newest first.	true	—
term	Only messages whose text contains this text.	none	—
page, count	The page and its size.	1 and 10	Stop at pagesCount.

curl "https://open-api.replyco.com/openapi/chat/pagedchatmessages/5d0b7e3a-1c2f-4a9b-8d6e-2f3a4b5c6d7e?sort=date&asc=false&count=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Answering a chat

POST /openapi/chat/sendmessage sends a message to the customer. Send chatId and text. To send a file instead, send its content base64-encoded in base64 and its name in fileName; the message then carries the file and no text.

{ "chatId": "5d0b7e3a-1c2f-4a9b-8d6e-2f3a4b5c6d7e", "text": "Your parcel left our warehouse this morning." }

PUT /openapi/chat/draft/{chatId} leaves a draft for an agent instead. The draft is plain text and is not sent to the customer: agents see it in the chat’s message box, straight away if they have the chat open. A chat has one draft, shared by all agents, so each call replaces the last one; send an empty messageText to clear it. The draft disappears when a message is sent in the chat, and after 24 hours.

{ "messageText": "Hi Sam, your parcel left our warehouse this morning." }

Assignment and customers

POST /openapi/chat/assignuser/{chatId}/{userId} adds an agent to the chat’s assignees; a chat can have several. Assign each user once. DELETE on the same path removes that agent.

GET /openapi/chat/customer/{chatId} returns the customer behind a chat, and answers 204 when the chat has none. When it finds exactly one customer, it also links that customer to the chat. POST /openapi/chat/customer/{chatId}/{customerId} links a customer you choose, and DELETE /openapi/chat/customer/{chatId} removes the link. GET /openapi/chat/chatsbycustomer/{customerId} lists every chat linked to a customer, and returns an empty list when there are none.

Operations

Method	Path	Summary	Scopes
POST	/openapi/chat/assignuser/{chatId}/{userId}	Assign a user to a chat	—
DELETE	/openapi/chat/assignuser/{chatId}/{userId}	Remove user assignment from a chat	—
GET	/openapi/chat/chatsbycustomer/{customerId}	Get all chats for a specific customer	—
GET	/openapi/chat/customer/{chatId}	Get customer(s) associated with a chat	—
DELETE	/openapi/chat/customer/{chatId}	Remove customer association from a chat	—
POST	/openapi/chat/customer/{chatId}/{customerId}	Associate a customer with a chat	—
PUT	/openapi/chat/draft/{chatId}	Set the draft reply for a chat	—
GET	/openapi/chat/paged	Get all records with paging	—
POST	/openapi/chat/paged	Get paginated list of chats with filtering	—
GET	/openapi/chat/pagedchatmessages/{chatId}	Get paginated messages for a specific chat	—
POST	/openapi/chat/sendmessage	Send a message in a live chat	—
POST	/openapi/chat/status/{chatId}/{status}	Change the status of a chat	—
GET	/openapi/chat/{id}	Get element by id	—

Errors

Status	Meaning	Returned by
400	Invalid request body; Invalid filter parameters; Invalid pagination parameters; Invalid request (e.g., missing required fields, chat is closed); Invalid status value	PUT /openapi/chat/draft/{chatId}, POST /openapi/chat/paged, GET /openapi/chat/pagedchatmessages/{chatId}, POST /openapi/chat/sendmessage, POST /openapi/chat/status/{chatId}/{status}
401	User is not authenticated or authorized; Unauthorized	POST /openapi/chat/assignuser/{chatId}/{userId}, DELETE /openapi/chat/assignuser/{chatId}/{userId}, GET /openapi/chat/chatsbycustomer/{customerId}, GET /openapi/chat/customer/{chatId}, DELETE /openapi/chat/customer/{chatId}, POST /openapi/chat/customer/{chatId}/{customerId}, PUT /openapi/chat/draft/{chatId}, GET /openapi/chat/paged, POST /openapi/chat/paged, GET /openapi/chat/pagedchatmessages/{chatId}, POST /openapi/chat/sendmessage, POST /openapi/chat/status/{chatId}/{status}, GET /openapi/chat/{id}
404	Chat or user ID was not found; Customer with the specified ID was not found; Chat or customer ID was not found; Chat with the specified ID was not found	POST /openapi/chat/assignuser/{chatId}/{userId}, DELETE /openapi/chat/assignuser/{chatId}/{userId}, GET /openapi/chat/chatsbycustomer/{customerId}, GET /openapi/chat/customer/{chatId}, DELETE /openapi/chat/customer/{chatId}, POST /openapi/chat/customer/{chatId}/{customerId}, PUT /openapi/chat/draft/{chatId}, GET /openapi/chat/pagedchatmessages/{chatId}, POST /openapi/chat/sendmessage, POST /openapi/chat/status/{chatId}/{status}

Related

• Answer live chats from your own system: find, read and answer chats step by step.
• Look up a customer’s history: a customer’s tickets and chats.
• Users: the user ids you assign.
• API reference: every field of ChatFilter, ChatModel and ChatMessageModel.