@proveanything/smartlinks 1.13.10 → 1.13.12

package/dist/api/authKit.d.ts

@@ -28,7 +28,7 @@ export declare namespace authKit {
     /** Verify phone verification code (public). */
     function verifyPhoneCode(clientId: string, phoneNumber: string, code: string): Promise<PhoneVerifyResponse>;
     /** Send a WhatsApp verification deep-link (public). */
-    function sendWhatsApp(clientId: string, body: SendWhatsAppRequest): Promise<SendWhatsAppResponse>;
+    function sendWhatsApp(clientId: string, body?: SendWhatsAppRequest): Promise<SendWhatsAppResponse>;
     /** Manually verify WhatsApp token if inbound webhook path is unavailable (public). */
     function verifyWhatsApp(clientId: string, token: string, phoneNumber: string): Promise<VerifyWhatsAppResponse>;
     /** Poll WhatsApp verification status for a token (public). */

package/dist/api/authKit.js

@@ -47,7 +47,7 @@ export var authKit;
     }
     authKit.verifyPhoneCode = verifyPhoneCode;
     /** Send a WhatsApp verification deep-link (public). */
-    async function sendWhatsApp(clientId, body) {
+    async function sendWhatsApp(clientId, body = {}) {
         return post(`/authkit/${encodeURIComponent(clientId)}/auth/whatsapp/send`, body);
     }
     authKit.sendWhatsApp = sendWhatsApp;

package/dist/api/interactions.d.ts

@@ -21,7 +21,10 @@ export declare namespace interactions {
     function aggregateByOutcome(collectionId: string, body: AdminInteractionsAggregateRequest): Promise<AdminInteractionsAggregateResponse>;
     /**
      * POST /admin/collection/:collectionId/interactions/append
-     * Appends one interaction event.
+      * Appends one interaction event.
+      *
+      * `interactionId` must reference an existing interaction type definition.
+      * This endpoint does not create interaction definitions.
      */
     function appendEvent(collectionId: string, body: AppendInteractionBody): Promise<{
         success: true;
@@ -30,13 +33,15 @@ export declare namespace interactions {
         success: true;
     }>;
     /**
-       * POST /api/v1/public/collection/:collectionId/interactions/submit
-       *
-       * Submits an interaction event from a public/client-side context.
-       * When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor
-       * `contactId` is required. Pass `anonId` inside `metadata` to enable
-       * device-level deduplication via `uniquePerAnonId`.
-       */
+     * POST /api/v1/public/collection/:collectionId/interactions/submit
+     *
+     * Submits an interaction event from a public/client-side context.
+    * `interactionId` must reference an existing interaction type definition.
+    * This endpoint does not create interaction definitions.
+     * When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor
+     * `contactId` is required. Pass `anonId` inside `metadata` to enable
+     * device-level deduplication via `uniquePerAnonId`.
+     */
     function submitPublicEvent(collectionId: string, body: AppendInteractionBody): Promise<SubmitInteractionResponse | SubmitInteractionError>;
     function create(collectionId: string, body: CreateInteractionTypeBody): Promise<InteractionTypeRecord>;
     function list(collectionId: string, query?: ListInteractionTypesQuery): Promise<InteractionTypeList>;

package/dist/api/interactions.js

@@ -54,7 +54,10 @@ export var interactions;
     // Deprecated endpoint removed: actorIdsByInteraction
     /**
      * POST /admin/collection/:collectionId/interactions/append
-     * Appends one interaction event.
+      * Appends one interaction event.
+      *
+      * `interactionId` must reference an existing interaction type definition.
+      * This endpoint does not create interaction definitions.
      */
     async function appendEvent(collectionId, body) {
         if (!body.userId && !body.contactId) {
@@ -73,13 +76,15 @@ export var interactions;
     }
     interactions.updateEvent = updateEvent;
     /**
-       * POST /api/v1/public/collection/:collectionId/interactions/submit
-       *
-       * Submits an interaction event from a public/client-side context.
-       * When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor
-       * `contactId` is required. Pass `anonId` inside `metadata` to enable
-       * device-level deduplication via `uniquePerAnonId`.
-       */
+     * POST /api/v1/public/collection/:collectionId/interactions/submit
+     *
+     * Submits an interaction event from a public/client-side context.
+    * `interactionId` must reference an existing interaction type definition.
+    * This endpoint does not create interaction definitions.
+     * When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor
+     * `contactId` is required. Pass `anonId` inside `metadata` to enable
+     * device-level deduplication via `uniquePerAnonId`.
+     */
     async function submitPublicEvent(collectionId, body) {
         const path = `/public/collection/${encodeURIComponent(collectionId)}/interactions/submit`;
         return post(path, body);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.10  |  Generated: 2026-05-12T16:12:33.784Z
+Version: 1.13.12  |  Generated: 2026-05-14T16:00:33.063Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3024,11 +3024,31 @@ interface EmailVerifyTokenResponse {
 }
 ```
 
+**WhatsAppReplyCta** (interface)
+```typescript
+interface WhatsAppReplyCta {
+  body: string
+  buttonLabel: string
+  buttonUrl: string
+}
+```
+
+**WhatsAppReplyOptions** (interface)
+```typescript
+interface WhatsAppReplyOptions {
+  contentSid?: string
+  contentVariables?: Record<string, unknown>
+  cta?: WhatsAppReplyCta
+  text?: string
+}
+```
+
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
-  phoneNumber: string
-  redirectUrl: string
+  phoneNumber?: string
+  redirectUrl?: string
+  reply?: WhatsAppReplyOptions
 }
 ```
 
@@ -8192,7 +8212,7 @@ Send phone verification code (public).
 **verifyPhoneCode**(clientId: string, phoneNumber: string, code: string) → `Promise<PhoneVerifyResponse>`
 Verify phone verification code (public).
 
-**sendWhatsApp**(clientId: string, body: SendWhatsAppRequest) → `Promise<SendWhatsAppResponse>`
+**sendWhatsApp**(clientId: string, body: SendWhatsAppRequest = {}) → `Promise<SendWhatsAppResponse>`
 Send a WhatsApp verification deep-link (public).
 
 **verifyWhatsApp**(clientId: string, token: string, phoneNumber: string) → `Promise<VerifyWhatsAppResponse>`
@@ -8803,54 +8823,54 @@ Legacy-friendly alias for aggregate().
 
 **appendEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<`
-POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
+POST /admin/collection/:collectionId/interactions/append Appends one interaction event. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions.
 
 **updateEvent**(collectionId: string,
     body: UpdateInteractionBody) → `Promise<`
-POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
+POST /admin/collection/:collectionId/interactions/append Appends one interaction event. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions.
 
 **submitPublicEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<SubmitInteractionResponse | SubmitInteractionError>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **create**(collectionId: string,
     body: CreateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **list**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **get**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **update**(collectionId: string,
     id: string,
     patchBody: UpdateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicCountsByOutcome**(collectionId: string,
     body: PublicInteractionsCountsByOutcomeRequest,
     authToken?: string) → `Promise<OutcomeCount[]>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicMyInteractions**(collectionId: string,
     body: PublicInteractionsByUserRequest,
     authToken?: string) → `Promise<InteractionEventRow[]>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicList**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicGet**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 ### jobs
 

package/dist/docs/ai-guide-template.md

@@ -225,6 +225,8 @@ await SL.appConfiguration.setConfig({
 
 ### Tracked Interactions
 
+Use interaction IDs that are defined via `SL.interactions.create(...)` for the collection. Do not invent ad-hoc IDs in app code.
+
 | Interaction ID | Description                                   |
 | -------------- | --------------------------------------------- |
 | `page-view`    | Tracks each time a user views the public page |

package/dist/docs/auth-kit.md

@@ -86,10 +86,20 @@ Use these flows when you want low-friction verification before or without full a
 import { authKit } from '@proveanything/smartlinks';
 
 // 1) Send WhatsApp verification deep link
-const wa = await authKit.sendWhatsApp(clientId, {
-  phoneNumber: '+447911123456',
-  redirectUrl: 'https://app.example.com/checkout/continue',
-});
+const wa = await authKit.sendWhatsApp(clientId);
+
+// Optional: pass redirect context and/or a post-verification reply
+// const wa = await authKit.sendWhatsApp(clientId, {
+//   redirectUrl: 'https://app.example.com/checkout/continue',
+//   reply: {
+//     cta: {
+//       body: "You're verified and ready to bid.",
+//       buttonLabel: 'Back to Auction',
+//       buttonUrl: '{{returnUrl}}',
+//     },
+//     text: "You're verified. Return to the app to continue.",
+//   },
+// });
 
 // wa.waLink can be opened directly by the app/browser
 // Poll status while user switches to WhatsApp and back
@@ -133,6 +143,27 @@ Verification status values returned by `authKit.getWhatsAppStatus` are:
 - `expired`
 - `unknown`
 
+#### Post-verification reply
+
+Pass a `reply` object in `sendWhatsApp` to send a message back to the user after they confirm `CONFIRM <token>`. Reply resolution order:
+
+1. `reply.contentSid` — explicit Twilio Content SID
+2. `reply.cta` — CTA shorthand using the shared generic Twilio Content template SID (`TWILIO_WHATSAPP_GENERIC_CTA_SID`)
+3. `reply.text` — plain-text fallback
+4. Per-client default (`authKit/{clientId}.whatsapp` config)
+5. Built-in default text
+
+The following template placeholders are available in `reply.text`, `reply.cta` fields, and `reply.contentVariables` values:
+
+| Placeholder | Description |
+|---|---|
+| `{{returnUrl}}` | The resolved redirect URL |
+| `{{phoneNumber}}` | The verified phone number |
+| `{{clientId}}` | The Auth Kit client ID |
+| `{{token}}` | The verification token |
+
+> **Note:** `redirectUrl` is optional. WhatsApp tokens are short hex strings (16 chars) for better UX.
+
 ### Google OAuth
 
 ```ts

package/dist/docs/interactions.md

@@ -15,15 +15,19 @@ Interactions have two distinct layers:
 | **Interaction Types** | Definitions stored in the database — configure an interaction's ID, permissions, and display metadata once per collection |
 | **Interaction Events** | Individual event records logged each time a user performs that interaction |
 
+Critical rule: event `interactionId` values must reference an existing interaction type definition in that collection. Do not generate random IDs in app code and submit events against them.
+
 ```text
 ┌──────────────────────────────────────────────────────────────────┐
 │ Your App                                                         │
 │                                                                  │
 │  1. Create type once:  interactions.create(collectionId, {       │
 │       id: 'vote', permissions: { uniquePerUser: true } })        │
+│       -> definition exists in platform                           │
 │                                                                  │
 │  2. Log events:        interactions.appendEvent(collectionId, {  │
 │       interactionId: 'vote', outcome: 'option-a', userId })      │
+│       (must match the created definition ID)                     │
 │                                                                  │
 │  3. Read results:      interactions.countsByOutcome(collectionId, │
 │       { interactionId: 'vote' })                                 │
@@ -31,6 +35,14 @@ Interactions have two distinct layers:
 └──────────────────────────────────────────────────────────────────┘
 ```
 
+### Required Workflow (Do Not Invent IDs)
+
+1. Create an interaction type definition (admin endpoint) before recording any events.
+2. Reuse that same definition ID for every `appendEvent` / `submitPublicEvent` call.
+3. Treat unknown IDs as configuration errors, not as values your app should auto-create.
+
+If your app currently hardcodes strings like `"poll"` or `"entry"`, make sure those IDs are actually created as interaction types during setup.
+
 ---
 
 ## Common Use Cases
@@ -101,6 +113,8 @@ const { items } = await SL.interactions.publicList(collectionId, { appId: 'my-ap
 
 ## Logging Events
 
+Before logging events, ensure the referenced interaction type already exists. Event ingestion is not intended to create new interaction definitions.
+
 ### Admin Event Append
 
 Use on the server side or in admin flows. Requires `userId` **or** `contactId`.
@@ -166,7 +180,7 @@ await SL.interactions.updateEvent(collectionId, {
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `interactionId` | string | ✅ | Which interaction type this event belongs to |
+| `interactionId` | string | ✅ | Existing interaction type ID (must already be defined in this collection) |
 | `userId` or `contactId` | string | ✅ (one of) | The actor. `appendEvent` / `updateEvent` require one of these |
 | `appId` | string | ❌ | Scopes the event to your app |
 | `outcome` | string | ❌ | The result or choice — what `countsByOutcome()` aggregates |

package/dist/docs/loyalty.md

@@ -120,6 +120,8 @@ const { items } = await SL.loyalty.publicGetMineHistory(collectionId, schemeId,
 
 Earning rules are the control plane that connects interactions to point awards. The server evaluates them automatically — your app never sets a point value directly.
 
+Every `interactionId` in a loyalty rule must reference an existing interaction type definition in the same collection.
+
 ### Create a Rule
 
 ```typescript

package/dist/docs/overview.md

@@ -227,6 +227,8 @@ See `docs/ai.md` for complete documentation.
 
 The `SL.interactions` namespace tracks user engagement — competition entries, votes, form submissions, warranty registrations. Events can trigger automated journeys and communications.
 
+Important: create interaction type definitions first, then submit events using those existing IDs. Do not invent `interactionId` values in client code.
+
 Key functions: `submitPublicEvent()`, `appendEvent()` (admin), `countsByOutcome()`, `query()`.
 
 See `docs/interactions.md` for complete documentation.

package/dist/docs/realtime.md

@@ -590,6 +590,7 @@ When a user votes, publish to the channel:
 ```typescript
 const submitVote = async (option: string) => {
   // Record in SmartLinks
+  // 'poll' must already exist as an interaction type definition for this collection.
   await SL.interactions.submitPublicEvent(collectionId, {
     appId,
     interactionId: 'poll',

package/dist/openapi.yaml

@@ -17864,6 +17864,31 @@ components:
       required:
         - success
         - message
+    WhatsAppReplyCta:
+      type: object
+      properties:
+        body:
+          type: string
+        buttonLabel:
+          type: string
+        buttonUrl:
+          type: string
+      required:
+        - body
+        - buttonLabel
+        - buttonUrl
+    WhatsAppReplyOptions:
+      type: object
+      properties:
+        contentSid:
+          type: string
+        contentVariables:
+          type: object
+          additionalProperties: true
+        cta:
+          $ref: "#/components/schemas/WhatsAppReplyCta"
+        text:
+          type: string
     SendWhatsAppRequest:
       type: object
       properties:
@@ -17871,9 +17896,8 @@ components:
           type: string
         redirectUrl:
           type: string
-      required:
-        - phoneNumber
-        - redirectUrl
+        reply:
+          $ref: "#/components/schemas/WhatsAppReplyOptions"
     SendWhatsAppResponse:
       type: object
       properties:

package/dist/types/authKit.d.ts

@@ -76,9 +76,24 @@ export interface EmailVerifyTokenResponse {
     emailVerificationMode?: 'immediate' | 'verify-auto-login' | 'verify-manual-login';
 }
 export type VerifyStatus = 'pending' | 'verified' | 'failed' | 'expired' | 'unknown';
+export interface WhatsAppReplyCta {
+    body: string;
+    buttonLabel: string;
+    buttonUrl: string;
+}
+export interface WhatsAppReplyOptions {
+    /** Option A: explicit Twilio Content SID */
+    contentSid?: string;
+    contentVariables?: Record<string, unknown>;
+    /** Option B: CTA shorthand (uses shared generic CTA content SID) */
+    cta?: WhatsAppReplyCta;
+    /** Option C: plain-text fallback */
+    text?: string;
+}
 export interface SendWhatsAppRequest {
-    phoneNumber: string;
-    redirectUrl: string;
+    phoneNumber?: string;
+    redirectUrl?: string;
+    reply?: WhatsAppReplyOptions;
 }
 export interface SendWhatsAppResponse {
     waLink: string;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.13.10  |  Generated: 2026-05-12T16:12:33.784Z
+Version: 1.13.12  |  Generated: 2026-05-14T16:00:33.063Z
 
 This is a concise summary of all available API functions and types.
 
@@ -3024,11 +3024,31 @@ interface EmailVerifyTokenResponse {
 }
 ```
 
+**WhatsAppReplyCta** (interface)
+```typescript
+interface WhatsAppReplyCta {
+  body: string
+  buttonLabel: string
+  buttonUrl: string
+}
+```
+
+**WhatsAppReplyOptions** (interface)
+```typescript
+interface WhatsAppReplyOptions {
+  contentSid?: string
+  contentVariables?: Record<string, unknown>
+  cta?: WhatsAppReplyCta
+  text?: string
+}
+```
+
 **SendWhatsAppRequest** (interface)
 ```typescript
 interface SendWhatsAppRequest {
-  phoneNumber: string
-  redirectUrl: string
+  phoneNumber?: string
+  redirectUrl?: string
+  reply?: WhatsAppReplyOptions
 }
 ```
 
@@ -8192,7 +8212,7 @@ Send phone verification code (public).
 **verifyPhoneCode**(clientId: string, phoneNumber: string, code: string) → `Promise<PhoneVerifyResponse>`
 Verify phone verification code (public).
 
-**sendWhatsApp**(clientId: string, body: SendWhatsAppRequest) → `Promise<SendWhatsAppResponse>`
+**sendWhatsApp**(clientId: string, body: SendWhatsAppRequest = {}) → `Promise<SendWhatsAppResponse>`
 Send a WhatsApp verification deep-link (public).
 
 **verifyWhatsApp**(clientId: string, token: string, phoneNumber: string) → `Promise<VerifyWhatsAppResponse>`
@@ -8803,54 +8823,54 @@ Legacy-friendly alias for aggregate().
 
 **appendEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<`
-POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
+POST /admin/collection/:collectionId/interactions/append Appends one interaction event. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions.
 
 **updateEvent**(collectionId: string,
     body: UpdateInteractionBody) → `Promise<`
-POST /admin/collection/:collectionId/interactions/append Appends one interaction event.
+POST /admin/collection/:collectionId/interactions/append Appends one interaction event. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions.
 
 **submitPublicEvent**(collectionId: string,
     body: AppendInteractionBody) → `Promise<SubmitInteractionResponse | SubmitInteractionError>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **create**(collectionId: string,
     body: CreateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **list**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **get**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **update**(collectionId: string,
     id: string,
     patchBody: UpdateInteractionTypeBody) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **remove**(collectionId: string,
     id: string) → `Promise<void>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicCountsByOutcome**(collectionId: string,
     body: PublicInteractionsCountsByOutcomeRequest,
     authToken?: string) → `Promise<OutcomeCount[]>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicMyInteractions**(collectionId: string,
     body: PublicInteractionsByUserRequest,
     authToken?: string) → `Promise<InteractionEventRow[]>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicList**(collectionId: string,
     query: ListInteractionTypesQuery = {}) → `Promise<InteractionTypeList>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 **publicGet**(collectionId: string,
     id: string) → `Promise<InteractionTypeRecord>`
-POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
+POST /api/v1/public/collection/:collectionId/interactions/submit Submits an interaction event from a public/client-side context. `interactionId` must reference an existing interaction type definition. This endpoint does not create interaction definitions. When the interaction has `allowAnonymousSubmit: true`, neither `userId` nor `contactId` is required. Pass `anonId` inside `metadata` to enable device-level deduplication via `uniquePerAnonId`.
 
 ### jobs
 

package/docs/ai-guide-template.md

@@ -225,6 +225,8 @@ await SL.appConfiguration.setConfig({
 
 ### Tracked Interactions
 
+Use interaction IDs that are defined via `SL.interactions.create(...)` for the collection. Do not invent ad-hoc IDs in app code.
+
 | Interaction ID | Description                                   |
 | -------------- | --------------------------------------------- |
 | `page-view`    | Tracks each time a user views the public page |

package/docs/auth-kit.md

@@ -86,10 +86,20 @@ Use these flows when you want low-friction verification before or without full a
 import { authKit } from '@proveanything/smartlinks';
 
 // 1) Send WhatsApp verification deep link
-const wa = await authKit.sendWhatsApp(clientId, {
-  phoneNumber: '+447911123456',
-  redirectUrl: 'https://app.example.com/checkout/continue',
-});
+const wa = await authKit.sendWhatsApp(clientId);
+
+// Optional: pass redirect context and/or a post-verification reply
+// const wa = await authKit.sendWhatsApp(clientId, {
+//   redirectUrl: 'https://app.example.com/checkout/continue',
+//   reply: {
+//     cta: {
+//       body: "You're verified and ready to bid.",
+//       buttonLabel: 'Back to Auction',
+//       buttonUrl: '{{returnUrl}}',
+//     },
+//     text: "You're verified. Return to the app to continue.",
+//   },
+// });
 
 // wa.waLink can be opened directly by the app/browser
 // Poll status while user switches to WhatsApp and back
@@ -133,6 +143,27 @@ Verification status values returned by `authKit.getWhatsAppStatus` are:
 - `expired`
 - `unknown`
 
+#### Post-verification reply
+
+Pass a `reply` object in `sendWhatsApp` to send a message back to the user after they confirm `CONFIRM <token>`. Reply resolution order:
+
+1. `reply.contentSid` — explicit Twilio Content SID
+2. `reply.cta` — CTA shorthand using the shared generic Twilio Content template SID (`TWILIO_WHATSAPP_GENERIC_CTA_SID`)
+3. `reply.text` — plain-text fallback
+4. Per-client default (`authKit/{clientId}.whatsapp` config)
+5. Built-in default text
+
+The following template placeholders are available in `reply.text`, `reply.cta` fields, and `reply.contentVariables` values:
+
+| Placeholder | Description |
+|---|---|
+| `{{returnUrl}}` | The resolved redirect URL |
+| `{{phoneNumber}}` | The verified phone number |
+| `{{clientId}}` | The Auth Kit client ID |
+| `{{token}}` | The verification token |
+
+> **Note:** `redirectUrl` is optional. WhatsApp tokens are short hex strings (16 chars) for better UX.
+
 ### Google OAuth
 
 ```ts

package/docs/interactions.md

@@ -15,15 +15,19 @@ Interactions have two distinct layers:
 | **Interaction Types** | Definitions stored in the database — configure an interaction's ID, permissions, and display metadata once per collection |
 | **Interaction Events** | Individual event records logged each time a user performs that interaction |
 
+Critical rule: event `interactionId` values must reference an existing interaction type definition in that collection. Do not generate random IDs in app code and submit events against them.
+
 ```text
 ┌──────────────────────────────────────────────────────────────────┐
 │ Your App                                                         │
 │                                                                  │
 │  1. Create type once:  interactions.create(collectionId, {       │
 │       id: 'vote', permissions: { uniquePerUser: true } })        │
+│       -> definition exists in platform                           │
 │                                                                  │
 │  2. Log events:        interactions.appendEvent(collectionId, {  │
 │       interactionId: 'vote', outcome: 'option-a', userId })      │
+│       (must match the created definition ID)                     │
 │                                                                  │
 │  3. Read results:      interactions.countsByOutcome(collectionId, │
 │       { interactionId: 'vote' })                                 │
@@ -31,6 +35,14 @@ Interactions have two distinct layers:
 └──────────────────────────────────────────────────────────────────┘
 ```
 
+### Required Workflow (Do Not Invent IDs)
+
+1. Create an interaction type definition (admin endpoint) before recording any events.
+2. Reuse that same definition ID for every `appendEvent` / `submitPublicEvent` call.
+3. Treat unknown IDs as configuration errors, not as values your app should auto-create.
+
+If your app currently hardcodes strings like `"poll"` or `"entry"`, make sure those IDs are actually created as interaction types during setup.
+
 ---
 
 ## Common Use Cases
@@ -101,6 +113,8 @@ const { items } = await SL.interactions.publicList(collectionId, { appId: 'my-ap
 
 ## Logging Events
 
+Before logging events, ensure the referenced interaction type already exists. Event ingestion is not intended to create new interaction definitions.
+
 ### Admin Event Append
 
 Use on the server side or in admin flows. Requires `userId` **or** `contactId`.
@@ -166,7 +180,7 @@ await SL.interactions.updateEvent(collectionId, {
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `interactionId` | string | ✅ | Which interaction type this event belongs to |
+| `interactionId` | string | ✅ | Existing interaction type ID (must already be defined in this collection) |
 | `userId` or `contactId` | string | ✅ (one of) | The actor. `appendEvent` / `updateEvent` require one of these |
 | `appId` | string | ❌ | Scopes the event to your app |
 | `outcome` | string | ❌ | The result or choice — what `countsByOutcome()` aggregates |

package/docs/loyalty.md

@@ -120,6 +120,8 @@ const { items } = await SL.loyalty.publicGetMineHistory(collectionId, schemeId,
 
 Earning rules are the control plane that connects interactions to point awards. The server evaluates them automatically — your app never sets a point value directly.
 
+Every `interactionId` in a loyalty rule must reference an existing interaction type definition in the same collection.
+
 ### Create a Rule
 
 ```typescript

package/docs/overview.md

@@ -227,6 +227,8 @@ See `docs/ai.md` for complete documentation.
 
 The `SL.interactions` namespace tracks user engagement — competition entries, votes, form submissions, warranty registrations. Events can trigger automated journeys and communications.
 
+Important: create interaction type definitions first, then submit events using those existing IDs. Do not invent `interactionId` values in client code.
+
 Key functions: `submitPublicEvent()`, `appendEvent()` (admin), `countsByOutcome()`, `query()`.
 
 See `docs/interactions.md` for complete documentation.

package/docs/realtime.md

@@ -590,6 +590,7 @@ When a user votes, publish to the channel:
 ```typescript
 const submitVote = async (option: string) => {
   // Record in SmartLinks
+  // 'poll' must already exist as an interaction type definition for this collection.
   await SL.interactions.submitPublicEvent(collectionId, {
     appId,
     interactionId: 'poll',

package/openapi.yaml

@@ -17864,6 +17864,31 @@ components:
       required:
         - success
         - message
+    WhatsAppReplyCta:
+      type: object
+      properties:
+        body:
+          type: string
+        buttonLabel:
+          type: string
+        buttonUrl:
+          type: string
+      required:
+        - body
+        - buttonLabel
+        - buttonUrl
+    WhatsAppReplyOptions:
+      type: object
+      properties:
+        contentSid:
+          type: string
+        contentVariables:
+          type: object
+          additionalProperties: true
+        cta:
+          $ref: "#/components/schemas/WhatsAppReplyCta"
+        text:
+          type: string
     SendWhatsAppRequest:
       type: object
       properties:
@@ -17871,9 +17896,8 @@ components:
           type: string
         redirectUrl:
           type: string
-      required:
-        - phoneNumber
-        - redirectUrl
+        reply:
+          $ref: "#/components/schemas/WhatsAppReplyOptions"
     SendWhatsAppResponse:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.13.10",
+  "version": "1.13.12",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",