Mint a key
- Open Settings → Integrations → API integration (above Webhooks).
- Under Create new key, enter a descriptive name (e.g.
prod-twilio-uploader) and click Create. - Copy the key once — Zelto only stores a hash.
owner or admin
role — a key reads every conversation in the
organization, so it isn’t a member-level credential.
TypeScript SDK
The official npm package iszelto-sdk. Conversation ingestion is new in 0.4.0;
0.3.0 only supports legacy web analytics. Check npm view zelto-sdk version
before installing. If 0.4.0 is not available, use the HTTP example below.
stored: true means accepted for asynchronous processing. Verify arrival in
Conversations or through REST/MCP. Under four turns is stored but not analyzed.
For another deployment, pass the full bootstrap endpoints.ingestCalls URL as
ingestUrl; the default is https://ingest.zelto.ai/webhooks/calls.
Use the organization API key, not the write-only OpenTelemetry ingestKey.
Await delivery in your durable job. The SDK has a 10-second timeout (configurable
with timeoutMs) and no automatic retries. Retry network errors, 429 and 5xx
with your queue’s backoff and the same complete payload and call.externalId.
Fix other 4xx errors before retrying. Re-sending an ID replaces its conversation.
HTTP errors throw ZeltoApiError with status and details; details can contain
sensitive data, so avoid logging them. stored: false needs handling even on HTTP 200.
The existing zelto.init / track / identify exports are for web analytics;
use new Zelto(...).sendConversation(...) for AI conversation ingestion.
Set up with a coding agent
Don’t want to wire this up by hand? Paste the prompt below into the coding agent in your editor — Claude Code, Cursor, Codex, or similar. It points the agent at this guide and the API reference, spells out the full upload contract, and has it send each finished conversation following your own codebase’s conventions. You still supply the key: mint one above and expose it asZELTO_API_KEY — the
prompt tells the agent to read it from the environment, never hardcode
it.
Paste into your coding agent
Upload a conversation
POST the whole conversation — agent, transcript, optional recording, and metadata — in one request to/webhooks/calls. Zelto acknowledges
immediately and processes it into a conversation and transcript in the
background. The API Reference tab covers the REST conventions and has a request
playground for verifying a payload before you wire up production.
The example below is a voice call; a text conversation is the
same shape with the audio fields left out.
call.json
200 with { "received": true, "stored": true }.
The 200 body also tells you what Zelto decided at the time of the request. All
fields except received are optional, so keep ignoring unknown fields:
Zelto analyzes a conversation only when it has at least 4 turns in
transcript.turns. A shorter one (an instant hangup, a one-line test) is
still stored and appears under Conversations, but it gets no summary or
findings and is not billed. If your first test conversation shows up without
analysis, send one with four or more turns.Zelto decides whether a conversation fits your plan’s monthly conversation
minutes after it has answered
200, so the response is the same in or out of
the allowance and has no field for it. A conversation is analyzed only if its
whole duration fits in the minutes left this month; one that does not fit is
still stored and readable but not analyzed, while a shorter one that fits is.
Skipped conversations show Not analyzed in Conversations and in their
details, and the Usage tab counts them. A voice conversation sent without call.durationSeconds is
also stored but not analyzed until a duration is recorded. See
Plans.Minutes are rated once. If you re-send a call.externalId with a longer
call.durationSeconds, only the added minutes are rated (and must fit what is
left of your plan, like a new conversation); if they do not fit, the re-send
still updates the transcript but the duration stays at what was already rated.
A shorter or equal duration changes nothing. A voice conversation sent with a
duration of 0 is treated as having no duration. A conversation with a
recording is voice whatever its channel metadata says; only one without
audio counts as text.analysisStatus from GET /v1/conversations (each item) or
GET /v1/conversations/{id}, or from the MCP list_conversations and
get_conversation tools:
New values may be added later; treat any value you do not know as “not
analyzed yet”.
Only
call.externalId and an agent reference are required; everything
else is optional. Provide either agent.externalId (Zelto finds or
creates the agent for you) or agentId to attach the conversation to an agent
you already created in the dashboard. If you made the agent by hand, send its
agentId: a different agent.externalId creates a second agent. Include call.recordingUrl and Zelto
re-hosts the audio so the player keeps working past your source’s recording TTL.
Set version to label the agent build or prompt revision behind the conversation
(e.g. "v3"); Zelto tracks it as the conversation’s agent version so you can compare
performance across versions on the agent’s page. It’s optional and works with
either agent reference — send the same string for conversations on the same build.
Supply the release configuration
Send optional top-levelversionConfig with version to record everything that release uses. It is a JSON object up to 64 KiB; llm, stt, and tts are conventional component names, and arbitrary tools, workflows, runtime settings, and custom fields are preserved. This is version context, separate from per-conversation metadata. It is captured on creation and does not overwrite an existing snapshot. See Agent versions for the form, registration API, and a complete example.
Version contract for experiments
For reliable experiment attribution, includeversion on every conversation from
each release. It is a case-sensitive string of 1–255 characters after trimming.
The same agent and label reuse a version; a new label creates one when its first
conversation is processed. Change the label for pipeline changes as well as prompt edits.
A label in metadata.version does not assign the conversation to an agent version.
Keep the agent ID stable across releases, preserve the version that actually
handled the session, and send its systemPrompt and captured configuration.
Do not rely on automatic prompt-based detection to distinguish concurrent
experiment releases or pipeline-only changes.
See Agent versions for examples, snapshot limitations,
provider behavior, retries, and the two-release verification checklist.
Attribute each conversation to a company
If your organization operates agents for several clients or brands, send a top-levelcompanyExternalId with every conversation. This is per-conversation attribution, so
one shared agent can handle consecutive conversations for different companies:
Agent groups
Sendagent.groups to organize agents that belong together — for example the
several agents in one area, language, team, or campaign. Each name is a group;
Zelto finds-or-creates it in your organization
and adds the agent to it. An agent can belong to more than one group, and the
field is additive — a later upload never removes a group the agent already has,
so it’s safe to send on every conversation. Once an agent is in a group you can filter
the whole dashboard by that group from the sidebar, and filter the
conversations list by group. You can also manage an
agent’s groups by hand on its settings page in the dashboard.
A group does not attribute conversations to a company. Use
companyExternalId for a
client or brand and agent.groups for flexible agent-level organization.Tool calls
If your agent invokes tools mid-call (function calls — check availability, book an appointment, look up an order), forward each one as atool turn carrying a
structured toolCall. Zelto shows tool calls inline in the transcript, records
them as queryable tool-call traces, and feeds
the structured conversation — name, arguments, and result — into its AI analysis
(summaries, findings, scorecards, metrics). So you send the tool call once,
as structured data; you do not need to also hand-render it into the turn’s
content.
A toolCall is { name, arguments?, result?, status?, toolCallId?, errorMessage? } — only name is required. arguments and result are any
JSON; status is success, error, or pending; toolCallId correlates an
invocation with its result if you send them as separate turns. The turn’s
content may be empty when a toolCall is present (Zelto labels it with the
tool name), and startSeconds still orders it in the timeline.
Text and messaging conversations
The same endpoint ingests text conversations — a chatbot or messaging agent (web chat, SMS, WhatsApp, in-app). Send the messages astranscript.turns and
omit the audio and telephony fields; there’s no recording to re-host. See
Chatbot & text conversations
for the full text-specific contract and a chat.json example.
Handle errors
Errors come back as JSON with anerror string; validation and provider errors
add a details object naming what to fix.
A
200 means Zelto accepted the conversation and is processing it in the
background — not that ingestion has finished. Bad auth and malformed bodies
fail synchronously with a 4xx, but a semantic problem like an agentId that
doesn’t exist in your org still returns 200 and then fails quietly, so it
never appears. Prefer agent.externalId (find-or-create) to avoid that, and
confirm conversations land under Conversations.A delivery that carries neither a transcript nor a recording is treated as
an unconnected dial: Zelto acks it with 200 but intentionally creates no
conversation, since there’s nothing to transcribe or analyze. Send the conversation
once it has a transcript or recordingUrl (a later
enrichment re-send with one of them ingests
normally).Idempotent re-uploads
call.externalId is the dedup key. POSTing the same id again updates
the existing conversation in place — refreshing the recording, transcript,
duration, or cost — and never double-charges. The transcript is replaced,
not merged: a re-send with fewer turns overwrites the longer one. The 200 says
so with "updated": true and "previousTurns". Send the conversation once when it
ends, then re-send later if you enrich it (e.g. once the recording
finishes uploading).
Already on Vapi or Retell?
The same endpoint also accepts native Vapi and Retell webhook payloads — set theX-Zelto-Provider header to vapi or retell and POST that
provider’s body unchanged. Omit the header (or send zelto) to use the
canonical shape above.
Verify the first conversation
After your first POST, open Conversations — the conversation appears within a few seconds with its transcript. The API Reference tab’s request playground is the fastest way to send a test payload. If a conversation doesn’t show up, check the response your POST got —{ "received": true, "stored": true } means Zelto accepted
it ("stored": false explains in reason why nothing was kept), while a 4xx returns the reason in the body (an unsupported X-Zelto-Provider
value, a failed field validation, or an invalid key). See
Connect a voice provider.
When to use this vs a native integration
If you already run on Vapi or Retell, use the native integration — webhooks land for free and recordings are fetched for you. This page is for everything else: Bland, Pipecat, a text or messaging agent, in-house stacks, or anything we haven’t shipped a first-class card for yet. Running on LiveKit? It has a dedicated LiveKit page.Related
- Chatbot & text conversations — the same endpoint for text, no audio.
- Connect a voice provider — pick the right path.
- LiveKit — the same endpoint, with a worker example.
- API reference — REST conventions and the full request shape.
- Conversations — where uploaded conversations land.

