@voctiv/agent-sdk 0.2.4 → 0.2.6

package/README.md

@@ -79,7 +79,7 @@ export default defineScript(async ({ channel, logger, context }) => {
 - `channel` is the media channel for SIP, WS, ASR, TTS, audio playback, LLM, and structured data messages.
 - `logger` writes structured script logs and can stream logs to a debug endpoint.
 - `context` contains dialog identity, caller/called numbers, language, flags, params, entry point, persisted env, and runtime budget.
-- `platform` exposes legacy platform operations: NLU, dialog state, outbound call scheduling, messaging, and phrase records.
+- `platform` exposes platform operations: NLU, dialog state, outbound call scheduling, messaging, and phrase records.
 
 `MediaChannel` is the main real-time API:
 
@@ -103,6 +103,28 @@ The important states are:
 - `active`: final 200 OK has been received or sent.
 - `terminated`: the call ended and no more audio is possible.
 
+### How Pre-Answer Works
+
+Pre-answer means the SIP media path is open before the call is finally answered with `200 OK`. In this state the caller can already hear TTS, the script can already receive audio for ASR, and DTMF can be exchanged.
+
+Use pre-answer when you need to do something before committing the call to the final answer state:
+
+- play an informational greeting or disclaimer;
+- collect a short value with ASR, such as account number or menu choice;
+- detect and navigate an IVR that speaks before answering;
+- delay `answer()` until the script is ready to transfer, bridge, or continue.
+
+For inbound calls, the script controls this explicitly:
+
+1. Call `channel.sip.sendProgress()` to send `183 Session Progress` with SDP.
+2. Wait for `channel.sip.waitForEarly()` if your next logic step needs media to be ready.
+3. Use `channel.audio.say()`, `channel.audio.play()`, `channel.createAsr()`, or `channel.sip.sendDtmf()` normally.
+4. Call `channel.sip.answer()` when you want to send the final `200 OK`.
+
+For outbound calls, pre-answer is controlled by the remote side. If the remote endpoint sends `183 Session Progress` with SDP, ScriptEngine moves the call to `early`. If it answers directly, `waitForEarly()` resolves when the call becomes `active`.
+
+`early` is a media-ready state, not a final answer state. `answer()` is still the explicit transition that sends final `200 OK` for inbound calls. External billing behavior depends on the carrier.
+
 ### Outbound Pre-Answer
 
 For outbound calls, early media starts when the remote side sends a provisional response with SDP, usually `183 Session Progress`. This is useful for IVRs that speak before answering.
@@ -349,7 +371,7 @@ await channel.audio.say(
 
 ## Platform API
 
-`platform` exposes Voctiv legacy-compatible operations.
+`platform` exposes Voctiv platform operations.
 
 `platform.nlu.extract(utterance, options?)` calls NLU v3 `/infer`. The runtime sends `phrase`, `context`, and `agent_id`. If `options.context` is omitted, current dialog params are serialized and used as NLU context.
 
@@ -361,7 +383,7 @@ const result = await platform.nlu.extract('I want to reschedule', {
 });
 ```
 
-Legacy platform APIs require `context.legacyV3Compat === true`. This includes NLU, outbound calls, dialog writes, messaging sends, and phrase records.
+Platform APIs require `context.legacyV3Compat === true`. This includes NLU, outbound calls, dialog writes, messaging sends, and phrase records.
 
 ### Dialog State
 
@@ -372,19 +394,68 @@ platform.dialog.result = 'done';
 
 Setters update the local value immediately and ask the platform DB to persist asynchronously. They are not awaitable and should not be used as transactional writes.
 
-### Outbound Calls
+### Platform-Scheduled Calls
+
+Use `platform.call(msisdn, options?)` when the script needs to ask the platform to place an outbound SIP call. This is different from `channel.sip.makeCall()`: `makeCall()` creates a B-leg immediately inside the current live SIP session, while `platform.call()` schedules a separate platform-managed call that may happen now or later.
+
+The destination number should be E.164 formatted.
+
+```ts
+await platform.call('+12025551234');
+```
+
+By default, the platform schedules the call for immediate processing. Use `date` to schedule it for the future:
 
 ```ts
 await platform.call('+12025551234', {
-  date: new Date(Date.now() + 60_000),
+  date: new Date(Date.now() + 15 * 60_000),
   entryPoint: 'on_callback',
-  recallCount: 2,
+});
+```
+
+`entryPoint` is passed to the script when the scheduled call starts. Use it to route the callback into a specific branch:
+
+```ts
+export default defineScript(async ({ context, channel }) => {
+  if (context.entryPoint === 'on_callback') {
+    channel.sip.answer();
+    await channel.audio.say('Hello, this is your scheduled callback.');
+    return;
+  }
+
+  await channel.audio.say('I will call you back in fifteen minutes.');
+});
+```
+
+Use `dateEnd` to define the latest time when the call is still useful. If the platform cannot place the call before that deadline, it can skip the attempt.
+
+```ts
+await platform.call('+12025551234', {
+  date: new Date('2026-04-29T10:00:00Z'),
+  dateEnd: new Date('2026-04-29T10:30:00Z'),
+  entryPoint: 'on_reminder',
+});
+```
+
+Retries are controlled with `recallCount` and `recallDelay`:
+
+```ts
+await platform.call('+12025551234', {
+  entryPoint: 'on_follow_up',
+  recallCount: 3,
   recallDelay: 300,
-  priority: 10,
 });
 ```
 
-This creates a row in the legacy `call` table. The dialer picks it up and originates the SIP call.
+This means the platform may retry up to three times, waiting about five minutes between attempts.
+
+Other scheduling options:
+
+- `priority`: higher-priority calls can be processed earlier by the dialer.
+- `timezone`: timezone offset used by the platform when interpreting scheduled dates.
+- `onSuccessCall`: entry point to use after a successful call.
+- `onFailedCall`: entry point to use after failed attempts.
+- `protoAdditional`: extra protocol-level parameters, such as SIP headers expected by your telephony setup.
 
 ### Messaging
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voctiv/agent-sdk",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",