> ## 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 Python SDK

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

Common fields on every call:

| Field            | Type     | Required | Description     |
| ---------------- | -------- | -------- | --------------- |
| `instance_id`    | `string` | Yes      | Instance ID.    |
| `instance_token` | `string` | Yes      | Instance token. |

## `client.typebots.list(instance_id, instance_token=...)`

Lists TypeBots configured on the instance.

```python theme={null}
typebots = client.typebots.list("VZ...", instance_token="instance-token")
print(typebots)
```

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

## `client.typebots.create(...)`

Creates a TypeBot configuration.

```python theme={null}
created = client.typebots.create(
    instance_id="VZ...",
    instance_token="instance-token",
    enabled=True,
    description="Welcome flow",
    typebot_url="https://typebot.io",
    public_id="my-public-flow",
    trigger_type="keyword",
    trigger_value="hello",
    priority=10,
    expire_in_minutes=30,
    keyword_finish="exit",
    default_delay_ms=800,
    unknown_message="Sorry, I did not understand. Can you rephrase?",
    transcribe_audio=True,
    listen_from_me=False,
    stop_bot_from_me=True,
    keep_open=False,
    debounce_ms=1500,
    ignore_groups=False,
)

print(created)
```

**Return:** created config, including `typebot_id` 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.                                          |
| `typebot_url`       | `string`  | Yes         | TypeBot base URL.                                                            |
| `public_id`         | `string`  | Yes         | Public flow identifier.                                                      |
| `trigger_type`      | `string`  | Yes         | `all`, `keyword`, `contains`, `starts_with`, `regex`, `advanced`, or `none`. |
| `trigger_value`     | `string`  | Conditional | Trigger text or regex.                                                       |
| `trigger_operator`  | `string`  | Conditional | Used when `trigger_type` is `advanced`.                                      |
| `priority`          | `number`  | Yes         | Evaluation order. Higher value first.                                        |
| `expire_in_minutes` | `number`  | Yes         | Session expiry after inactivity. `0` means no expiry.                        |

## `client.typebots.update(...)`

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

```python theme={null}
client.typebots.update(
    instance_id="VZ...",
    instance_token="instance-token",
    typebot_id="550e8400-e29b-41d4-a716-446655440000",
    enabled=True,
    description="Updated welcome flow",
    trigger_type="contains",
    trigger_value="help",
    priority=20,
    expire_in_minutes=60,
)
```

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

## `client.typebots.delete(...)`

Removes the configuration and its sessions.

```python theme={null}
client.typebots.delete(
    instance_id="VZ...",
    instance_token="instance-token",
    typebot_id="550e8400-e29b-41d4-a716-446655440000",
)
```

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

## `client.typebots.start_session(...)`

Starts a session manually with a contact.

By `public_id`:

```python theme={null}
client.typebots.start_session(
    instance_id="VZ...",
    instance_token="instance-token",
    public_id="support",
    phone="5511999999999",
    push_name="Customer",
    message="I need help",
)
```

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

By `typebot_id`:

```python theme={null}
client.typebots.start_session(
    instance_id="VZ...",
    instance_token="instance-token",
    typebot_id="550e8400-e29b-41d4-a716-446655440000",
    phone="5511999999999",
    message="I need help",
)
```

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

## `client.typebots.list_sessions(instance_id, instance_token=...)`

Lists active and closed sessions.

```python theme={null}
sessions = client.typebots.list_sessions("VZ...", instance_token="instance-token")
print(sessions)
```

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

## `client.typebots.pause_session(...)`

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

```python theme={null}
client.typebots.pause_session(
    instance_id="VZ...",
    instance_token="instance-token",
    session="550e8400-e29b-41d4-a716-446655440001",
)
```

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

## `client.typebots.close_session(...)`

Closes a session manually.

By session UUID:

```python theme={null}
client.typebots.close_session(
    instance_id="VZ...",
    instance_token="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):

```python theme={null}
client.typebots.close_session(
    instance_id="VZ...",
    instance_token="instance-token",
    session="5511999999999",
)
```