Skip to main content
TroopyDocs
GuidesSet up and use TroopyAppsConnect your servicesAPIThe API, the CLI and MCPChangelogEach update to Troopy

Developers

Account

Troop

Skills

Tasks and projects

Needs you

Routines and triggers

Brain

Docs

Canvas

Email

CRM

Outreach

Customers

Analytics

Sessions

Surveys

Support Agent

Tests and incidents

Disputes

Apps

Vault

Computer

Open Troopy
Troopy

API reference / Support Agent

Take over, hand back, resolve or translate a conversation

Send only what changes. held: true takes the conversation over, and the Support agent answers nothing in it. held: false hands it back, also after the Support agent asked for a person: the Support agent reads what it missed, and answers the next message. resolved: true resolves it and hands it back, and false opens it again. read: false marks it unread for the caller, and true reads it. translate turns Live translate on, with language as the language of the team (a tag such as en), or off. Troopy reads the language of the visitor from its messages, and turns Live translate off when the visitor writes in the language of the team. blocked: true blocks the visitor, for owners and admins: it sees no chat from then. false unblocks it. A person writes here, never a teammate.

patch/api/v1/support-conversations/{id}

Authorization

HeaderAuthorization: Bearer <API key>
Or the headerX-API-Key: <API key>
API keyMake one in Troopy under Settings > API keys. It acts as you, in its workspace.
Scopessupport:write

Other ways to call it

CLItroopy support update
MCP toolNone. Call it over REST or with the CLI.
Rate limit60 calls in 60 seconds, for each key
RetriesSend an Idempotency-Key header. A retry with the same key gets the first answer back, and the operation runs one time.

Path parameters

id*string

A 24-character id

Body

application/json
heldboolean
resolvedboolean
readboolean

false marks the conversation unread for the caller. The other people keep their own marks

blockedboolean

true blocks the visitor by its browser and its email, and ends its chat. false unblocks it. Owners and admins

translateobject
2 properties
on*boolean
languagestring

The language of the team, as a tag such as en

Default "en" · At least 2 characters · At most 35 characters

Response

200 · application/json
data*object
33 properties
id*string

A 24-character id

botId*string

A 24-character id

botName*string

The name of the Support Agent

origin*string

The website where the visitor chats

status*enum<string>

online: the page of the visitor is open now

onlineoffline

lastSeenAt*string | null
createdAt*string

ISO 8601 date and time

expiresAt*string

When the chat of the visitor ends. After it, a reply goes only by email

lastMessageAt*string

ISO 8601 date and time

messageCount*integer
excerpt*string

The last message that the visitor sees, 180 characters at most

lastFrom*enum<string> | null

visitorbotpersonnoteevent

lastBy*string | null

The person of the team who wrote the last message, when a person did

country*string | null
city*string | null
unread*integer

The messages of the visitor that the caller did not read

taken*object | null

The person who holds the conversation. The Support agent answers nothing while a person holds it

2 properties
id*string
name*string
resolved*boolean
waitingSince*string | null

Since when the visitor waits for an answer. Null: nobody waits

asked*object | null

The Support agent, or the count of visitor messages, asked for a person, and nobody holds the chat yet. The Support agent answers nothing until a person replies or hands it back

2 properties
at*string

ISO 8601 date and time

reason*string

Why, in one sentence for the team

contact*object | null

The signed-in user that the website named with TroopyChat.identify. Null for a visitor that it named not

5 properties
id*string | null

The id of the user in the product of the business

email*string | null
name*string | null
photo*string | null

The address of the copy of the photo in Troopy's storage

verified*boolean

The backend of the website signed the email (or the id) with the identity secret of the Support Agent

email*string | null

The email that the visitor gave in the chat, for the replies of the team

ticket*object | null

The bug ticket of the chat. A chat has one open ticket

7 properties
key*string
title*string
status*enum<string>

backlogtodoin_progressneeds_youin_reviewdonecanceled

stage*enum<string> | null

The step of the engineering flow. Null: the ticket is not in the flow

analyzeplanbuildtestrelease

reports*integer

The reports of the visitor's problem that the ticket holds

liveAt*string | null

When the ticket went live. The team then tells the visitor that the problem is fixed

told*boolean

A person of the team replied to the visitor after the ticket went live

customer*object | null

The same person as a customer of the business, by the email or the id of its contact. Needs customers:read

7 properties
id*string

A 24-character id

name*string | null
status*enum<string>

freetrialactivepast_duecancelingchurnedpaid

plan*string | null
mrr*number

What the customer pays a month, in the units of its currency

currency*string | null
risk*enum<string>

nonewatchhigh

visitor*object | null

The visitor as Analytics knows one. Troopy keeps no address

8 properties
countrystring | null
regionstring | null
citystring | null
timeZonestring | null
languagestring | null
browserstring | null
osstring | null
devicestring | null
pages*array<object>

The last 10 pages of the visitor, by path

3 properties
path*string
title*string | null
at*string

ISO 8601 date and time

ended*boolean

The conversation of the visitor ended. A reply then goes only by email (mailTo)

mailTo*string | null

Where a reply of the team goes when the visitor does not read it in the chat: the email of the visitor

readAt*string | null

The last time that the chat of the visitor was open on a page that showed. The visitor read the replies before it

rating*object | null

How the visitor rated the help, 1 to 5, after a person resolved the conversation

3 properties
score*integer

At least 1 · At most 5

comment*string | null
at*string

ISO 8601 date and time

translate*object | null

Live translate: the language of the team and of the visitor

2 properties
team*string
visitor*string | null

Null until the first translation reads the language that the visitor writes in

translating*boolean
messages*array<object>
11 properties
id*string
role*enum<string>

visitor, bot (the Support agent), person (a reply of a person of the team), note (for the team only) or event (the team took the conversation over, or resolved it)

visitorbotpersonnoteevent

text*string
at*string

ISO 8601 date and time

by*object | null
2 properties
id*string
name*string
original*string | null

The words that the person wrote, when the reply went to the visitor in the language of the visitor

translation*object | null

The message in the language of the team, for Live translate

2 properties
text*string
lang*string
state*enum<string> | null

A reply that waits for its translation, or that could not get one. The visitor sees neither

sendingfailed

byEmail*boolean

A message of the visitor that came as an answer to an email of the team

attachments*array<object>
5 properties
id*string
name*string
contentType*string | null
size*number | null
available*boolean
gif*object | null
4 properties
url*string
title*string
width*number
height*number

Errors

400 invalid_inputFix the field named in detail. Each operation's schema is in /api/v1/openapi.json.
401 unauthorizedSend an API key as `Authorization: Bearer tr_live_...`. Create one in Troopy under Settings.
403 forbiddenThe key lacks a scope this operation needs, or its owner lacks the role. detail says which; create a key with the scope, or ask an organization owner or admin.
404 not_foundCheck the path and any id in it. Every operation is listed in /api/v1/openapi.json.
409 conflictThis Idempotency-Key was used for a different request, or that request is still running. Use a new key for a new request.
429 rate_limitedWait the number of seconds in Retry-After, then retry.