Skip to main content
The TypeBot integration lets each VZaps instance answer incoming WhatsApp messages with a conversational flow. You can configure multiple TypeBots per instance, each with its own trigger condition and priority.

​
Overview

  • Each instance can have N TypeBots configured.
  • Every configuration carries a base URL (e.g. https://typebot.io), the flow public_id and a trigger rule.
  • When a message reaches the WhatsApp of the instance, the API evaluates enabled TypeBots in descending priority. The first whose trigger matches the incoming text starts the session.
  • Active sessions are keyed by the contact’s remote_jid. Subsequent messages from the same contact continue the session instead of starting a new one.
  • Audio messages can be transcribed to text when the feature is enabled in the VZaps infrastructure. After transcription, the text follows the same session and trigger rules as typed messages.
  • Sessions can be closed from the dashboard or via the dedicated endpoint.

​
Configuration fields

FieldDescription
enabledWhen false, the TypeBot is ignored by the trigger evaluation.
descriptionFriendly name shown in the dashboard.
typebot_urlTypeBot site root (e.g. https://typebot.io).
public_idPublic identifier of the flow.
trigger_typeall, keyword, contains, starts_with, regex, advanced or none (manual via API).
trigger_operatorOnly for trigger_type = advanced: equals, contains, starts_with or regex.
trigger_valueText/regex used by the trigger (required for everything except all and none).
priorityEvaluation order. Higher value is evaluated first.
expire_in_minutesCloses the session after this idle window. 0 = never expires automatically.
keyword_finishExact word the contact sends to close the session.
default_delay_msDelay applied between every outbound WhatsApp message.
unknown_messageMessage sent when TypeBot cannot interpret the input.
transcribe_audioWhen true, incoming audio messages can be transcribed and handled as text by TypeBot.
listen_from_meWhen true, messages sent by the instance itself also feed the TypeBot.
stop_bot_from_meWhen true, a manual message from the instance pauses the bot for the current conversation.
keep_openControls what happens to the session when it ends (expire, keyword_finish or flow completion): true keeps the row with status=closed for history; false deletes it entirely. Time-based expiration applies either way.
debounce_msWindow in ms to merge consecutive messages from the same contact before forwarding to TypeBot.

​
Endpoints

  • GET /instances/{id}/typebots - list configured TypeBots.
  • POST /instances/{id}/typebots - create a TypeBot.
  • PATCH /instances/{id}/typebots/{typebotId} - update configuration.
  • DELETE /instances/{id}/typebots/{typebotId} - remove the configuration and its sessions.
  • POST /instances/{id}/typebots/sessions/start - manually start a TypeBot session for a contact using the TypeBot public_id, an optional push_name, and an initial message.
  • GET /instances/{id}/typebots/sessions - list active/closed sessions.
  • POST /instances/{id}/typebots/sessions/{session}/pause - pause an opened session manually. The session path parameter must be the session UUID.
  • POST /instances/{id}/typebots/sessions/{session}/close - close a session manually. The session path parameter accepts both the session UUID or the contact’s phone number (digits only, e.g. 5532988776655); in the latter case every active session of that contact on the instance is closed and the response returns closed with the count.

​
Start a session manually

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

​
Example: create a keyword-triggered TypeBot

curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/typebots" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "description": "Welcome",
    "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. Could you rephrase?",
    "transcribe_audio": true,
    "listen_from_me": false,
    "stop_bot_from_me": true,
    "keep_open": false,
    "debounce_ms": 1500
  }'

​
Close a session by phone

When a human agent needs to take over immediately and you only have the contact’s phone number (no session UUID), pass the phone directly in the path. The API looks up and closes every active session of that contact on the instance, regardless of which TypeBot created them. 
curl -X POST "https://api.vzaps.com/instances/INSTANCE_ID/typebots/sessions/5532988776655/close" \
  -H "Authorization: Bearer YOUR_JWT"
Response: 
{
  "status": "ok",
  "closed": 1,
  "phone": "5532988776655"
}
If the instance has no active (opened or paused) session for that phone, the API returns 404.

​
Best practices

  • Assign distinct priorities so behavior does not depend on creation order.
  • regex enables sophisticated triggers; test in a sandbox first.
  • debounce_ms prevents the bot from firing multiple times when the contact sends several messages in a row.
  • Enable stop_bot_from_me for conversations that should stay with a human agent.
  • keep_open=true only preserves the history of finished sessions; it does not disable the expire_in_minutes idle timeout.