Docs - AI phone agents for SMB

Also available from the API: GET /v1/webhook-event-types (reference). Levels are the endpoint levels that can subscribe to an event. An event that happens in an organization reaches that organization’s endpoints, and reseller and account endpoints that also receive events from the levels below (levels). Data fields are the keys of data. The IDs of where it happened (partner_id, reseller_id, org_id, agent_id) are always in the envelope (payloads) and usually not repeated in data. The exceptions are org.created, org.suspended, org.reactivated, org.cancelled and partner.ns_agents_tab_live, which also carry organization_id in data. A flat name of — means the event type is used as event in the flat format.

First events

Account firsts (account.*, the partner.* firsts, agent.first_personalized and agent.first_knowledge_base_added below) fire once per account, ever, and only while the account is on its trial — deleting and recreating an agent does not fire account.first_agent_created again, and an account that is no longer a trial does not fire them.
Organization and agent firsts (org.first_*, agent.first_call_received) fire once per organization or agent, ever, on any plan. Organizations and agents that existed when these events were introduced count as already having reached them, so they never fire for them. Accounts whose agents had already reached agent.first_personalized or agent.first_knowledge_base_added count as having reached them too.

A real call is an inbound phone call (not a web or widget call, not a dashboard playground call) to an agent that is not a demo agent, lasting at least the minimum duration Telzino sets for the platform. account.first_call_received and org.first_call_received / agent.first_call_received count every inbound call, test calls included.

Onboarding

Event	Flat name	Levels	Description	Data fields
`account.first_agent_created`	`agent_created`	account	The account created its first agent while on its trial (once per account, ever).	agent_name, agent_extension
`account.first_call_received`	`first_call_received`	account	The account’s agents received their first inbound call while it was on its trial, test calls included (once per account, ever).	call_duration_seconds
`account.first_real_call_received`	`first_real_call_received`	account	The account’s agents received their first real call while it was on its trial (once per account, ever).	call_duration_seconds
`partner.ns_ui_config.created`	`ns_ui_config_created`	account	A NetSapiens UI config was created successfully while the account was on its trial (once per account, ever).	—
`partner.userbase_claim.verified`	`ns_base_claimed`	account	A NetSapiens user base claim was submitted and verified while the account was on its trial (once per account, ever).	—
`partner.ns_agents_tab_live`	`ns_agents_tab_live`	account	The AI Agents tab in the NetSapiens portal opened successfully for the first time while the account was on its trial (once per account, ever).	claim_id, organization_id, domain
`trial.expiring`	—	account	The account’s trial ends within the number of days Telzino sets for the platform (once per account). `credit_remaining` is `null` when the balance is not known.	trial_ends_at, days_left, credit_remaining
`org.first_agent_created`	—	account, reseller, organization	The organization created its first agent (once per organization, ever).	agent_name, agent_extension
`org.first_call_received`	—	account, reseller, organization	The organization’s agents received their first inbound call, test calls included (once per organization, ever).	call_duration_seconds
`org.first_real_call_received`	—	account, reseller, organization	The organization’s agents received their first real call (once per organization, ever).	call_duration_seconds
`agent.first_call_received`	—	account, reseller, organization	The agent received its first inbound call, test calls included (once per agent, ever).	call_duration_seconds
`agent.first_personalized`	—	account, reseller, organization	A person or API key first changed the settings of one of the account’s agents while it was on its trial (once per account, ever). `agent_id` is that agent.	changed_fields
`agent.first_knowledge_base_added`	—	account, reseller, organization	One of the account’s agents was first given a knowledge base while the account was on its trial (once per account, ever). `agent_id` is that agent.	knowledge_base_id

Lifecycle

Event	Flat name	Levels	Description	Data fields
`reseller.created`	—	account	A reseller was created.	name, external_id, plan, created_by, created_by_type
`org.created`	—	account, reseller	An organization was created.	organization_id, name, external_id, plan, created_by, created_by_type
`agent.created`	—	account, reseller, organization	An agent was created. Restoring a deleted agent does not fire it.	agent_name, agent_extension, agent_type, plan, created_by, created_by_type
`agent.updated`	—	account, reseller, organization	An agent’s settings were changed.	changed_fields, actor
`agent.prompt_changed`	—	account, reseller, organization	An agent’s prompt was changed (also fires `agent.updated`).	actor
`agent.knowledge_base_updated`	—	account, reseller, organization	An agent’s knowledge base or its knowledge base settings were changed (also fires `agent.updated`).	knowledge_base_id, actor
`agent.deleted`	—	account, reseller, organization	An agent was deleted. `actor` is always `null` today.	agent_name, actor
`partner.userbase_claim.created`	—	account	A NetSapiens user base claim was submitted (every claim, any plan). Credentials are never included.	claim_id, name, territory, portal_url
`partner.userbase_claim.rejected`	—	account	A NetSapiens user base claim was refused. `reason` is `invalid_credentials` or `already_claimed`.	reason, portal_url
`org.suspended`	—	account, reseller, organization	The organization was suspended.	organization_id, reason, actor
`org.reactivated`	—	account, reseller, organization	The organization was reactivated after a suspension. `reason` is always `null` (reactivating clears it).	organization_id, reason, actor
`org.cancelled`	—	account, reseller	The organization was deleted. `actor` is always `null` today.	organization_id, name, actor

