Skip to main content
PATCH

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Path Parameters

id
string
required

The agent's id (ag_…).

kind
enum<string>
required

The connection: calcom (calendar), grist or googlesheets (spreadsheets), zoho or zoho_bigin (CRMs), records (kept here), zendesk or salesforce (helpdesks).

Available options:
calcom,
grist,
googlesheets,
zoho,
zoho_bigin,
records,
zendesk,
salesforce

Body

application/json

Any of these, as the kind allows. Applied in this order — fields, target, match, variableColumns, mode, runAsync, tools, phrases — stopping at the first refusal; what came before it is kept, and the refusal says so. Helpdesks (zendesk, salesforce) have nothing to configure.

fields

Records only: what to collect, Label or Label | what it means.

target
object

Spreadsheets and CRMs: pins it and reads the target's real columns. Grist needs doc and table; Google Sheets spreadsheet and sheet; Zoho CRM and Bigin module. Use GET …/options to see the choices.

match
object | null

Spreadsheets and CRMs: fill the lead's existing row found by this column instead of adding one. Null (or column: null) adds a row per conversation.

variableColumns
object

Spreadsheets and CRMs: column to campaign variable, e.g. { "Locality": "locality" }. Neither may contain = or a line break. Replaces the saved map.

mode
enum<string>

All but the calendar: tool saves during the conversation; parser reads the conversation afterwards (and switches the save tool off).

Available options:
tool,
parser
runAsync
boolean

Grist only: answer before the save finishes.

tools
object

Tool id to true or false. Every id must be one of this connection's tools. Switching on counts against the shared maxTools budget.

phrases
object

Tool id to { before, after }: what the agent says on a call while the tool runs. Up to 8 lines, each under 60 characters.

Response

The connection as saved, with what each change said.

One account an agent can work in. Fields beyond the first few depend on the kind: a calendar has timezone; spreadsheets and CRMs have target, match and variableColumns; records has fields, recordCount and link; a helpdesk has only account and enabled. Credentials never appear.

kind
enum<string>
required

The connection.

Available options:
calcom,
grist,
googlesheets,
zoho,
zoho_bigin,
records,
zendesk,
salesforce
name
string
required

Its display name.

signIn
enum<string>
required

How it is connected: key by POST with a key; browser through a consent screen in the console (the API cannot); none for records, which need no account.

Available options:
key,
browser,
none
available
boolean
required

Whether this deployment offers it at all.

connected
boolean
required

Whether it is connected.

account
object | null
required

Who it is connected as: { email, name }, or { host, email } for a helpdesk.

lastError
string | null
required

Why the last attempt to use it failed.

toolsInUse
integer
required

Connection tools switched on, across every connection.

maxTools
integer
required

The shared budget.

messages
string[]
required

What each applied change said, in order.

signInPending
boolean

Browser sign-ins only: a sign-in was started in the console and not finished.

timezone
string | null

Calendar only: the account's timezone.

mode
enum<string>

All but the calendar and helpdesks: tool saves during the conversation; parser reads the conversation afterwards.

Available options:
tool,
parser
runAsync
boolean

Grist only: answer before the save finishes.

target
object

Spreadsheets and CRMs: what it is pinned to, and that target's real columns. Grist { doc, table, columns }; Google Sheets { spreadsheet, sheet, columns }; Zoho { module, columns }.

match
object | null

Spreadsheets and CRMs: the column that finds a lead's existing row, or null to add a row per conversation.

variableColumns
object

Spreadsheets and CRMs: column to campaign variable.

tools
object[]

Its tools. Helpdesks have none here.

fields
object[]

Records only: what is collected.

recordCount
integer

Records only: how many records have been collected.

Records only: the link to read them. The passcode is shown only by the call that makes a link.

enabled
boolean

Helpdesks only: whether it is in use.