Vue

Vue SDK

The Vue SDK provides a plugin, composables, and pre-built components for integrating Vocall into Vue 3.4+ applications.

Installation

npm install @primoia/vocall-vue

Peer dependency: vue >=3.4

---

VocallPlugin

Register the plugin in your application entry point. The options are passed to the underlying client.

// main.ts
import { createApp } from 'vue';
import { VocallPlugin } from '@primoia/vocall-vue';
import App from './App.vue';

const app = createApp(App);

app.use(VocallPlugin, {
  url: 'wss://engine.example.com/connect',
  token: 'my-token',
  visitorId: 'optional-visitor-id',
});

app.mount('#app');

| Option | Type | Required | Description | |---|---|---|---| | url | string | Yes | WebSocket URL of the Vocall engine. | | token | string | Yes | Authentication token. | | visitorId | string | No | Optional identifier for the visitor session. |

---

useVocall

The primary composable. Returns reactive refs and control methods.

import { useVocall } from '@primoia/vocall-vue';

const { status, messages, connected, sessionId, sendText, connect, disconnect, client } = useVocall();

| Property | Type | Description | |---|---|---| | status | Ref<VocallStatus> | Current engine status (disconnected, idle, listening, recording, thinking, speaking, executing). | | messages | Ref<Message[]> | Chat message history. | | connected | Ref<boolean> | Whether the WebSocket is connected. | | sessionId | Ref<string \| null> | Active session identifier. | | sendText | (text: string) => void | Send a text message to the engine. | | connect | () => void | Open the WebSocket connection. | | disconnect | () => void | Close the connection. | | client | VocallClient | Underlying client instance for advanced use. |

---

useVocallField

Binds a template ref to a manifest field so the engine can read and write its value.

const { fieldRef, value } = useVocallField({ fieldId, client });

| Option | Type | Description | |---|---|---| | fieldId | string | The field identifier from your manifest. | | client | VocallClient | The client instance from useVocall(). |

| Return | Type | Description | |---|---|---| | fieldRef | Ref<HTMLElement \| null> | Template ref to bind to the input element. | | value | Ref<string> | Reactive value that stays in sync with the field. |

---

useVocallAction

Registers a handler that the engine can invoke by action identifier.

useVocallAction({ actionId, client, handler });

| Option | Type | Description | |---|---|---| | actionId | string | The action identifier from your manifest. | | client | VocallClient | The client instance from useVocall(). | | handler | () => void | Function executed when the engine triggers this action. |

---

Built-in Components

VocallChat

A chat panel that renders messages and provides text input.

| Prop | Type | Default | Description | |---|---|---|---| | position | 'left' \| 'right' | 'right' | Side of the screen. | | title | string | 'Vocall' | Header title. | | placeholder | string | 'Type a message...' | Input placeholder text. | | open | boolean | false | Controlled open state. |

| Event | Payload | Description | |---|---|---| | update:open | boolean | Emitted when the user opens or closes the chat (supports v-model:open). |

VocallFab

A floating action button that toggles the chat panel or triggers voice input.

VocallStatus

A small badge that displays the current VocallStatus as a colored indicator.

---

Full Example

<script setup lang="ts">
import { useVocall, useVocallField, useVocallAction, VocallChat, VocallFab } from '@primoia/vocall-vue';
import { ref } from 'vue';

const { status, messages, sendText, client } = useVocall();

const clientName = useVocallField({ fieldId: 'clientName', client });
const amount     = useVocallField({ fieldId: 'amount', client });

useVocallAction({
  actionId: 'submit',
  client,
  handler: () => {
    console.log('Engine triggered submit');
  },
});

const chatOpen = ref(false);
</script>

<template>
  <div>
    <h1>Emitir NFS-e</h1>

    <label>Client Name</label>
    <input ref="clientName.fieldRef" placeholder="Client name" />

    <label>Amount</label>
    <input ref="amount.fieldRef" placeholder="0.00" />

    <p>Status: {{ status }}</p>

    <VocallChat
      title="Invoice Assistant"
      position="right"
      v-model:open="chatOpen"
    />
    <VocallFab @click="chatOpen = !chatOpen" />
  </div>
</template>

---

Manifest Structure

Field and action identifiers must match your application manifest. See the Manifest Reference for details.