Tel

Package tel is the telecommunications surface: phone numbers, calls and messages, on whatever carrier the deployment is configured for.

Quickstart

export HANZO_API_KEY=hk-...   # console.hanzo.ai → API keys

Then the first call — a read that needs nothing but the key. GET /v1/tel/calls, operation get_tel_calls:

import { Configuration, TelApi } from 'hanzoai';

const api = new TelApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getTelCalls();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import TelApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = TelApi(client).get_tel_calls()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.TelAPI.GetTelCalls(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, tel_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = tel_api::get_tel_calls(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.TelApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new TelApi(client).getTelCalls();

curl https://api.hanzo.ai/v1/tel/calls \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_tel_calls"
         }
       }
     }'

Answers 200 with object — ok.

tel

DELETE /v1/tel/calls/{id}

Ends a live call. The holding is checked before the carrier is asked, so a call belonging to another org answers 404 rather than being torn down: the carrier knows nothing about tenancy and would obey either way.

GET /v1/tel/calls

Returns this org's call history, newest first as the store gives it. Org-scoped like every read here.

POST /v1/tel/calls

Dials. An agent names a Hanzo assistant to answer it; the call is refused up front when no assistant plane is configured, because a call that connects to silence has already cost the person who answered it.

Request body — application/json (required)

GET /v1/tel/messages

Returns this org's message history. Org-scoped like every read here.

POST /v1/tel/messages

Sends one message. from must be a number this org holds -- the carrier will send from any number it routes, so without that check one tenant could originate traffic on another's number, and the bill and the reputation would follow the number rather than the sender.

Request body — application/json (required)

DELETE /v1/tel/numbers/{id}

Checks the holding is THIS org's before it reaches the carrier. Without that read, an id belonging to another tenant would be released by whoever guessed it.

GET /v1/tel/numbers/available

Asks the carrier what is available to buy. Nothing is recorded — a search is not a holding, and treating it as one is how inventory leaks.

GET /v1/tel/numbers

Returns the numbers this org holds. Scoped to the caller's org, so a number bought by one tenant is invisible to every other.

POST /v1/tel/numbers

Provisions with the carrier FIRST and records second. The other order records a holding that may not exist, and a number the platform believes it owns but cannot use is worse than one it failed to buy.

Request body — application/json (required)

GET /v1/tel/summary

Counts what this org holds and has used -- numbers, calls, messages. The one read the dashboard makes, so it is three counts rather than three lists.

All Hanzo APIs · Interactive reference