agent.updated, agent.prompt_changed and agent.first_personalized fire for Telzino voice agents only. agent.knowledge_base_updated and agent.first_knowledge_base_added fire for every agent type, as do agent.created and agent.deleted. plan is the account’s subscribed plan name, "trial" while the account is on its trial, or null. Resellers, organizations and agents carry their account’s plan.

Who created it

created_by_type says what kind of identity created the record. created_by is the same identity as a prefixed string, <created_by_type>:<id>, like actor:

`created_by_type`	`created_by`
`user`	`user:<id>` — the dashboard user, by user ID.
`api_key`	`api_key:<id>` — the API key used, by key ID.
`ns_user`	`ns_user:<ns_user_id>@<ns_domain>` — the NetSapiens user, including resellers and organizations created automatically when that user first opened AI Agents.
`system`	`system:<id>` — created by Telzino.

Both are null when the creator is not known; the event is still sent.

Actor

actor says who made a change, as a prefixed string, or null when that is not known:

`actor`	Who
`user:<id>`	A dashboard user, by user ID.
`api_key:<id>`	An API key, by key ID (organization suspend and reactivate). Agent changes made through the API have `actor` `null`: the key is not recorded on the agent.
`ns_user:<user>@<domain>`	A NetSapiens user, working in Connect.
`super_user`	Telzino staff. Which staff member is never sent.

There is no agent.published event: agents are live as soon as they are saved, so there is no publish step to report.

Account, billing and users

Event	Flat name	Levels	Description	Data fields
`plan.changed`	—	account	The account’s plan changed. `change_type` is `upgrade`, `downgrade`, `changed` (a different plan at the same price), `cancel_scheduled` (a cancellation was requested) or `cancelled`. `to_plan` is `null` when `cancelled`.	change_type, from_plan, to_plan, effective_at
`payment.failed`	—	account	A payment failed. `source` is `subscription_invoice`, `wallet_topup` or `auto_recharge`. `attempt` is `null` for `wallet_topup`. Sent for every failure.	source, amount_cents, currency, failure_reason, attempt, auto_recharge_paused
`balance.low`	—	account	The account’s balance is at or below its low balance threshold but above $0. Same check and threshold as the low balance email, run every 5 minutes after any auto-recharge attempt, so a successful auto-recharge sends nothing. Fires once, and again after the balance goes back above the threshold. `balance_cents` and `threshold_cents` are US-dollar cents. Resellers and organizations share the account’s balance and do not receive it. Not sent for accounts on their trial.	balance_cents, threshold_cents, auto_recharge_enabled
`balance.zero`	—	account	The account’s balance is $0 or less. Same check as the zero balance email, run every 5 minutes after any auto-recharge attempt, so a successful auto-recharge sends nothing. Fires once, and again after the balance goes back above $0. `balance_cents` and `threshold_cents` are US-dollar cents. Resellers and organizations share the account’s balance and do not receive it. Not sent for accounts on their trial.	balance_cents, threshold_cents, auto_recharge_enabled
`usage.threshold_reached`	—	account	The account has used 50, 80 or 100 percent of its included minutes. Each threshold fires once, and again after minutes are added back (a new billing period or a top-up). After a plan change, thresholds the account is already past are recorded without being sent.	threshold_percent, minutes_included, minutes_remaining
`user.invited`	—	account, reseller	A user was invited to the account or reseller.	user_email, role, invited_by
`user.created`	—	account, reseller	A user joined the account or reseller.	user_email, role
`user.role_changed`	—	account, reseller	A user’s role changed.	user_email, from_role, to_role
`api_key.created`	—	the key’s level	An API key was created. The key itself is never included.	api_key_id, api_key_name, key_scope
`api_key.revoked`	—	the key’s level	An API key was revoked, including each key of an organization or reseller that was deleted.	api_key_id, api_key_name, key_scope
`webhook.disabled`	—	account, reseller, organization	A webhook endpoint at this level was disabled after failing continuously.	endpoint_id, endpoint_name, reason, disabled_at

