> ## 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 e gerencie sessões com o SDK Python

Use `client.typebots` para integrar fluxos TypeBot com uma instância VZaps.

Campos comuns em todas as chamadas:

| Campo            | Tipo     | Obrigatório | Descrição           |
| ---------------- | -------- | ----------- | ------------------- |
| `instance_id`    | `string` | Sim         | ID da instância.    |
| `instance_token` | `string` | Sim         | Token da instância. |

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

Lista TypeBots configurados na instância.

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

**Retorno:** lista/array de configuracoes TypeBot da instancia (IDs, gatilhos, prioridade, etc.).

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

Cria uma configuração TypeBot.

```python theme={null}
created = client.typebots.create(
    instance_id="VZ...",
    instance_token="instance-token",
    enabled=True,
    description="Fluxo de boas-vindas",
    typebot_url="https://typebot.io",
    public_id="meu-fluxo-publico",
    trigger_type="keyword",
    trigger_value="ola",
    priority=10,
    expire_in_minutes=30,
    keyword_finish="sair",
    default_delay_ms=800,
    unknown_message="Não entendi. Pode reformular?",
    transcribe_audio=True,
    listen_from_me=False,
    stop_bot_from_me=True,
    keep_open=False,
    debounce_ms=1500,
    ignore_groups=False,
)

print(created)
```

**Retorno:** configuracao criada, incluindo `typebot_id` para updates posteriores.

Campos principais do payload:

| Campo               | Tipo      | Obrigatório | Descrição                                                                   |
| ------------------- | --------- | ----------- | --------------------------------------------------------------------------- |
| `enabled`           | `boolean` | Sim         | Habilita ou desabilita a avaliação de triggers.                             |
| `description`       | `string`  | Sim         | Nome de exibição da configuração.                                           |
| `typebot_url`       | `string`  | Sim         | URL base do TypeBot.                                                        |
| `public_id`         | `string`  | Sim         | Identificador público do fluxo.                                             |
| `trigger_type`      | `string`  | Sim         | `all`, `keyword`, `contains`, `starts_with`, `regex`, `advanced` ou `none`. |
| `trigger_value`     | `string`  | Condicional | Texto ou regex do trigger.                                                  |
| `trigger_operator`  | `string`  | Condicional | Usado quando `trigger_type` é `advanced`.                                   |
| `priority`          | `number`  | Sim         | Ordem de avaliação. Valor maior primeiro.                                   |
| `expire_in_minutes` | `number`  | Sim         | Expiração da sessão após inatividade. `0` significa sem expiração.          |

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

Atualiza um TypeBot existente. Passe `typebot_id` do create ou list.

```python theme={null}
client.typebots.update(
    instance_id="VZ...",
    instance_token="instance-token",
    typebot_id="550e8400-e29b-41d4-a716-446655440000",
    enabled=True,
    description="Fluxo de boas-vindas atualizado",
    trigger_type="contains",
    trigger_value="ajuda",
    priority=20,
    expire_in_minutes=60,
)
```

**Retorno:** configuracao atualizada ou `{ status: "ok" }`.

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

Remove a configuração e suas sessões.

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

**Retorno:** confirmacao de remocao (`{ status: "ok" }` ou mensagem equivalente).

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

Inicia uma sessão manualmente com um contato.

Por `public_id`:

```python theme={null}
client.typebots.start_session(
    instance_id="VZ...",
    instance_token="instance-token",
    public_id="suporte",
    phone="5511999999999",
    push_name="Cliente",
    message="Preciso de ajuda",
)
```

**Retorno:** sessao iniciada (UUID da sessao, contato, status `opened`).

Por `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="Preciso de ajuda",
)
```

| Campo        | Tipo     | Obrigatório | Descrição                                                        |
| ------------ | -------- | ----------- | ---------------------------------------------------------------- |
| `public_id`  | `string` | Condicional | Identificador público do fluxo. Use `public_id` ou `typebot_id`. |
| `typebot_id` | `string` | Condicional | ID interno do TypeBot.                                           |
| `phone`      | `string` | Sim         | Telefone do contato.                                             |
| `message`    | `string` | Sim         | Mensagem inicial enviada ao fluxo.                               |
| `push_name`  | `string` | Não         | Nome de exibição do contato.                                     |

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

Lista sessões ativas e encerradas.

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

**Retorno:** lista de sessoes (`opened`, `paused`, `closed`) por contato/flow.

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

Pausa uma sessão aberta. Passe o UUID da sessão em `session`.

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

**Retorno:** sessao com status `paused`.

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

Encerra uma sessão manualmente.

Por UUID da sessão:

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

**Retorno:** sessao encerrada (`closed`) ou confirmacao por telefone.

Por telefone do contato (encerra todas as sessões ativas desse número):

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