Docs - AI phone agents for SMB

@telzino/server sends texts and places outbound calls with a Telzino API key. It runs on your server (Node.js 18 or later). Never ship it, or the key, to a browser: for the browser use chat and voice with a publishable key.

npm install @telzino/server

import { TelzinoServer } from '@telzino/server';

const telzino = new TelzinoServer({
  clientId: process.env.TELZINO_CLIENT_ID!,
  clientSecret: process.env.TELZINO_CLIENT_SECRET!,
});

The SDK gets an access token with the client credentials flow, keeps it until shortly before it expires, and gets a new one if the key’s secret was rotated. Every request gives up after 30 seconds.

Send a text

const msg = await telzino.sms.send({
  agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
  to: '+15551234567',
  body: 'Your order is ready for pickup.',
  idempotencyKey: 'order-9312-ready', // optional: a retry never sends twice
});
// { id, status: 'queued', to, from, agent_id }

The text goes out from the agent’s SMS number and joins that customer’s conversation. When the customer replies, the agent answers. See Send SMS for the rules: the agent needs an enabled SMS number, and recipients who texted STOP are refused.

Place an outbound call

const call = await telzino.calls.create({
  agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
  to: '+15551234567',
  callContext: 'You are calling Sam to confirm tomorrow at 3pm.',
  greeting: 'Hi Sam, this is Ava from Bright Dental.',
});

callbackUrl and metadata are supported too. Any other field of Trigger Outbound Call goes in extra, in the API’s snake_case, for example extra: { retry_policy_id: '...' }.

Which key to use

Create the key in the dashboard under API Keys. For a backend that only texts and calls for one agent, choose Access → One agent: that key can send that agent’s texts and place its calls, and nothing else. See Agent-scoped API keys.

Errors

Failures throw a TelzinoApiError with the HTTP status and the API’s code:

import { TelzinoApiError } from '@telzino/server';

try {
  await telzino.sms.send({ agentId, to, body });
} catch (err) {
  if (err instanceof TelzinoApiError && err.code === 'opted_out') {
    // the customer texted STOP: do not retry
  } else throw err;
}

Common codes: opted_out, sms_not_enabled, rate_limited, not_found, insufficient_scope, invalid_request.

Setup Guides

Managing AI agents

Telzino Dashboard

Connect App

Agent Settings

Agent Functions

NetSapiens Functions

Event Webhooks

Agent Examples

Integrations

SDK

White Label

Configure agents with AI

Developers

Server SDK

Send a text

Place an outbound call

Which key to use

Errors