Telzino only

Telzino’s own platform endpoints can subscribe to every event on this page, and also to these, which no account, reseller or organization endpoint receives:

Event	Flat name	Description	Data fields
`partner.created`	—	A partner account was created.	name, plan, created_by, created_by_type
`account.signed_up`	`account_signed_up`	An account signed up and its trial credit was applied.	signup_at, trial_ends_at, credit_amount, ref
`account.updated`	`account_updated`	A trial account’s PBX type changed.	changed_fields
`plan.purchased`	`plan_purchased`	An account’s subscription became active.	plan_name
`trial.credit_low`	`credit_low`	A trial account’s credit fell to or below the low credit threshold.	credit_remaining
`trial.credit_exhausted`	`credit_exhausted`	A trial account’s credit reached $0 or less.	credit_remaining

Calls

Call events are sent when the call ends, except integration.connection_failed, which is sent as soon as the failure happens (usually mid-call). Caller details and summaries are sent only in the phi object, and only when the organization allows it.

Event	Flat name	Levels	Description	Data fields
`call.completed`	—	account, reseller, organization	A call ended and its record was saved. `transcript_url` opens the call in the dashboard (sign-in required); it can be `null`. `summary` is included only when the organization redacts personal details from transcripts. `transfer` is included only when the agent has at least one transferred-call context setting on, or the call was handed over by another AI agent whose call already had transfer context.	call_id, direction, started_at, ended_at, duration_seconds, resolution_status, sentiment, transcript_url, summary, transfer
`call.transferred_to_human`	—	account, reseller, organization	The agent transferred the caller to a person and the transfer went through. `transfer_type` is `blind`, `warm` or `web`. `succeeded_at` is when the person took the caller. A hand-off to another AI agent does not count.	call_id, transfer_type, succeeded_at
`call.escalated`	—	account, reseller, organization	The call ended with resolution status `escalated`.	call_id
`call.failed`	—	account, reseller, organization	The call failed. `reason` is `session_error`, `busy` (refused because the agent was at its call limit), `worker_error` or `dead_air`. `call_id` is `null` when no call record was saved.	call_id, reason
`call.voicemail_left`	—	account, reseller, organization	`kind` is `outbound_left` (the agent left a voicemail on an outbound call) or `inbound_routed` (a caller was routed to voicemail).	call_id, kind
`call.outcome`	—	account, reseller, organization	The agent recorded a business outcome: a calendar event or appointment booked or changed, a payment link sent, a listing link sent, or how a reservation call ended. One event per outcome (values). Custom webhook and MCP tools never count.	call_id, outcome_type, tool
`call.negative_sentiment`	—	account, reseller, organization	The call’s sentiment was Negative.	call_id
`integration.connection_failed`	—	account, reseller, organization	An agent could not reach an integration: an MCP server or ModMed could not connect, or a Google or Outlook calendar authorization expired and could not be refreshed. Sent when it happens, at most once per agent, integration and hour. `integration_type` is `mcp`, `modmed`, `google_calendar` or `outlook_calendar`. `error_kind` is `transport_error` (MCP timeout or network failure), `connect_failed` (any other MCP failure, ModMed) or `auth_expired` (calendars).	integration_type, integration_id, integration_name, error_kind

Call outcomes

`tool`	`outcome_type`
`create_event`, `outlook_create_event`	`calendar_event_created` (Google, Outlook)
`update_event`, `outlook_update_event`	`calendar_event_updated`
`modmed_schedule_appointment`	`appointment_scheduled`
`modmed_update_appointment`	`appointment_updated`
`process_payment_link`	`payment_link_sent`
`send_listing_link`	`listing_link_sent`
`reservation`	How a reservation agent’s call ended, sent for every reservation call: `booked_verified`, `booked_unverified`, `alternative_accepted`, `waitlist_offered`, `human_handoff`, `abandoned` (the default when nothing else was recorded), `info_only`, `error`, `transferred_to_human`, `voicemail_left`, `abandoned_unreachable`, `emailed_link` or `callback_scheduled`.

No outcome is sent for taking a payment: only the payment link being sent is reported.

Survey

Survey events are sent when a survey agent’s call ends. Each survey call sends exactly one of survey.completed, survey.partial and survey.refused, plus survey.detractor and survey.callback_requested when they apply. Survey calls still send call.completed. An existing endpoint receives survey events only after you subscribe it to them.

