npm i @telenow/server        # Node 18+ / Bun / Deno / Cloudflare Workers
pip install telenow          # Python 3.8+  ("telenow[django]" adds the Django helper)

import { Telenow } from '@telenow/server';
const tn = new Telenow({ apiKey: process.env.TELENOW_API_KEY }); // baseUrl defaults to api.telenow.ai

import os
from telenow import Telenow
tn = Telenow(api_key=os.environ["TELENOW_API_KEY"])

const { sessionId, callId, status } = await tn.calls.create({
  agentId: 'AGENT_UUID',
  to: '+15551234567',                                 // E.164
  variables: { order_id: 'A-1042' },                  // context variables
  identifier: 'customer-9',                           // trusted caller identity for tools
  firstResponse: 'Hi! Calling about your delivery.',  // optional opener override
  machineDetection: 'true',                           // 'true' = auto-voicemail, 'hangup'
});

result = tn.create_call(
    "AGENT_UUID", "+15551234567",
    variables={"order_id": "A-1042"},
    identifier="customer-9",
    first_response="Hi! Calling about your delivery.",
    machine_detection="true",
)

// 1) Backend: mint the softphone session (the API key never leaves the server).
app.post('/crm/dial', async (req, res) => {
  const session = await tn.calls.createManual({
    to: req.body.customerPhone,    // E.164 number to ring
    from: '+15550001111',          // your org's caller-ID (Numbers / BYOC / SIP)
    userId: req.body.agentUserId,  // optional attribution: who placed the call
  });
  res.json(session); // { sessionId, websocketUrl, callId, callMode: 'manual', fromNumber, toNumber }
});

@app.post("/crm/dial")
async def crm_dial(req):
    return tn.create_manual_call(
        req.customer_phone,           # E.164 number to ring
        from_number="+15550001111",   # your org's caller-ID (Numbers / BYOC / SIP)
        user_id=req.agent_user_id,    # optional attribution
    )

// 2) Frontend: connect the softphone — this becomes the rep's mic + speaker.
import { TelenowCall } from '@telenow/client';
const session = await fetch('/crm/dial', { method: 'POST', /* … */ }).then((r) => r.json());
const call = new TelenowCall({ session });
await call.start();   // mic permission → bridged to the customer over the carrier

app.post('/voice/session', async (_req, res) => {
  res.json(await tn.calls.createWeb({
    agentId: 'AGENT_UUID',
    variables: { customer_name: 'Sarah' },
    firstResponse: 'Hi Sarah! How can I help today?', // optional per-session opener override
  }));
});

@app.post("/voice/session")
async def voice_session():
    return tn.init_web_call(
        "AGENT_UUID",
        variables={"customer_name": "Sarah"},
        first_response="Hi Sarah! How can I help today?",  # optional per-session opener override
    )

await tn.calls.transfer(sessionId, '+15557654321'); // warm transfer to a human
await tn.calls.end(sessionId);                      // hang up

tn.transfer_call(session_id, "+15557654321")
tn.end_call(session_id)

// Low-level: one turn at a time.
const first = await tn.chat.send({ agentId: 'AGENT_UUID', identifier: 'user-42', input: 'Hello!' });
// → { sessionId, reply, turn: 1, identifier }
const next = await tn.chat.send({ agentId: 'AGENT_UUID', identifier: 'user-42', input: 'Tell me more', sessionId: first.sessionId });
const { messages } = await tn.chat.messages(first.sessionId); // transcript
await tn.chat.end(first.sessionId);                            // settle now (idempotent)

first = tn.chat("AGENT_UUID", "user-42", "Hello!")            # → {"sessionId", "reply", "turn", ...}
nxt = tn.chat("AGENT_UUID", "user-42", "Tell me more", session_id=first["sessionId"])
msgs = tn.chat_messages(first["sessionId"])["messages"]        # transcript
tn.chat_end(first["sessionId"])                                # settle now (idempotent)

import { chatLoop } from '@telenow/server';
const convo = chatLoop(tn, { agentId: 'AGENT_UUID', identifier: 'user-42', variables: { plan: 'Pro' } });
const a = await convo.send('Hello!');               // turn 1
const b = await convo.send('What are your hours?'); // turn 2 (or a transparent restart)
await convo.end();

convo = tn.chat_conversation("AGENT_UUID", "user-42", variables={"plan": "Pro"})
a = convo.send("Hello!")                # turn 1
b = convo.send("What are your hours?")  # turn 2 (or a transparent restart)
convo.end()

app.post('/webhooks/telenow', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await tn.webhooks.verify(req.body, req.get('x-voiceai-signature') ?? '', SECRET);
  if (!ok) return res.status(401).end();
  const event = JSON.parse(req.body.toString());   // call.started | call.ended | transcript.ready | tool.invoked
  res.status(200).end();
});

from telenow.django import telenow_webhook

@telenow_webhook(secret=settings.TELENOW_WEBHOOK_SECRET)
def hook(request, event):          # signature verified, body parsed
    if event["event"] == "call.ended":
        ...
    return HttpResponse(status=200)

import { customApiNodeHandler, callEnd } from '@telenow/server';

app.post('/telenow-llm', customApiNodeHandler(async function* ({ query, userId }) {
  for await (const token of myLlm.stream(query)) yield token;  // spoken as it streams
  // yield callEnd('Goodbye!');                                // optional hangup after the reply
}, { bearer: process.env.TELENOW_BEARER }));
// Fetch-style runtimes (Next.js routes / Bun / Workers / Deno): customApiFetchHandler(handler)

from telenow import custom_api
from fastapi.responses import StreamingResponse

@app.post("/telenow-llm")
async def llm(request: Request):
    body = await request.json()

    async def gen():
        async for token in my_llm_stream(body["query"]):
            yield token                          # str → spoken token delta
        # yield custom_api.call_end("Goodbye!")  # dict → control event

    return StreamingResponse(custom_api.sse_astream(gen()),
                             media_type=custom_api.MEDIA_TYPE,
                             headers=custom_api.SSE_HEADERS)
# Django/Flask (sync): wrap a generator with custom_api.sse_stream(...) instead.