> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vzaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeBot

> Configure TypeBot and manage sessions with the TypeScript SDK

Use `vzaps.typebots` to integrate TypeBot flows with a VZaps instance.

Common fields on every call:

| Field           | Type     | Required | Description     |
| --------------- | -------- | -------- | --------------- |
| `instanceId`    | `string` | Yes      | Instance ID.    |
| `instanceToken` | `string` | Yes      | Instance token. |

## `typebots.list(instanceId, options?)`

Lists TypeBots configured on the instance.

```ts theme={null}
const typebots = await vzaps.typebots.list('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(typebots, { depth: null });
```

**Return:** array of TypeBot configs for the instance (IDs, triggers, priority, etc.).

## `typebots.create(request)`

Creates a TypeBot configuration.

```ts theme={null}
const created = await vzaps.typebots.create({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  enabled: true,
  description: 'Welcome flow',
  typebotUrl: 'https://typebot.io',
  publicId: 'my-public-flow',
  triggerType: 'keyword',
  triggerValue: 'hello',
  priority: 10,
  expireInMinutes: 30,
  keywordFinish: 'exit',
  defaultDelayMs: 800,
  unknownMessage: 'Sorry, I did not understand. Can you rephrase?',
  transcribeAudio: true,
  listenFromMe: false,
  stopBotFromMe: true,
  keepOpen: false,
  debounceMs: 1500,
  ignoreGroups: false,
});

console.dir(created, { depth: null });
```

**Return:** created config, including `typebotId` for later updates.

Main payload fields:

| Field             | Type      | Required    | Description                                                                  |
| ----------------- | --------- | ----------- | ---------------------------------------------------------------------------- |
| `enabled`         | `boolean` | Yes         | Enables or disables trigger evaluation.                                      |
| `description`     | `string`  | Yes         | Display name for the configuration.                                          |
| `typebotUrl`      | `string`  | Yes         | TypeBot base URL.                                                            |
| `publicId`        | `string`  | Yes         | Public flow identifier.                                                      |
| `triggerType`     | `string`  | Yes         | `all`, `keyword`, `contains`, `starts_with`, `regex`, `advanced`, or `none`. |
| `triggerValue`    | `string`  | Conditional | Trigger text or regex.                                                       |
| `triggerOperator` | `string`  | Conditional | Used when `triggerType` is `advanced`.                                       |
| `priority`        | `number`  | Yes         | Evaluation order. Higher value first.                                        |
| `expireInMinutes` | `number`  | Yes         | Session expiry after inactivity. `0` means no expiry.                        |

## `typebots.update(request)`

Updates an existing TypeBot. Pass `typebotId` from create or list.

```ts theme={null}
await vzaps.typebots.update({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  typebotId: '550e8400-e29b-41d4-a716-446655440000',
  enabled: true,
  description: 'Updated welcome flow',
  triggerType: 'contains',
  triggerValue: 'help',
  priority: 20,
  expireInMinutes: 60,
});
```

**Return:** updated config or `{ status: "ok" }`.

## `typebots.delete(request)`

Removes the configuration and its sessions.

```ts theme={null}
await vzaps.typebots.delete({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  typebotId: '550e8400-e29b-41d4-a716-446655440000',
});
```

**Return:** deletion confirmation (`{ status: "ok" }` or equivalent message).

## `typebots.startSession(request)`

Starts a session manually with a contact.

By `publicId`:

```ts theme={null}
await vzaps.typebots.startSession({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  publicId: 'support',
  phone: '5511999999999',
  pushName: 'Customer',
  message: 'I need help',
});
```

**Return:** started session (session UUID, contact, `opened` status).

By `typebotId`:

```ts theme={null}
await vzaps.typebots.startSession({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  typebotId: '550e8400-e29b-41d4-a716-446655440000',
  phone: '5511999999999',
  message: 'I need help',
});
```

| Field       | Type     | Required    | Description                                            |
| ----------- | -------- | ----------- | ------------------------------------------------------ |
| `publicId`  | `string` | Conditional | Public flow identifier. Use `publicId` or `typebotId`. |
| `typebotId` | `string` | Conditional | Internal TypeBot ID.                                   |
| `phone`     | `string` | Yes         | Contact phone.                                         |
| `message`   | `string` | Yes         | Initial message sent to the flow.                      |
| `pushName`  | `string` | No          | Contact display name.                                  |

## `typebots.listSessions(instanceId, options?)`

Lists active and closed sessions.

```ts theme={null}
const sessions = await vzaps.typebots.listSessions('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(sessions, { depth: null });
```

**Return:** session list (`opened`, `paused`, `closed`) per contact/flow.

## `typebots.pauseSession(request)`

Pauses an open session. Pass the session UUID in `session`.

```ts theme={null}
await vzaps.typebots.pauseSession({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  session: '550e8400-e29b-41d4-a716-446655440001',
});
```

**Return:** session with `paused` status.

## `typebots.closeSession(request)`

Closes a session manually.

By session UUID:

```ts theme={null}
await vzaps.typebots.closeSession({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  session: '550e8400-e29b-41d4-a716-446655440001',
});
```

**Return:** closed session or confirmation by phone number.

By contact phone (closes all active sessions for that number):

```ts theme={null}
await vzaps.typebots.closeSession({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  session: '5511999999999',
});
```