@profullstack/group-call 0.4.0 → 0.5.0

package/README.md

@@ -46,6 +46,13 @@ await line.handle(JSON.parse(rawBody).data);
 - **Call people in.** `dial(code, phone, { from, connectionId, name?, prompt? })` rings a phone
   from your number. Whoever answers presses 1 and is in the room, so voicemail never joins.
   The room rides in the call's `client_state`, so an answer after a restart still lands right.
+- **Call a voice agent in.** `dial(code, "sip:+1555...@sip.rtc.elevenlabs.io", { ..., direct: true, name, headers })`
+  joins on answer with no press 1 and no greeting, and sends `headers` (`X-...` only) on the INVITE.
+  ElevenLabs Agents expose them as dynamic variables (`X-Otr-Episode` -> `{{sip_otr_episode}}`).
+- **Record a room.** `record(code)` records the conference, everyone mixed, as mp3 (or wav) until it
+  ends or `stopRecording(code)`. `onRecording({ code, conferenceId, recordingId, mp3, wav, ... })` fires
+  on `conference.recording.saved`; the links are short-lived, so download straight away, or get fresh
+  ones with `recordingLinks(recordingId)`.
 - **Room API.** `say(code, text, voice?)` speaks into a room. Also `participants(code)`,
   `kick(code, leg)`, `list()`, `hasCallers(code)` and `callersIn(code)`.
 - **App hooks.** `onCode` can join, welcome, reject, or take the call over: `call.gather(...)`

package/dist/index.d.ts

