@voctiv/agent-sdk 0.2.5 → 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:
 
@@ -371,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.
 
@@ -383,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
 
@@ -394,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.5",
+  "version": "0.2.6",
   "description": "Voctiv TypeScript agent SDK: defineScript and platform types for the voice/dialog scripting runtime.",
   "license": "UNLICENSED",
   "author": "",