Kognitive Telephony

@kognitivedev/telephony is the Node-side call-control package for Kognitive voice agents. It handles phone-provider ingress, outbound dialing, media-stream message normalization, and audio codec helpers. Cloud Voice uses it underneath for PSTN/SIP channels.

Install

bun add @kognitivedev/telephony

Inbound Calls

import { createTwilioInboundCallResponse } from "@kognitivedev/telephony/twilio";

const result = await createTwilioInboundCallResponse({
  service: telephony,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  resourceId: { userId: "caller:+15550001111" },
  buildStreamUrl: (session) =>
    `wss://api.example.com/api/cloud/voice/telephony/twilio/media/${session.sessionId}`,
}, {
  url: "https://api.example.com/api/cloud/voice/telephony/twilio/inbound",
  headers: { "x-twilio-signature": request.headers.get("x-twilio-signature") ?? "" },
  params,
});

return new Response(result.twiml, {
  headers: { "Content-Type": "text/xml" },
});

Outbound Calls

import { createTwilioOutboundCall } from "@kognitivedev/telephony/twilio";

const call = await createTwilioOutboundCall({
  accountSid: process.env.TWILIO_ACCOUNT_SID!,
  authToken: process.env.TWILIO_AUTH_TOKEN!,
  from: "+15550001111",
  to: "+15550002222",
  answerUrl: "https://api.example.com/api/cloud/voice/telephony/twilio/outbound-answer/session_123",
  statusCallbackUrl: "https://api.example.com/api/cloud/voice/telephony/twilio/status",
});

Runtime Tool Calls

Phone calls do not have a browser runtime. Cloud Voice phone tools should be normal Kognitive runtime tools, synced from the customer's Kognitive instance and executed by the Cloud Voice backend during the call.

import { Kognitive } from "@kognitivedev/core";
import { createTool } from "@kognitivedev/tools";
import { z } from "zod";

const lookupOrder = createTool({
  id: "lookup_order",
  description: "Look up an order",
  inputSchema: z.object({ orderNumber: z.string() }),
  execute: async ({ orderNumber }) => db.orders.findByNumber(orderNumber),
});

export const kognitive = new Kognitive({
  apiKey: process.env.KOGNITIVE_API_KEY,
  baseUrl: process.env.KOGNITIVE_API_URL,
  tools: [lookupOrder],
});

The Cloud Voice media bridge owns tracing and provider tool-result delivery. Application code does not call appendCloudVoiceEvent() or sendToolResult() directly.

Phone Control Adapter

Cloud Voice phone-control tools use provider adapters. Twilio call control lives in this package; Cloud Voice orchestration receives it as a plain structural adapter.

import { createTwilioPhoneControlAdapter } from "@kognitivedev/telephony/twilio";

const adapter = createTwilioPhoneControlAdapter({
  accountSid: process.env.TWILIO_ACCOUNT_SID!,
  authToken: process.env.TWILIO_AUTH_TOKEN!,
});

await adapter.hangUpCall({
  providerCallId: "CA...",
  reason: "caller said goodbye",
});

The adapter completes the active Twilio call through the Calls REST API with Status=completed.