Event	Flat name	Levels	Description	Data fields
`survey.completed`	—	account, reseller, organization	Every required question that applied (its Only ask when condition held and no Skip when these transfer details are missing detail was empty) got an answer.	survey_version, call_id, parent_call_id, rep, queue, transferred_at, status, language, duration_sec, answers, flags, transcript_url
`survey.partial`	—	account, reseller, organization	At least one question was answered, but not every required question that applied (see `survey.completed`).	survey_version, call_id, parent_call_id, rep, queue, transferred_at, status, language, duration_sec, answers, flags, transcript_url
`survey.refused`	—	account, reseller, organization	No question was answered (the caller declined, opted out or hung up).	survey_version, call_id, parent_call_id, rep, queue, transferred_at, status, language, duration_sec, answers, flags, transcript_url
`survey.detractor`	—	account, reseller, organization	The survey’s detractor rule matched the answers. Sent in addition to the event above.	survey_version, call_id, parent_call_id, rep, queue, transferred_at, status, language, duration_sec, answers, flags, transcript_url
`survey.callback_requested`	—	account, reseller, organization	The caller asked for a callback, or answered yes to a question with Offer a callback when the answer is yes. Sent in addition to the event above.	survey_version, call_id, parent_call_id, rep, queue, transferred_at, status, language, duration_sec, answers, flags, transcript_url

All five carry the same fields:

call_id is the survey call’s own record; parent_call_id is the call the caller was transferred from (null when unknown). transferred_at and queue come from the transferred-call context.
rep is {id, name, extension, source}: the representative who handled the caller. id, name and extension are null when the representative is unknown. source is how the representative was found (referred_by, diversion, history_info, static_map, netsapiens_api, internal or unknown), and null when the call has no transfer context.
status is completed, partial or refused. language is en, es or fr. duration_sec is the length of the survey call, null when unknown.
answers lists the answered questions, in survey order: {key, type, value, confirmed, confidence}. A question that was not asked or not answered is not listed. The value of an open answer is null, unless PII redaction is on for the organization or the agent (then it is the redacted text). confidence is the speech-to-text confidence of the caller’s reply: informational only, and null when unavailable. With redaction on, each answer also carries the redacted raw text the caller said.
flags is {detractor, callback_requested, survey_opt_out}.
transcript_url opens the call in the dashboard (sign-in required); it can be null.

The caller’s number and the raw and open answer text follow the PHI rules. Redaction is on when PII redaction is on for the organization or for the survey agent; Webhook PHI is an organization setting:

Settings	Raw and open answer text
Redaction off, Webhook PHI off (default)	Not in any webhook: open `value` is `null`, no `raw`, no `phi`. Read the answers in the transcript via `transcript_url`. An End of Call Action still receives them
Redaction off, Webhook PHI on	Only in `phi`: `answers_raw`, `open_answers` (plus `transfer_ani`), and only to the endpoints your Webhook PHI setting covers
Redaction on, Webhook PHI off	Redacted text in `data` (`answers[].raw`, open `value`); no `phi`
Redaction on, Webhook PHI on	Redacted text in `data`; `phi` has only `transfer_ani`, and only for the endpoints your Webhook PHI setting covers

Monitoring

Monitoring events are worked out per endpoint, from the event settings you give that endpoint (event settings). Each one:

is sent only to the endpoint whose settings it met — two endpoints with different thresholds get different events;
fires once when its condition is met, then stays quiet until the condition clears (it re-arms), so it can fire again the next time;
is checked about once a minute.

Some need Telzino-side setup, and are not sent where it is missing:

agent.registration_lost / agent.registration_restored need registration polling of the SIP proxies (OPENSIPS_PROXY_TARGETS on the event worker). An agent counts as lost only after it was seen registered at least once. A round in which a proxy does not answer marks nobody as lost.
agent.latency_degraded needs the call-metrics store (CLICKHOUSE_URL on the event worker).

