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

> Configurar TypeBot e gerenciar sessões com o SDK PHP

Use `$vzaps->typeBots()` para integrar fluxos TypeBot a uma instância VZaps.

Campos comuns em todas as chamadas:

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

## `typeBots()->list($instanceId, $instanceToken = null)`

Lista os TypeBots configurados na instância.

```php theme={null}
$typebots = $vzaps->typeBots()->list('VZ...', 'instance-token');

print_r($typebots);
```

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

## `typeBots()->create($request)`

Cria uma configuração de TypeBot.

```php theme={null}
$created = $vzaps->typeBots()->create([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'enabled' => true,
    'description' => 'Boas-vindas',
    'typebotUrl' => 'https://typebot.io',
    'publicId' => 'meu-flow-publico',
    'triggerType' => 'keyword',
    'triggerValue' => 'ola',
    'priority' => 10,
    'expireInMinutes' => 30,
    'keywordFinish' => 'sair',
    'defaultDelayMs' => 800,
    'unknownMessage' => 'Desculpe, não entendi. Pode reformular?',
    'transcribeAudio' => true,
    'listenFromMe' => false,
    'stopBotFromMe' => true,
    'keepOpen' => false,
    'debounceMs' => 1500,
    'ignoreGroups' => false,
]);

print_r($created);
```

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

Campos principais do payload:

| Campo             | Tipo      | Obrigatório | Descrição                                                                   |
| ----------------- | --------- | ----------- | --------------------------------------------------------------------------- |
| `enabled`         | `boolean` | Sim         | Ativa ou desativa o TypeBot na avaliação de gatilhos.                       |
| `description`     | `string`  | Sim         | Nome para identificação.                                                    |
| `typebotUrl`      | `string`  | Sim         | URL base do TypeBot.                                                        |
| `publicId`        | `string`  | Sim         | Identificador público do flow.                                              |
| `triggerType`     | `string`  | Sim         | `all`, `keyword`, `contains`, `starts_with`, `regex`, `advanced` ou `none`. |
| `triggerValue`    | `string`  | Condicional | Texto ou regex do gatilho.                                                  |
| `triggerOperator` | `string`  | Condicional | Usado quando `triggerType` é `advanced`.                                    |
| `priority`        | `number`  | Sim         | Ordem de avaliação. Maior valor primeiro.                                   |
| `expireInMinutes` | `number`  | Sim         | Expira sessão após inatividade. `0` não expira.                             |

## `typeBots()->update($request)`

Atualiza um TypeBot existente. Informe `typebotId` retornado na criação ou listagem.

```php theme={null}
$vzaps->typeBots()->update([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'typebotId' => '550e8400-e29b-41d4-a716-446655440000',
    'enabled' => true,
    'description' => 'Boas-vindas atualizado',
    'triggerType' => 'contains',
    'triggerValue' => 'ajuda',
    'priority' => 20,
    'expireInMinutes' => 60,
]);
```

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

## `typeBots()->delete($request)`

Remove a configuração e as sessões associadas.

```php theme={null}
$vzaps->typeBots()->delete([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'typebotId' => '550e8400-e29b-41d4-a716-446655440000',
]);
```

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

## `typeBots()->startSession($request)`

Inicia sessão manualmente com um contato.

Por `publicId`:

```php theme={null}
$vzaps->typeBots()->startSession([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'publicId' => 'support',
    'phone' => '5511999999999',
    'pushName' => 'Cliente',
    'message' => 'Quero atendimento',
]);
```

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

Por `typebotId`:

```php theme={null}
$vzaps->typeBots()->startSession([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'typebotId' => '550e8400-e29b-41d4-a716-446655440000',
    'phone' => '5511999999999',
    'message' => 'Quero atendimento',
]);
```

| Campo       | Tipo     | Obrigatório | Descrição                                                     |
| ----------- | -------- | ----------- | ------------------------------------------------------------- |
| `publicId`  | `string` | Condicional | Identificador público do flow. Use `publicId` ou `typebotId`. |
| `typebotId` | `string` | Condicional | ID interno do TypeBot.                                        |
| `phone`     | `string` | Sim         | Telefone do contato.                                          |
| `message`   | `string` | Sim         | Mensagem inicial enviada ao flow.                             |
| `pushName`  | `string` | Não         | Nome exibido do contato.                                      |

## `typeBots()->listSessions($instanceId, $instanceToken = null)`

Lista sessões ativas e encerradas.

```php theme={null}
$sessions = $vzaps->typeBots()->listSessions('VZ...', 'instance-token');

print_r($sessions);
```

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

## `typeBots()->pauseSession($request)`

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

```php theme={null}
$vzaps->typeBots()->pauseSession([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'session' => '550e8400-e29b-41d4-a716-446655440001',
]);
```

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

## `typeBots()->closeSession($request)`

Encerra uma sessão manualmente.

Por UUID da sessão:

```php theme={null}
$vzaps->typeBots()->closeSession([
    'instanceId' => 'VZ...',
    'instanceToken' => '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):

```php theme={null}
$vzaps->typeBots()->closeSession([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'session' => '5511999999999',
]);
```