kipps-voiceagent

Embed the Kipps.AI voice agent in Expo and React Native apps. Web renders an iframe; iOS/Android use react-native-webview.

Features

• Simple embed: One component to render the voice agent on web and native.
• Auto init or manual: Control when to start the call with autoInit or ref.init().
• Event bridge: Receive bot events via the onEvent callback.

Installation

Install peer dependencies in your Expo app:

expo install react-native-webview

Then add this package (from npm or local workspace):

npm i kipps-voiceagent
# or in workspaces: "kipps-voiceagent": "file:../packages/expo-voicebot"

Requirements

• react >= 18
• react-native >= 0.73 (Expo SDK 50+)
• expo >= 50
• react-native-webview >= 13

Permissions (Expo)

Add to app.json or app.config.ts:

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSMicrophoneUsageDescription": "This app requires microphone access for voice calls."
      }
    },
    "android": {
      "permissions": ["RECORD_AUDIO"]
    }
  }
}

Usage

import { KippsVoiceAgent } from 'kipps-voiceagent';
// or default: import KippsVoiceAgent from 'kipps-voiceagent'

export default function Screen() {
  return (
    <KippsVoiceAgent
      botId="YOUR_BOT_ID"
      initPayload={{
        caller_name: 'Jane',
        caller_id: 'WebUser-123',
        call_origin: 'click-to-call'
      }}
      height={500}
      width={280}
      onEvent={(evt) => console.log('Kipps event', evt)}
    />
  );
}

Passing Voiceagent ID and Data

• Voiceagent ID: Provide your bot’s ID via the botId prop.
• Data object: Provide initial call data via initPayload.

TypeScript types:

type KippsInitPayload = {
  caller_name?: string;
  caller_id?: string;
  call_origin?: string;
  response?: string;
  [k: string]: any; // you may pass additional custom fields
};

Example (auto-init, default behavior):

<KippsVoiceAgent
  botId="YOUR_BOT_ID"
  initPayload={{
    caller_name: 'Jane',
    caller_id: 'User-42',
    call_origin: 'support-chat',
    // any additional fields your bot expects
    ticketId: 'ABC-123'
  }}
  onEvent={(e) => console.log(e)}
/>

Manual init (for starting the call after your own logic/auth):

import React, { useRef } from 'react';
import { KippsVoiceAgent, KippsVoiceAgentRef } from 'kipps-voiceagent';

export default function Screen() {
  const ref = useRef<KippsVoiceAgentRef>(null);

  const startCall = () => {
    // do your checks (auth, consent, etc.)
    ref.current?.init();
  };

  return (
    <>
      <Button title="Start Voice Agent" onPress={startCall} />
      <KippsVoiceAgent
        ref={ref}
        botId="YOUR_BOT_ID"
        autoInit={false}
        initPayload={{ caller_name: 'Jane', caller_id: 'User-42' }}
      />
    </>
  );
}

Notes:

• On web, an iframe posts messages to your app; on native, messages come from the WebView bridge.
• Ensure any custom fields in initPayload match what your bot configuration expects.

Props

• botId: string (required)
• initPayload?: object
• origin?: string (default https://app.kipps.ai)
• path?: string (default /iframe-voice-bot/{botId}/call)
• height?: number, width?: number, style?
• onEvent?: (event) => void
• autoInit?: boolean (default true)

Events

• onEvent(event) receives messages posted from the bot page. On web, messages arrive via postMessage from the iframe; on native, via WebView's message bridge.

Troubleshooting

• If the call doesn’t start automatically, set autoInit={false} and call ref.init() after your own auth/logic.
• Ensure microphone permissions are accepted on the device/simulator.
• Verify origin is reachable and matches your environment (defaults to https://app.kipps.ai).

License

MIT