Skip to main content

Mint a key

  1. Open Settings → Integrations → API integration (above Webhooks).
  2. Under Create new key, enter a descriptive name (e.g. prod-twilio-uploader) and click Create.
  3. Copy the key once — Zelto only stores a hash.
The dedicated page lists keys with their last-used timestamp. Delete a key any time to revoke access. Minting and revoking need the 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 is zelto-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.
Run this in a server-side Node.js 18+ job after the conversation ends. Never put an organization API key in browser code or a public environment variable.
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 as ZELTO_API_KEY — the prompt tells the agent to read it from the environment, never hardcode it.
Paste into your coding agent
If your editor has the Zelto MCP server connected, the agent can call its read_docs tool to pull the always-current contract instead of the embedded copy — and the same key works for MCP, the REST API, and this upload flow.

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
A successful upload returns HTTP 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.
To check from code whether a stored conversation was analyzed, read its 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-level versionConfig 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, include version 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-level companyExternalId with every conversation. This is per-conversation attribution, so one shared agent can handle consecutive conversations for different companies:
Use the same stable value for every conversation belonging to the same company. When Companies is enabled, the first unseen value creates a company named after that value; rename it in the dashboard and later conversations keep the mapping. If the field is absent, Zelto uses the agent’s default company, if one is set. Otherwise the conversation remains unattributed. See Companies for the complete model and Set up companies for the dashboard steps.

Agent groups

Send agent.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 a tool 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 as transcript.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 an error 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 the X-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.