Documentation

Importing a file

Upload a CSV, JSON Lines in our format, or JSON in your own shape. Check how it was read, confirm the mapping, and import: redacted before the first write, the same as everything else.

You do not have to connect anything to be read. Export your conversations from wherever they live, upload the file on Settings › Sources, check how it was read, and import it. An export that recurs can be [watched in a bucket](#watched-bucket) instead. This is rung 0 of the access model ([the rung model](rungs.md)), and it is the same road a conversation takes when you send it over [the signals API](signals-api.md): every route ends in one format, one writer and one set of redaction rules.

Four kinds of file are read:

  • A CSV, with columns you pick. Download the template from the upload screen.
  • JSON Lines (.jsonl, .ndjson), one conversation per line, in the format below. This is the shape to export into if you are building the export yourself.
  • JSON in another shape (.json, or JSON Lines of your own), mapped by paths you type — the same picks a signals key uses for [any webhook in its own shape](signals-api.md#any-webhook-in-its-own-shape). Nothing is guessed.
  • Another tool's own export, for the tools listed under [Another tool's export](#another-tools-export): the file is recognized by its keys, you are told what it looks like and how sure we are, and it is read that way only when you pick the reader.

A file takes up to 20,000 conversations and 10 MB. Split a larger export, or connect the helpdesk instead.

Check first, then import

Pressing Check the file reads the file and stores nothing. It tells you how many conversations it found, which column or path it took for each thing, how many it would refuse and why, what redaction can and cannot do on this file, and a fingerprint: a short hash of exactly how the file was read (which column is which, the shape of the header row, and your answer to whose answers the file holds). Import carries the fingerprint back. If the file or any pick has changed since you checked it, the import is refused and you check again; nothing is imported on a guess, and nothing on a mapping you did not look at. The fingerprint is recorded in the workspace's audit trail with who confirmed it, and never a row.

Two questions are never answered for you:

  • Whose answers are in the file? A CSV with no column saying whether your AI answered is asked once, for the whole file: your AI's, or your team's. A missing column is not an answer. JSON Lines says it conversation by conversation, or by the roles of its turns.
  • When did each conversation start? A row with no readable date is refused and counted. A date is never made up, because every figure over a window reads it. A date in the future is not a date either.

The format: functioninghq.conversation/v1

One conversation per line. Only id, startedAt and turns are required.

{"format":"functioninghq.conversation/v1","id":"T-1042","startedAt":"2026-09-01T09:14:00Z","updatedAt":"2026-09-01T11:02:00Z","state":"closed","channel":"chat","language":"en","subject":"Refund for order ORD-77814","customer":{"id":"u-8841","email":"ada@example.com","name":"Ada Lovelace","company":"Analytical Engines"},"turns":[{"role":"customer","text":"My refund has not arrived.","at":"2026-09-01T09:14:00Z"},{"role":"ai","text":"Refunds take 5-10 business days from the charge.","at":"2026-09-01T09:14:20Z","by":"support-bot","tools":[{"name":"order_lookup","ok":true}],"retrieved":[{"articleId":"refunds-policy","passage":"Refunds take 5-10 business days."}]},{"role":"customer","text":"It has been three weeks.","at":"2026-09-01T10:40:00Z"},{"role":"agent","text":"Sorry about that. I have escalated it and you will hear today.","at":"2026-09-01T11:02:00Z"}],"ai":{"participated":true,"cited":["refunds-policy"],"claim":{"outcome":"claimed","field":"status"}},"rating":{"conversation":2,"comment":"Took too long"},"tags":["refund"],"facets":{"plan":"team"}}
FieldWhat it is
formatOptional. If given, it must be functioninghq.conversation/v1.
idYour id for the conversation. Unique within the file; stored namespaced to the upload, so it never meets a helpdesk ticket of the same number.
startedAt, updatedAtISO 8601. updatedAt defaults to startedAt. A file keeps the dates it carries.
stateopen, closed or snoozed. Left out, nothing is recorded.
channel, language, subject, tags, facetsContext. A subject is customer-written and redacted like a message. language is a hint; the read stays authoritative.
customerid, email, company, name. See below.
turnsIn order. role is customer, ai or agent; text; optional at. An ai turn may say which tools it called and whether each worked, and what it retrieved.
ai.participatedWhether an AI answered. Left out, it is read from the roles of the turns.
ai.citedThe help center articles the answer quoted, by your id for them.
ai.claimWhat your vendor claims about the outcome: outcome is confirmed, assumed, claimed, escalated or unresolved, and field is the name of the field it came from. With a field, the claim is recorded as evidence with your file named as its source — theirs, never our verdict. Left out, the conversation claims nothing.
ratingOut of five, as the customer gave it: conversation, ai, and a comment (redacted).

What is stored, and what never is

  • Redaction runs before the first write, the same as for a live sync and the signals API: addresses, phone numbers, cards, tokens, your workspace's own patterns (Settings › Data), and, where the customer's name is in the file, the name itself. customer.name is for this and nothing else: it is never stored. Neither is the email or the id; they are hashed the moment they are read so the same person is recognised across conversations. The text is written under the version of the redaction rules it was redacted by.
  • Your AI's signature (Settings › How we work), if you have set one, marks the answers that carry it as your AI's.
  • Internal notes are dropped. A turn with the role note is counted and discarded.
  • A tool's result is never kept, nor its arguments: only its name and whether it worked. Everything else a tool object carries is dropped.
  • Nobody who answered is stored. by on a turn is read and dropped. Nothing in a file feeds coaching; the product keeps only whether the AI or a person answered.
  • Fields the format does not have are dropped and counted, by name, on the check. An origin a file names is not believed: only this product's own readers of a vendor's native export may say which helpdesk conversation a row is, and never from a claim in a file.

What redaction cannot do on a file

A live connection has the contact record, so it removes the customer's own name and email wherever they appear in the messages. A file has no contact record. If neither a customer name nor an email is in the file, the check says so in plain words: a name written into a message is not removed. Send customer.name (a JSON Lines file), or map the name column (a CSV), and it is.

Cleaning a CSV before it leaves your computer

You can clean a CSV in your own browser before anything is sent, at /prepare (no account needed) or under Clean it in this browser first on the upload. The same redaction runs there as on our servers, plus each row's own name (whole and in parts) and any words you list. The name column is used and then dropped, the customer column becomes a stand-in (person- and an HMAC under a key kept in your browser, so we cannot reverse it), and columns we do not read are left out unless you keep them. Every row gets a cleaned_locally column naming the redaction version. The upload then says the file was cleaned instead of warning about weaker redaction; our own redaction still runs on it as it is stored. A stand-in does not join the same person read later from a connected helpdesk.

Dates, retention, and duplicates

  • Older than your retention window: refused and counted. The nightly job deletes on the last message, so a row already past the window would be read once and removed that night. The check shows the date before which rows are refused.
  • The same file twice stores nothing the second time: its rows are recognised.
  • The same conversation as your helpdesk holds is counted once: the helpdesk's copy stands and the file's is marked its duplicate, by the same person and first message within minutes. Where an export says exactly which helpdesk conversation it is, and the account is the connected account, it is matched exactly; that is built for exports this product reads itself.
  • Stored as an upload. Every conversation from a file is stored with the source csv and the route and format beside it, so your team's answers in it are graded at rung 0. For that reason a signals key cannot be named csv or import.

A CSV

id,customer_id,customer_name,created_at,transcript,resolved,ai_handled,cited_articles
"1001","ada@example.com","Ada Lovelace","2026-09-01T09:14:00Z","customer: My refund has not arrived.
ai: Refunds take 5-10 business days from the date of the original charge.
agent: Sorry about that - I have escalated it.","false","true","refunds-policy"

Only the transcript and the date are required. resolved is your vendor's own claim, recorded as evidence naming that column; with no such column the file claims nothing. Every column is a pick: the check shows which one it took and lets you change it.

Columns it does not know. A file whose columns the importer cannot match by name is not refused: the check shows the mapping with every header, and you pick. If you would rather not start from nothing, press Suggest columns. A model reads the column names and up to three short values under each, with anything personal removed (addresses, phone numbers, cards and your workspace's own patterns) and cut short, and fills in only the fields we could not find. It answers with a column of your file or with nothing, and anything else it says is thrown away. It is a default in a select and never the mapping: you look at each pick and check the file again, and the import quotes the fingerprint of what you checked. It spends a little of your day's allowance, and is refused on a plan that takes no import and while the workspace is paused.

JSON in another shape

Say where things are, as paths: the conversation's id, startedAt, the list of messages, a message's text and role, the author values that mean your AI and your team (anything else is the customer), and optionally the customer's email or id and company. A file that is one JSON document can name list, the path to the list of conversations. The date is required, and an item without one is refused and counted. The mapping is checked and fingerprinted like a CSV's.

id:          ticket.number
startedAt:   ticket.opened
messages:    thread
text:        body
role:        from
AI values:   bot

Another tool's export

A file that carries the keys of a tool's own objects is recognized, and recognition only suggests. The check says what the file looks like, how many records it holds and what is true of this particular file ("Looks like a Zendesk ticket export, 1,204 tickets, no users file, so roles are inferred"), and reads nothing until you choose Read it as that tool's. Declining reads the file as it states itself. After you choose, the dry run, the counts and the fingerprint are exactly a mapped file's: nothing is imported on a guess.

Each reader is this product's own code, built from the tool's documentation, and none has yet been compared with a real export. How sure it is of the shape is stated beside it, and on the check:

  • high: the tool's own object, which a live connection already reads in production here, so only how you get it into a file is unverified.
  • medium: the documented API object, partly exercised by a live connection; parts of it (who the AI is, what a custom status means) are inferences.
  • low: built from the documentation alone, with no live use here.
ToolThe fileSureWhat it cannot tell
ZendeskTickets with their comments: JSON Lines, a list, or { "tickets": [ … ] }; a users list is optionalmediumWithout users, the requester is the customer and everyone else is your team. The AI is read from the channel a comment came in on (Zendesk names no bot user). The automated-resolution tag is Zendesk's claim of a resolution, not a bill.
IntercomConversations with their conversation_partshighOnly ai_agent.resolution_state is a claim; a conversation without it claims nothing, whether or not Fin took part. A list fetched without parts is read as its opening message alone.
Help ScoutConversations with _embedded.threadsmediumHelp Scout reports whether its AI took part and not how it went, so there is no claim. The account is not in the file.
GorgiasTickets with their messagesmediumWhich messages are AI Agent's is inferred from its tags and its sender's name. The ai_close tag is Gorgias's claim that its AI resolved a ticket, and ai_handover a handover; neither is a bill.
FreshdeskTickets with conversations embeddedlowFreshdesk reports nothing about its AI, so no answer is read as the AI's and there is no claim. A ticket may have more replies than the API embeds.
FrontConversations with messages (is_inbound)lowNo AI and no claim. Drafts and comments are not read.
CrispSessions with messages (from user or operator)lowNo AI and no claim. Notes are not read.
ChatbaseA chatbot's conversations with messages (role, content)lowEvery assistant message is the chatbot's. No outcome.
LangfuseTraces, put together by sessionIdlowA trace with no sessionId is refused. The newest trace of a session is the conversation.
LangSmithRuns, put together by session_id, thread_id or conversation_id in their metadatalowA call with none is refused. The newest call is the conversation.
BraintrustLog spans, put together by a conversation id in their metadatalowA call with none is refused. Nothing is read as retrieved.

Every reader keeps the rules of the format. A private note, an internal comment or a draft is dropped and counted. A conversation the tool itself marks deleted, spam or merged is left out with that reason. No assignee is carried. A claim is present only where the tool's own record carries a field for it, and it names that field; a reader never makes one up. For the trace tools (Langfuse, LangSmith, Braintrust) the rule is OpenTelemetry's: a chat model is handed the whole history on every call, so the newest call of a conversation holds the conversation; a tool the application ran is its name and whether it failed, and its arguments and its result are never read; a retriever's output is the passages it retrieved. Only the helpdesk readers set an origin, from the id the tool gave the conversation, and the exact match to a connected copy still needs the account to agree (Zendesk names its subdomain in a ticket's own address; the others do not name one, so they are matched by the heuristic).

Sierra and Decagon publish no export format, so there is no reader for either. A file from either is read by the confirmed mapping, like any other, until there is a real sample to build one from. Sending an export from the [import API](#import-api) is the same: add ?format=zendesk (or another tool's name) to read the body that way.

Import API

For history that lives somewhere this product does not connect to: an export, a data warehouse, a script over a database. Post it. It is the same road as the upload — the same format, the same writer, the same redaction — and the same two steps: a check that stores nothing, then the same body again with the check's fingerprint.

POST https://functioninghq.com/api/import
Authorization: Bearer sai_<key id>_<secret>

The key. Make an import key under Settings › Sources › Send files from a script. It is shown once, we keep only a hash, and it can do one thing: send files here. The signals API, the OpenTelemetry address, inbound email and the widget refuse it, and it cannot read anything back, start a play or reach your helpdesk. A workspace has one at a time; revoke it and make another if it is lost. Making one takes manage connections, and a plan that takes no import (Free) is refused before the key exists and again on every request.

The body is JSON Lines in the format above, one conversation per line. Compress it with gzip (Content-Encoding: gzip) if it is large. It takes up to 20,000 conversations and 10 MB once decompressed, and 4 MB on the wire; split a larger history into several requests. A key may send 30 requests a minute and 200,000 conversations a day.

Check, then commit.

  1. Send the body with no confirm. You get counts, the fingerprint of how the body was read, the first twenty refusals with the line and the reason, what was left out, and what redaction cannot do on a body like this. Nothing from the body is stored: not the conversations, not a sample, not the request.
  2. Send the same body to ?confirm=<fingerprint>. It is read again, and if it is not what the check fingerprinted the answer is 409 and nothing is stored. Sending the commit twice stores nothing the second time: its rows are recognized.
# history.jsonl: one functioninghq.conversation/v1 per line (see "The format" above)
curl -sS -X POST https://functioninghq.com/api/import \
  -H "Authorization: Bearer $FUNCTIONINGHQ_IMPORT_KEY" \
  -H "Content-Encoding: gzip" \
  --data-binary @<(gzip -c history.jsonl)

The check answers:

{
  "dryRun": true,
  "format": "jsonl",
  "fingerprint": "5d41b7e0c3a9f204",
  "rows": 1204,
  "importable": 1198,
  "refused": { "undated": 2, "beyondRetention": 3, "invalid": 1, "removed": 0 },
  "firstRefusals": [{ "where": "line 17", "id": "T-1042", "reason": "startedAt must be an ISO 8601 date" }],
  "dropped": { "notes": 12, "toolResults": 0, "originsIgnored": 0, "unknownFields": [] },
  "retentionCutoff": "2025-10-10T00:00:00.000Z",
  "redactionWarning": null,
  "suggestion": null,
  "blockers": [],
  "next": "Send the same body again to /api/import?confirm=5d41b7e0c3a9f204 to store 1198 conversations."
}

Then store them, with the same body and the fingerprint it returned:

curl -sS -X POST "https://functioninghq.com/api/import?confirm=5d41b7e0c3a9f204" \
  -H "Authorization: Bearer $FUNCTIONINGHQ_IMPORT_KEY" \
  -H "Content-Encoding: gzip" \
  --data-binary @<(gzip -c history.jsonl)
{
  "dryRun": false,
  "fingerprint": "5d41b7e0c3a9f204",
  "parsed": 1204,
  "stored": 1198,
  "skipped": 0,
  "rejected": 1,
  "undated": 2,
  "beyondRetention": 3,
  "removed": 0,
  "rejections": [{ "where": "line 17", "reason": "startedAt must be an ISO 8601 date" }]
}
StatusMeaning
200A check, or a commit that stored something or had nothing to refuse.
400The body is empty or not valid gzip, or the query is not one this route takes.
401No key, or a key that is not live. One answer for every kind of bad key.
403wrong_key: not an import key. plan_limit: the plan takes no import.
409fingerprint_mismatch: the body is not what the check fingerprinted. Check it again.
413The body is over the size bound, on the wire or decompressed.
422A commit that stored nothing because every conversation was refused, or a body that cannot be imported yet (blockers).
429Over the key's rate. Retry-After says when.

A refusal is a sentence about a field and the line it was on, never a quotation from the body. Whatever the answer, the audit trail records the counts and the fingerprint with the key's public half, and never a row.

Another tool's export. Add ?format=zendesk (or intercom, helpscout, gorgias, freshdesk, front, crisp, chatbase, langfuse, langsmith, braintrust) and the body is read by that tool's own reader, with the same check and the same fingerprint. A body that looks like one of them and does not say so is not imported: the check answers with what it looks like and the ?format= to send.

Watched bucket

For an export that recurs and has nowhere to be posted from: Sierra's or Decagon's, a warehouse drop, anything a script writes to cloud storage. Point FunctioningHQ at a folder in an Amazon S3 or Google Cloud Storage bucket you own, and each night the objects that are new there are read through the same road as an upload: the same format, the same checks, the same redaction, the same writer. Make it under Settings › Sources › Watch a bucket. Making it takes manage connections, and a plan that takes no import (Free) is refused before anything is made.

  • We read, and only read. The credential you give us lists the folder and gets the objects in it, and nothing else. Our client has three calls, list, head and get; it has no way to write to your bucket, overwrite or delete anything in it. For S3 the role we assume is also narrowed to those two reads when we assume it, so a role you made too wide still cannot be used to write.
  • Where we connect is ours to decide. The address is built from the region you choose out of a list (S3) or is Google's one address, and the bucket is a name checked against a pattern. A pasted address is refused, and so is a redirect.
  • You look at a sample first. Before anything is read, the screen runs the upload's own check on one object in the folder: how it was read, what would be refused and why, and what redaction cannot do on a file. You pick the columns (or a tool's reader), check again, and confirm. The confirmation records the fingerprint of how the object was read and who confirmed it.
  • Nothing is imported on a guess. An object that no longer reads the way you confirmed (a column renamed, a field moved, another tool's export) is held with the reason, counted, and shown on the bucket's row. A held object is read again when its version changes or when you confirm the mapping again.

Amazon S3

You make one role in your own AWS account. FunctioningHQ holds no AWS key of yours: our role (the ARN is printed on the screen) assumes yours, and only with an ExternalId. The ExternalId is ours, random and one per bucket; it is what stops anyone who learns your role's name from having us assume it for them. It is not a secret, and the screen prints it inside the policy.

  1. On the screen, choose Amazon S3, give the bucket, the folder (for example exports/support/, with the slash) and the bucket's region, and press Start.
  2. In IAM, create a role with this trust policy. The screen prints it with our role's ARN and your ExternalId; this is its shape:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::111122223333:role/functioninghq-import"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "functioninghq-q3XkF9aPz1mC7vLw2RtY8HnD"
        }
      }
    }
  ]
}
  1. Give the role this permissions policy, and nothing more. A HEAD request needs s3:GetObject, so there is no third statement:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListTheWatchedFolder",
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::acme-support-exports",
      "Condition": {
        "StringLike": {
          "s3:prefix": [
            "exports/support/*"
          ]
        }
      }
    },
    {
      "Sid": "ReadObjectsInIt",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::acme-support-exports/exports/support/*"
    }
  ]
}
  1. If the objects are encrypted with a KMS key of your own, the role also needs kms:Decrypt on that key.
  2. Paste the role's ARN (arn:aws:iam::123456789012:role/functioninghq-read) on the screen and press Check and connect. We list the folder and head the first object, and store nothing if that fails.

When you stop watching the bucket the credential on our side is destroyed. Delete the role in your account as well; that is the half only you can do.

Google Cloud Storage

Google's storage speaks the S3 protocol when a request is signed with an HMAC key, so it is the same client.

  1. On the screen, choose Google Cloud Storage, give the bucket and the folder, and press Start.
  2. In your project, create a service account for this and nothing else.
  3. Give it the role Storage Object Viewer on the bucket, with this IAM condition so it reaches the folder and no other:
resource.name.startsWith("projects/_/buckets/acme-support-exports/objects/exports/support/")
  1. Create an HMAC key for the service account (Cloud Storage › Settings › Interoperability). Paste the access ID and the secret on the screen. The secret is posted once, kept encrypted, sent only to storage.googleapis.com, and never shown again, logged or put in an audit event.

What is read, held and skipped

An objectWhat happens
.csv, .jsonl, .ndjson, .json, each with or without .gzRead the way you confirmed.
Any other name (_SUCCESS, a Parquet file, a manifest), and folder placeholdersNot a file we read. Recorded as such so it is not asked about every night, and never fetched.
Over 200 MB, or over 200 MB once decompressedHeld, with the size. Decompression stops at the limit rather than finishing and then looking.
Not valid gzip, or not UTF-8 textHeld.
Reads differently from the confirmed mappingHeld, naming the columns that moved.
Holds more than 20,000 conversationsHeld: one object takes at most what an upload does. Split it.
Changed while it was being readNot taken; read again tonight.

An object is read once per version (its name and its ETag). A conversation is stored once, by your id for it, so a later object that carries the same id changes nothing that is stored: it is recognised and left as it was. A new version of an object (the ETag changed) is read again, and only the conversations in it that are new are added. An object deleted from the bucket deletes nothing here. Because the same conversation read again is recognised and not rewritten, erasing a person in the product holds only until an object that carries them changes: remove their conversations from the file as well.

A night lists at most 10,000 keys of the folder, in the order the provider lists them, and takes the new objects in them oldest first. It resumes where the last slice ended and starts again from the beginning when it reaches the end of the folder, so in a folder of more than 10,000 objects a new one is found when the slice reaches it. Use dated folders, and put new exports under them.

Limits

One object200 MB stored, 200 MB decompressed, 20,000 conversations
A night1,000 new objects, 20,000 conversations, about four minutes; what does not fit waits for tomorrow
A sample on the screen10 MB, so the check is on the whole object
BucketsPer plan: none on Free, one on Starter, three on the larger plans

A night's read is recorded as counts: how many keys were listed, objects read, conversations stored, already here, refused, held and not read. Pausing a bucket stops reading from it and nothing else; resuming carries on from where it stopped. A bucket that fails two nights running is a connection that has stopped working, and the team is told once, as for any source.

Nothing is stored about an object's name except a hash of it and its last two path segments with anything personal removed, because a name can hold a customer's name or address. Nothing of what an object says is stored but through the writer, redacted.

Something missing, or a field that does not behave as this says? Tell us — the contracts here are what the code is held to, so a page that is wrong is a bug in the same sense the code would be.