Skip to main content
Give this page to your AI assistant. It’s written for the assistant, and every step links to the API reference page with the exact request and response.
Before changing any Telzino AI agent, read https://docs.telzino.com/configure-with-ai/runbook.md and follow it step by step.

Ground rules

  1. Only use documented endpoints and fields. The API reference and the OpenAPI spec at https://api.telzino.com/api-doc/openapi are the source of truth. Never guess an endpoint, field or value.
  2. Propose before you change. Show the user every field you will change, with the old and new values, and wait for their approval before any POST, PUT, PATCH or DELETE.
  3. Change one agent at a time, and read it again after each change.
  4. Never delete an agent, knowledge base, source or other resource, and never place an outbound call, unless the user asks for that specific action.
  5. Keep secrets out of the chat. Read the client ID and secret from the environment. Never print them, a token or any credential stored on an agent.

Step 1: Get a token

Exchange the client ID and secret for a bearer token with POST /oauth/token. Send Authorization: Bearer <access_token> on every request. Tokens last 24 hours. On a 401, get a new token once and retry. Then call GET /v1/me to see the account and the key’s scope. If the key is limited to one reseller or organization, stay inside it. A request outside it returns 403.

Step 2: Find the agent

Call GET /v1/agents with organization_id to list agents. Use page and limit (max 100) and keep paging until you’ve seen them all. Match the agent the user named by name, and confirm with the user if more than one matches.

Step 3: Read the agent

Call GET /v1/agents/{agentId} and keep the full response. This is your “before” copy.

Step 4: Propose the change

Build the update body from the Update Agent reference. Watch for these rules:
  • Reads and writes use different names. Get Agent returns snake_case top-level keys (system_prompt). Update Agent takes camelCase (systemPrompt) and rejects keys it doesn’t recognise. Keys inside nested objects such as config and voiceSettings stay snake_case.
  • Send only the fields you change. Fields you leave out stay as they are.
  • Many objects are replaced whole, not merged, for example extensions, voiceSettings, pronunciations and interpreterConfig. Start from the current value, apply the change and send the whole object back.
  • email is returned as a string but must be sent as an array of addresses.
Show the user a before and after table of the changed fields and wait for approval.

Step 5: Apply the change

Call PUT /v1/agents/{agentId}. Include organizationId so the request is refused if the agent isn’t in the organization you expect. If the API returns 400, show the user the error and its details. Don’t retry with guessed values. To turn an agent on or off, set billing_state to live or off with the same PUT /v1/agents/{agentId} call.

Step 6: Verify

Call Get Agent again and compare it with your “before” copy. Confirm that only the approved fields changed. Then call GET /v1/agents/{agentId}/history: the newest entry should list your changes. Note its id.

Step 7: Undo if needed

If the user wants to undo, find the version from before your change in the history and call POST /v1/agents/{agentId}/history/{versionId}/revert. Use the entry’s id, not its version number. A revert is saved as a new version, so it can be undone the same way.

Reading calls

To review how an agent is doing, call GET /v1/agents/{agentId}/call-logs. Each call log has a summary and the transcript. Call logs contain caller details: only quote what the user needs, and don’t copy transcripts into other tools.

More endpoints

The Agent Runbook for developers lists every endpoint, from knowledge bases to guardrails and retry policies.