@@ -40,6 +40,20 @@ export interface Participant {
 interface Room extends RoomInfo {
     /** Legs currently in the room, so a caller is never counted twice. */
     legs: Map<string, Participant>;
+    /** The conference a recording was started on, or null; a remade conference is not being recorded. */
+    recordingConf?: string | null;
+}
+/** A finished recording of a room's conference, as Telnyx saved it. */
+export interface Recording {
+    /** The room, when this process started the recording; null after a restart lost track. */
+    code: string | null;
+    conferenceId: string;
+    recordingId: string;
+    /** Short-lived signed links; fetch the file promptly, or ask Telnyx for /recordings/{id} again. */
+    mp3: string | null;
+    wav: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
 }
 /** Sending a text. Injected because the number that sends is not always the one called. */
 export interface Sms {
@@ -131,6 +145,8 @@ export interface GroupCallOptions {
     };
     /** A finished line somebody said in a room (needs `transcribe`). */
     onTranscript?: (code: string, who: Participant, text: string) => void;
+    /** A room recording (see `record`) is saved on Telnyx and ready to download. */
+    onRecording?: (recording: Recording) => void;
     /** Injected for tests. */
     now?: () => number;
     fetch?: typeof globalThis.fetch;
@@ -180,6 +196,10 @@ export declare class GroupCall {
     private readonly dialled;
     /** How many times each leg has been asked for a code, so it is not forever. */
     private readonly asks;
+    /** Names for legs `dial` placed with one, used when they enter. */
+    private readonly legName;
+    /** Which room each conference we are recording belongs to, for the saved webhook. */
+    private readonly recordingRoom;
     /** Legs whose voice failed once, which hear the plain one from then on. */
     private readonly plainVoice;
     /** Names promised for callers about to arrive from a number: agents announce themselves. */
@@ -245,6 +265,12 @@ export declare class GroupCall {
      * room. The room is carried in the call's client_state too, so an answer
      * that arrives after a restart still knows where it was going. Returns the
      * new leg, or null when Telnyx would not place the call.
+     *
+     * `direct` skips the press-1 question and joins on answer, silently: for a
+     * machine that will not press anything, like a voice agent. `to` may then be
+     * a SIP URI (`sip:+1555...@sip.example.com`), and `headers` are sent on the
+     * INVITE as custom X- headers, which is how such an agent is told what call
+     * this is.
      */
     dial(code: string, to: string, opts: {
         from: string;
@@ -253,10 +279,16 @@ export declare class GroupCall {
         prompt?: string;
         welcome?: string;
         timeoutSecs?: number;
+        direct?: boolean;
+        headers?: Record<string, string>;
     }): Promise<{
         leg: string;
     } | null>;
-    /** A dialled phone was picked up: press 1 to join, so voicemail never does. */
+    /**
+     * A dialled phone was picked up: press 1 to join, so voicemail never does.
+     * Telnyx itself replays the prompt (three tries) and ignores any other key,
+     * so an ended gather without a 1 is a no.
+     */
     private offer;
     /** Hand a well-formed code to the app, and act on what it says the code is. */
     private routeCode;
@@ -276,9 +308,9 @@ export declare class GroupCall {
      * Put a leg into a room, making the conference if it is the first one there.
      *
      * `welcome` is what the caller hears once they are in, before the count of
-     * who else is.
+     * who else is; null joins them without a word.
      */
-    join(leg: string, code: string, welcome?: string): Promise<void>;
+    join(leg: string, code: string, welcome?: string | null): Promise<void>;
     /**
      * A conference's name: findable again after a restart, but not the code itself,
      * which would be a room's whole key sitting in somebody else's dashboard. A
@@ -307,6 +339,25 @@ export declare class GroupCall {
      * nobody is on the phone there, which is most of the time and costs nothing.
      */
     say(code: string, text: string, voice?: string, settings?: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Record the room's conference, everyone mixed into one file. Runs until the
+     * conference ends (the last caller leaves) or `stopRecording`; `onRecording`
+     * hears when the file is saved. False when nobody is on the line yet, since
+     * there is no conference to record until somebody is.
+     */
+    record(code: string, opts?: {
+        format?: "mp3" | "wav";
+        beep?: boolean;
+    }): Promise<boolean>;
+    /** Whether this process is recording the room's current conference. */
+    recording(code: string): boolean;
+    /** Stop recording; the file is saved and `onRecording` follows. */
+    stopRecording(code: string): Promise<boolean>;
+    /** A saved recording's current download links, for when the webhook's have expired. */
+    recordingLinks(recordingId: string): Promise<{
+        mp3: string | null;
+        wav: string | null;
+    } | null>;
     /** Hang up one participant in a room. */
     kick(code: string, leg: string): Promise<boolean>;
     /** Whether anybody is on the phone in a room. */

package/dist/index.js

@@ -73,6 +73,8 @@ function dialState(raw) {
             code: s["code"],
             ...(typeof s["prompt"] === "string" ? { prompt: s["prompt"] } : {}),
             ...(typeof s["welcome"] === "string" ? { welcome: s["welcome"] } : {}),
+            ...(s["direct"] === true ? { direct: true } : {}),
+            ...(typeof s["name"] === "string" ? { name: s["name"] } : {}),
         };
     }
     catch {
@@ -187,6 +189,10 @@ export class GroupCall {
     dialled = new Map();
     /** How many times each leg has been asked for a code, so it is not forever. */
     asks = new Map();
+    /** Names for legs `dial` placed with one, used when they enter. */
+    legName = new Map();
+    /** Which room each conference we are recording belongs to, for the saved webhook. */
+    recordingRoom = new Map();
     /** Legs whose voice failed once, which hear the plain one from then on. */
     plainVoice = new Set();
     /** Names promised for callers about to arrive from a number: agents announce themselves. */
@@ -281,13 +287,34 @@ export class GroupCall {
     async handle(event) {
         const type = event.event_type ?? "";
         const payload = event.payload ?? {};
+        // A conference event, not a leg's: it may carry no call_control_id at all.
+        if (type === "conference.recording.saved") {
+            const conferenceId = typeof payload["conference_id"] === "string" ? payload["conference_id"] : "";
+            const recordingId = typeof payload["recording_id"] === "string" ? payload["recording_id"] : "";
+            if (!conferenceId || !recordingId)
+                return;
+            const urls = (payload["recording_urls"] ?? payload["public_recording_urls"] ?? {});
+            const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+            const code = this.recordingRoom.get(conferenceId) ?? null;
+            this.recordingRoom.delete(conferenceId);
+            this.options.onRecording?.({
+                code,
+                conferenceId,
+                recordingId,
+                mp3: str(urls["mp3"]),
+                wav: str(urls["wav"]),
+                startedAt: str(payload["recording_started_at"]),
+                endedAt: str(payload["recording_ended_at"]),
+            });
+            return;
+        }
         const leg = typeof payload["call_control_id"] === "string" ? payload["call_control_id"] : "";
         if (!leg)
             return;
         if (type === "call.initiated") {
             // Only inbound. An outbound leg we dialled is not somebody calling in,
             // and answering it would be answering ourselves.
-            if (payload["direction"] !== "incoming")
+            if (payload["direction"] !== "incoming" || this.dialled.has(leg))
                 return;
             if (typeof payload["from"] === "string")
                 this.legFrom.set(leg, payload["from"]);
@@ -295,14 +322,23 @@ export class GroupCall {
             return;
         }
         if (type === "call.answered") {
-            // An answered outbound leg is somebody else's business, unless it is one
-            // `dial` rang: then it is a person picking up, to be asked in.
-            if (payload["direction"] === "outgoing") {
-                const dialled = this.dialled.get(leg) ?? dialState(payload["client_state"]);
-                if (dialled)
-                    await this.offer(leg, dialled);
+            // A leg `dial` rang is somebody picking up, to be asked in -- checked before
+            // the direction, because a call to a SIP URI does not always say "outgoing".
+            // Any other answered outbound leg is somebody else's business.
+            const dialled = this.dialled.get(leg) ?? dialState(payload["client_state"]);
+            if (dialled?.direct) {
+                this.dialled.delete(leg);
+                if (dialled.name)
+                    this.legName.set(leg, dialled.name);
+                await this.join(leg, dialled.code, null);
                 return;
             }
+            if (dialled) {
+                await this.offer(leg, dialled);
+                return;
+            }
+            if (payload["direction"] === "outgoing")
+                return;
             await this.ask(leg);
             return;
         }
@@ -355,6 +391,7 @@ export class GroupCall {
             this.release(leg);
             this.legFrom.delete(leg);
             this.dialled.delete(leg);
+            this.legName.delete(leg);
             this.pendingGather.delete(leg);
             this.asks.delete(leg);
             this.plainVoice.delete(leg);
@@ -372,38 +409,59 @@ export class GroupCall {
      * room. The room is carried in the call's client_state too, so an answer
      * that arrives after a restart still knows where it was going. Returns the
      * new leg, or null when Telnyx would not place the call.
+     *
+     * `direct` skips the press-1 question and joins on answer, silently: for a
+     * machine that will not press anything, like a voice agent. `to` may then be
+     * a SIP URI (`sip:+1555...@sip.example.com`), and `headers` are sent on the
+     * INVITE as custom X- headers, which is how such an agent is told what call
+     * this is.
      */
     async dial(code, to, opts) {
-        const number = normalNumber(to);
+        const sip = opts.direct === true && /^sips?:[^\s@]+@[^\s@]+$/i.test(to.trim());
+        const number = sip ? to.trim() : normalNumber(to);
         if (!number || !opts.connectionId || !opts.from)
             return null;
-        const state = { code, ...(opts.prompt ? { prompt: opts.prompt.slice(0, 300) } : {}), ...(opts.welcome ? { welcome: opts.welcome.slice(0, 200) } : {}) };
+        const state = {
+            code,
+            ...(opts.prompt ? { prompt: opts.prompt.slice(0, 300) } : {}),
+            ...(opts.welcome ? { welcome: opts.welcome.slice(0, 200) } : {}),
+            ...(opts.direct ? { direct: true } : {}),
+            ...(opts.direct && opts.name ? { name: opts.name.slice(0, 60) } : {}),
+        };
+        const headers = Object.entries(opts.headers ?? {})
+            .filter(([name]) => /^X-[A-Za-z0-9-]{1,60}$/.test(name))
+            .map(([name, value]) => ({ name, value: String(value).slice(0, 200) }));
         const placed = (await this.request("/calls", {
             connection_id: opts.connectionId,
             to: number,
             from: normalNumber(opts.from),
             timeout_secs: opts.timeoutSecs ?? 30,
             client_state: Buffer.from(JSON.stringify({ gc: "dial", ...state }), "utf8").toString("base64"),
+            ...(headers.length ? { custom_headers: headers } : {}),
         }));
         const leg = placed?.data?.call_control_id;
         if (typeof leg !== "string")
             return null;
         this.dialled.set(leg, state);
         this.legFrom.set(leg, number);
-        if (opts.name)
+        if (opts.name && opts.direct)
+            this.legName.set(leg, opts.name.slice(0, 60));
+        else if (opts.name)
             this.expect(code, number, opts.name, 5 * 60 * 1000);
         this.options.onEvent?.(`  ringing a phone into a room.`);
         return { leg };
     }
-    /** A dialled phone was picked up: press 1 to join, so voicemail never does. */
-    async offer(leg, dialled, tries = 1) {
+    /**
+     * A dialled phone was picked up: press 1 to join, so voicemail never does.
+     * Telnyx itself replays the prompt (three tries) and ignores any other key,
+     * so an ended gather without a 1 is a no.
+     */
+    async offer(leg, dialled) {
         this.dialled.delete(leg);
         const prompt = dialled.prompt ?? "This is group call, calling you into a room.";
-        await this.gather(leg, `${tries > 1 ? "" : `${prompt} `}Press 1 to join.`, { validDigits: "0123456789", maximumDigits: 1, timeoutMillis: 10000 }, async (digits) => {
+        await this.gather(leg, `${prompt} Press 1 to join.`, { validDigits: "1", maximumDigits: 1, timeoutMillis: 6000 }, async (digits) => {
             if (digits === "1")
                 return this.join(leg, dialled.code, dialled.welcome);
-            if (tries < 2)
-                return this.offer(leg, dialled, tries + 1);
             await this.command(leg, "speak", { payload: "Okay, not joining. Goodbye.", ...this.voiceBody(leg) });
             await this.command(leg, "hangup", {});
         });
@@ -492,7 +550,7 @@ export class GroupCall {
      * Put a leg into a room, making the conference if it is the first one there.
      *
      * `welcome` is what the caller hears once they are in, before the count of
-     * who else is.
+     * who else is; null joins them without a word.
      */
     async join(leg, code, welcome = `Welcome to room ${spokenCode(code)}. `) {
         const room = this.room(code);
@@ -586,7 +644,7 @@ export class GroupCall {
         if (room.legs.has(leg))
             return;
         const from = this.legFrom.get(leg) ?? "";
-        const who = { leg, from, name: this.claimName(room.code, from), joinedAt: this.now() };
+        const who = { leg, from, name: this.legName.get(leg) || this.claimName(room.code, from), joinedAt: this.now() };
         room.legs.set(leg, who);
         room.callers = room.legs.size;
         this.options.onEvent?.(`  ${who.name || "a caller"} joined a room (${room.callers} on the line).`);
@@ -626,7 +684,7 @@ export class GroupCall {
      * the room do not hear every arrival welcomed.
      */
     async greet(room, leg, welcome) {
-        if (room.conferenceId === null)
+        if (room.conferenceId === null || welcome === null)
             return;
         await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/speak`, {
             payload: `${welcome}${peopleHere(room.callers)}`,
@@ -654,6 +712,53 @@ export class GroupCall {
         });
         return answer !== null;
     }
+    /**
+     * Record the room's conference, everyone mixed into one file. Runs until the
+     * conference ends (the last caller leaves) or `stopRecording`; `onRecording`
+     * hears when the file is saved. False when nobody is on the line yet, since
+     * there is no conference to record until somebody is.
+     */
+    async record(code, opts = {}) {
+        const room = this.rooms.get(code);
+        if (!room || room.conferenceId === null || room.callers === 0)
+            return false;
+        if (room.recordingConf === room.conferenceId)
+            return true;
+        const started = await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/record_start`, {
+            format: opts.format ?? "mp3",
+            play_beep: opts.beep ?? false,
+        });
+        if (started === null)
+            return false;
+        room.recordingConf = room.conferenceId;
+        this.recordingRoom.set(room.conferenceId, code);
+        this.options.onEvent?.(`  recording a room.`);
+        return true;
+    }
+    /** Whether this process is recording the room's current conference. */
+    recording(code) {
+        const room = this.rooms.get(code);
+        return Boolean(room && room.conferenceId !== null && room.recordingConf === room.conferenceId);
+    }
+    /** Stop recording; the file is saved and `onRecording` follows. */
+    async stopRecording(code) {
+        const room = this.rooms.get(code);
+        if (!room || room.conferenceId === null || room.recordingConf !== room.conferenceId)
+            return false;
+        const stopped = await this.request(`/conferences/${encodeURIComponent(room.conferenceId)}/actions/record_stop`, {});
+        if (stopped !== null)
+            room.recordingConf = null;
+        return stopped !== null;
+    }
+    /** A saved recording's current download links, for when the webhook's have expired. */
+    async recordingLinks(recordingId) {
+        const got = (await this.get(`/recordings/${encodeURIComponent(recordingId)}`));
+        const urls = got?.data?.download_urls;
+        if (!urls)
+            return null;
+        const str = (v) => (typeof v === "string" && v !== "" ? v : null);
+        return { mp3: str(urls["mp3"]), wav: str(urls["wav"]) };
+    }
     /** Hang up one participant in a room. */
     async kick(code, leg) {
         if (!this.rooms.get(code)?.legs.has(leg))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/group-call",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A group call on a phone number: dial in, key a room code, talk with everyone else who did, people and AI agents alike. Telnyx Call Control state machine extracted from nixamp's party line; the engine behind nixamp live joins and group.call.pit.world.",
   "license": "MIT",
   "type": "module",