Event	Flat name	Levels	Description	Data fields
`agent.inactive`	—	account, reseller, organization	The agent has had no calls for `after_hours` hours (counting only `business_hours`, when set). The clock starts at the agent’s last call, or when the endpoint first started watching the agent, whichever is later. Re-arms on the agent’s next call.	threshold, observed, since
`agent.activity_resumed`	—	account, reseller, organization	The agent took a call after `agent.inactive` fired. Uses the `agent.inactive` settings. `since` is when the inactivity began.	since
`org.inactive`	—	account, reseller, organization	No agent of the organization has had a call for `after_hours` hours (counting only `business_hours`, when set). The clock starts as for `agent.inactive`. Re-arms on the next call.	threshold, observed, since
`org.activity_resumed`	—	account, reseller, organization	The organization took a call after `org.inactive` fired. Uses the `org.inactive` settings. `since` is when the inactivity began.	since
`agent.registration_lost`	—	account, reseller, organization	An agent with SIP registration turned on, and seen registered before, has not been registered for `debounce_minutes`. `reason` is `not_found` (no registration record on any proxy), `wrong_credentials` (the registrar refused the credentials), `timeout` (the registration request timed out), `registrar_error` (the registrar returned an error) or `not_registered` (a proxy has a record for the agent, but it is not registered and none of the other reasons apply).	reason, since, last_registered_seen_at, registrar
`agent.registration_restored`	—	account, reseller, organization	The agent is registered again after `agent.registration_lost`. `since` is when the registration was lost. Uses the `agent.registration_lost` settings.	since, registrar
`org.error_rate_spike`	—	account, reseller, organization	At least `rate_percent` percent of the organization’s calls in the last `window_minutes` failed, over at least `min_calls` calls. Re-arms when the rate drops below.	threshold, observed, window_minutes, since
`agent.latency_degraded`	—	account, reseller, organization	The agent’s 95th-percentile response time over the last `window_minutes` reached `p95_ms`, over at least `min_turns` turns. Re-arms when it drops below.	threshold, observed, window_minutes, since
`org.call_volume_spike`	—	account, reseller, organization	The organization had more than `calls_per_hour` calls in the last hour: inbound calls, plus outbound calls that were dialled or attempted (queued, scheduled and cancelled calls do not count). Re-arms when it drops below.	threshold, observed, since, inbound_calls, outbound_calls

threshold is the setting that was met and observed the value Telzino measured. since is when the condition started for agent.inactive, org.inactive and agent.registration_lost, and when it was detected for org.error_rate_spike, agent.latency_degraded and org.call_volume_spike.

Event settings

Endpoints that subscribe to a monitoring event must give its settings in event_settings, keyed by event type. There are no defaults; an endpoint subscribed without them is refused. GET /v1/webhook-event-types returns each event’s settings_schema.

Event	Setting	Type	Range	Required
`agent.inactive`, `org.inactive`	`after_hours`	integer	1–2160	yes
	`business_hours`	object (below)	—	no
`agent.registration_lost`	`debounce_minutes`	integer	1–1440	yes
`org.error_rate_spike`	`window_minutes`	integer	5–1440	yes
	`min_calls`	integer	1–10000	yes
	`rate_percent`	integer	1–100	yes
`agent.latency_degraded`	`window_minutes`	integer	5–1440	yes
	`p95_ms`	integer	100–60000	yes
	`min_turns`	integer	1–100000	yes
`org.call_volume_spike`	`calls_per_hour`	integer	1–100000	yes

agent.activity_resumed, org.activity_resumed and agent.registration_restored have no settings of their own: they use the settings of their pair event. Put them in event_settings under the pair event’s own name (for example agent.inactive for agent.activity_resumed), even when only the resumed/restored event is subscribed: without them the endpoint is refused, and settings keyed under the resumed/restored name are refused too. business_hours:

{ "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00", "timezone": "America/New_York" }

days are 0–6, 0 = Sunday; start and end are HH:MM; timezone is an IANA name. Example event_settings:

{
  "agent.inactive": { "after_hours": 48, "business_hours": { "days": [1, 2, 3, 4, 5], "start": "09:00", "end": "17:00", "timezone": "America/New_York" } },
  "org.error_rate_spike": { "window_minutes": 60, "min_calls": 10, "rate_percent": 25 }
}

Suspending an organization

Account admins and Reseller Admins of the organization’s reseller can suspend and reactivate an organization from the Customers page, or with PATCH /v1/organizations/{organization_id} (reference), with an optional reason. While an organization is suspended:

inbound phone and web/widget calls to its agents are refused before the agent answers;
new outbound calls are refused, and outbound calls already queued or scheduled are skipped;
SMS from its agents is refused;
its users can still sign in and edit it;
billing is unchanged — its agents still count.

Suspending fires org.suspended; reactivating fires org.reactivated.

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

Events

First events

Onboarding

Lifecycle

Who created it

Actor

Account, billing and users

Telzino only

Calls

Call outcomes

Survey

Monitoring

Event settings

Suspending an organization