Integracao com o TypeBot

A integracao com o TypeBot permite que cada instancia do VZaps responda automaticamente as mensagens recebidas seguindo um fluxo conversacional. Voce pode configurar varios TypeBots por instancia, cada um com a sua condicao de gatilho e prioridade.

Visao geral

Cada instancia pode ter N TypeBots configurados.
Cada configuracao tem uma URL base (ex.: https://typebot.io), o public_id do flow e uma regra de gatilho.
Quando uma mensagem chega ao WhatsApp da instancia, a API avalia os TypeBots ativos em ordem de priority decrescente. O primeiro cujo gatilho casar com o texto recebido inicia a sessao.
Sessoes ativas sao identificadas pelo remote_jid do contato. Mensagens subsequentes do mesmo contato continuam a sessao em vez de criar uma nova.
Mensagens de audio podem ser transcritas para texto quando o recurso esta habilitado na infraestrutura VZaps. Depois da transcricao, o texto segue as mesmas regras de sessao e gatilho das mensagens digitadas.
Voce pode encerrar sessoes pelo painel ou pelo endpoint dedicado.

Campos da configuracao

Campo	Descricao
`enabled`	Quando `false`, o TypeBot e ignorado pela avaliacao de gatilhos.
`description`	Nome para identificacao no painel.
`typebot_url`	URL base do TypeBot (ex.: `https://typebot.io`).
`public_id`	Identificador publico do flow.
`trigger_type`	`all`, `keyword`, `contains`, `starts_with`, `regex`, `advanced` ou `none` (manual via API).
`trigger_operator`	Apenas para `trigger_type = advanced`: `equals`, `contains`, `starts_with` ou `regex`.
`trigger_value`	Texto/regex usado no gatilho (obrigatorio para tudo, exceto `all` e `none`).
`priority`	Ordem de avaliacao. O maior valor e avaliado primeiro.
`expire_in_minutes`	Encerra a sessao apos este tempo sem mensagens. `0` = nao expira automaticamente.
`keyword_finish`	Palavra exata enviada pelo contato para encerrar a sessao.
`default_delay_ms`	Delay aplicado entre cada mensagem enviada ao WhatsApp.
`unknown_message`	Mensagem enviada quando o TypeBot nao consegue interpretar a entrada.
`transcribe_audio`	Quando `true`, audios recebidos podem ser transcritos e tratados como texto pelo TypeBot.
`listen_from_me`	Quando `true`, mensagens enviadas pela propria instancia tambem alimentam o TypeBot.
`stop_bot_from_me`	Quando `true`, uma mensagem manual da instancia pausa o bot na conversa atual.
`keep_open`	Controla o que acontece com a sessao ao encerrar (expiracao, keyword_finish ou fim do flow): `true` preserva a row com `status=closed` para consulta historica; `false` apaga a sessao por completo. A expiracao por tempo ocorre em ambos os casos.
`debounce_ms`	Janela em ms para agrupar mensagens consecutivas do mesmo contato antes de enviar ao TypeBot.

Endpoints

GET /instances/{id}/typebots - lista os TypeBots configurados.
POST /instances/{id}/typebots - cria um TypeBot.
PATCH /instances/{id}/typebots/{typebotId} - atualiza configuracoes.
DELETE /instances/{id}/typebots/{typebotId} - remove a configuracao e suas sessoes.
POST /instances/{id}/typebots/sessions/start - inicia manualmente uma sessao do TypeBot para um contato usando o public_id do TypeBot, um push_name opcional e uma mensagem inicial.
GET /instances/{id}/typebots/sessions - lista sessoes ativas/encerradas.
POST /instances/{id}/typebots/sessions/{session}/pause - pausa uma sessao aberta manualmente. O path param session deve ser o UUID da sessao.
POST /instances/{id}/typebots/sessions/{session}/close - encerra uma sessao manualmente. O path param session aceita tanto o UUID da sessao quanto o numero de telefone do contato (so os digitos, ex.: 5532988776655); nesse caso, todas as sessoes ativas desse contato na instancia sao encerradas e a resposta traz closed com a quantidade.

Iniciar sessao manualmente

curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/typebots/sessions/start" \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "public_id": "dev",
    "phone": "5532999999999",
    "push_name": "Gustavo Almeida",
    "message": "Ola"
  }'

Exemplo: criar um TypeBot por palavra-chave

curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/typebots" \
  -H "Authorization: Bearer SEU_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Boas-vindas",
    "typebot_url": "https://typebot.io",
    "public_id": "meu-flow-publico",
    "trigger_type": "keyword",
    "trigger_value": "ola",
    "priority": 10,
    "expire_in_minutes": 30,
    "keyword_finish": "sair",
    "default_delay_ms": 800,
    "unknown_message": "Desculpe, nao entendi. Pode reformular?",
    "transcribe_audio": true,
    "listen_from_me": false,
    "stop_bot_from_me": true,
    "keep_open": false,
    "debounce_ms": 1500
  }'

Encerrar sessao por telefone

Quando um atendimento humano precisa assumir imediatamente e voce so tem o numero do contato em maos (sem o UUID da sessao), passe o telefone direto no path. A API localiza e encerra todas as sessoes ativas desse contato na instancia, independentemente de qual TypeBot as criou.

curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/typebots/sessions/5532988776655/close" \
  -H "Authorization: Bearer SEU_JWT"

Resposta:

{
  "status": "ok",
  "closed": 1,
  "phone": "5532988776655"
}

Se a instancia nao tiver nenhuma sessao ativa (opened ou paused) para esse numero, a API devolve 404.

Boas praticas

Use prioridades distintas para nao depender de ordem de criacao.
regex permite gatilhos sofisticados; teste antes em ambiente isolado.
debounce_ms evita disparar o bot multiplas vezes quando o contato envia varias mensagens em sequencia.
Para conversas que devem permanecer com o atendente humano, ative stop_bot_from_me.
keep_open=true so preserva o historico das sessoes encerradas; ele nao desativa a expiracao por expire_in_minutes.

​Visao geral

​Campos da configuracao

​Endpoints

​Iniciar sessao manualmente

​Exemplo: criar um TypeBot por palavra-chave

​Encerrar sessao por telefone

​Boas praticas