Bot Builder

Node Reference

Full node list for visual builder with safe placeholder examples and validation-aligned structure.

Each example below is a graph-save node object, so it includes required groupKey, position, and config.

send_text

Required fields: groupKey, position, config.message

json

{ "id": "node_send_text", "type": "send_text", "groupKey": "send_message", "position": { "x": 160, "y": 120 }, "config": { "message": "Sample message" } }

send_media

Required fields: groupKey, position, config.mediaType, config.mediaAssetId | config.mediaUrl | config.mediaId

json

{ "id": "node_send_media", "type": "send_media", "groupKey": "send_message", "position": { "x": 160, "y": 120 }, "config": { "mediaType": "image", "mediaUrl": "https://example.invalid/image.jpg", "message": "Optional caption" } }

send_template

Required fields: groupKey, position, config.templateName, config.languageCode

json

{ "id": "node_send_template", "type": "send_template", "groupKey": "send_message", "position": { "x": 160, "y": 120 }, "config": { "templateName": "sample_template", "languageCode": "en", "bodyVariables": ["sample_name"] } }

send_whatsapp_flow

Required fields: groupKey, position, config.flowId

json

{ "id": "node_send_flow", "type": "send_whatsapp_flow", "groupKey": "send_message", "position": { "x": 160, "y": 120 }, "config": { "flowId": "flow_example_id", "flowToken": "flow_token_example" } }

send_location

Required fields: groupKey, position, config.latitude, config.longitude

json

{ "id": "node_send_location", "type": "send_location", "groupKey": "send_message", "position": { "x": 160, "y": 120 }, "config": { "latitude": 12.3401, "longitude": 77.5602, "locationName": "Sample Location", "locationAddress": "MG Road, Bengaluru" } }

ask_text

Required fields: groupKey, position, config.message

json

{ "id": "node_ask_text", "type": "ask_text", "groupKey": "ask_questions", "position": { "x": 160, "y": 120 }, "config": { "message": "Enter your name" } }

ask_number

Required fields: groupKey, position, config.message

json

{ "id": "node_ask_number", "type": "ask_number", "groupKey": "ask_questions", "position": { "x": 160, "y": 120 }, "config": { "message": "Enter your score" } }

ask_phone

Required fields: groupKey, position, config.message

json

{ "id": "node_ask_phone", "type": "ask_phone", "groupKey": "ask_questions", "position": { "x": 160, "y": 120 }, "config": { "message": "Enter phone number" } }

ask_email

Required fields: groupKey, position, config.message

json

{ "id": "node_ask_email", "type": "ask_email", "groupKey": "ask_questions", "position": { "x": 160, "y": 120 }, "config": { "message": "Enter email" } }

ask_date

Required fields: groupKey, position, config.message

json

{ "id": "node_ask_date", "type": "ask_date", "groupKey": "ask_questions", "position": { "x": 160, "y": 120 }, "config": { "message": "Enter date (YYYY-MM-DD)" } }

ask_location

Required fields: groupKey, position, config.message

json

{ "id": "node_ask_location", "type": "ask_location", "groupKey": "ask_questions", "position": { "x": 160, "y": 120 }, "config": { "message": "Share your location" } }

ask_button

Required fields: groupKey, position, config.message, config.options (max 3, each <= 20 chars)

json

{ "id": "node_ask_button", "type": "ask_button", "groupKey": "choices", "position": { "x": 160, "y": 120 }, "config": { "message": "Choose one", "options": ["Option A", "Option B"] } }

ask_list

Required fields: groupKey, position, config.message, config.options (max 10)

json

{ "id": "node_ask_list", "type": "ask_list", "groupKey": "choices", "position": { "x": 160, "y": 120 }, "config": { "message": "Pick an item", "options": ["Item 1", "Item 2", "Item 3"] } }

condition

Required fields: groupKey, position, config.expression, branches true/false/default

json

{ "id": "node_condition", "type": "condition", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "expression": "gt({{score}}, 50)" } }

switch

Required fields: groupKey, position, config.variableKey, config.options[], matching branches + optional default

json

{ "id": "node_switch", "type": "switch", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "variableKey": "lead_grade", "options": ["hot", "warm", "cold"] } }

data_lookup

Required fields: groupKey, position, config.variableKey, config.recordsJson, success/not_found/error branches

json

{ "id": "node_lookup", "type": "data_lookup", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "variableKey": "sku_code", "outputVariableKey": "sku_name", "recordsJson": "{\"sku_101\":\"Paracetamol 650mg\"}" } }

Switch Operator Cheat Sheet

text

equals: exact text/number match
not_equals: values are different
contains: left value contains text
in_list: value exists in list
regex: regex test
greater_than / greater_or_equal: numeric comparisons
less_than / less_or_equal: numeric comparisons
between: numeric range using value + valueTo
fallback: connect a default branch when no case matches

set_variable

Required fields: groupKey, position, config.variableKey, config.expression | config.value

json

{ "id": "node_set_var", "type": "set_variable", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "variableKey": "lead_grade", "expression": "if(gt({{score}}, 80), 'hot', 'warm')" } }

delay

Required fields: groupKey, position, config.delaySeconds (positive integer)

json

{ "id": "node_delay", "type": "delay", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "delaySeconds": 5 } }

jump_to

Required fields: groupKey, position, config.targetNodeId

json

{ "id": "node_jump", "type": "jump_to", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "targetNodeId": "node_end" } }

end

Required fields: groupKey, position

json

{ "id": "node_end", "type": "end", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": {} }

human_handoff

Required fields: groupKey, position

json

{ "id": "node_handoff", "type": "human_handoff", "groupKey": "operations", "position": { "x": 160, "y": 120 }, "config": { "message": "Agent will join shortly" } }

release_to_bot

Required fields: groupKey, position

json

{ "id": "node_release", "type": "release_to_bot", "groupKey": "operations", "position": { "x": 160, "y": 120 }, "config": { "message": "Bot resumed" } }

tag_conversation

Required fields: groupKey, position, config.tag

json

{ "id": "node_tag", "type": "tag_conversation", "groupKey": "operations", "position": { "x": 160, "y": 120 }, "config": { "tag": "sample_tag" } }

add_note

Required fields: groupKey, position

json

{ "id": "node_note", "type": "add_note", "groupKey": "operations", "position": { "x": 160, "y": 120 }, "config": { "note": "Sample internal note" } }

persist_lead

Required fields: groupKey, position, config.variableKeys (recommended)

json

{ "id": "node_persist", "type": "persist_lead", "groupKey": "operations", "position": { "x": 160, "y": 120 }, "config": { "variableKeys": ["lead_name", "lead_phone"] } }

notify_team

Required fields: groupKey, position, config.variableKeys (recommended)

json

{ "id": "node_notify", "type": "notify_team", "groupKey": "operations", "position": { "x": 160, "y": 120 }, "config": { "variableKeys": ["lead_name", "lead_grade"] } }

google_sheets

Required fields: groupKey, position, config.credentialId, config.operation, config.documentId, config.sheetName, success/not_found/error branches

json

{ "id": "node_google_sheets", "type": "google_sheets", "groupKey": "logic_utilities", "position": { "x": 160, "y": 120 }, "config": { "credentialId": "google_sheets_account_1", "resource": "sheet_within_document", "operation": "get_rows", "documentId": "1AbCdEf", "sheetName": "Sheet1", "lookupVariableKey": "sku_code", "keyColumn": "key", "resultColumn": "value", "outputVariableKey": "sku_name" } }

Google Sheets OAuth2 (Single Service)

This guide covers how to connect a Google Sheets credential in SmsPort Visual Builder and validate it with a real test. Open the full Google Sheets integration runbook.

Prerequisites

Google Cloud project
Google Sheets API enabled
Google Drive API only if SmsPort adds spreadsheet picker/list/search
OAuth consent screen configured
OAuth client credentials (Web application)

SmsPort Connection Modes

OAuth2 (recommended): direct Google OAuth flow in popup.
Web App URL (legacy): Apps Script fallback; use only when required.

Set Up OAuth2 (Recommended)

Open Visual Builder and select a google_sheets node.
Open Create / Manage credential.
Set Connection mode = OAuth2 (recommended).
Enter OAuth Client ID and OAuth Client Secret.
Copy OAuth Redirect URL from SmsPort popup.
In Google Cloud OAuth client, paste that URL into Authorized redirect URIs (exact match required).
Click Connect Google and complete Google consent.
Click Save credential.
Click Test connection.

Use in Node

Select credential in node config.
Set documentId and sheetName.
Choose operation (for example get_rows).
Run simulator/test scenario and verify success branch output.

Troubleshooting

redirect_uri_mismatch: use the exact redirect URL shown in SmsPort popup.
Google hasn't verified this app: add your account as a test user or publish consent screen.
Connected badge only means OAuth linked; run Test connection for runtime readiness.
If prod still shows localhost redirect URL, set INTEGRATIONS_GOOGLE_OAUTH_CALLBACK_URL (or APP_API_URL) in env.

Expression functions|Visual builder standard|Google Sheets integration|Bot builder API map

Node Reference

Quick Jump

send_text

send_media

send_template

send_whatsapp_flow

send_location

ask_text

ask_number

ask_phone

ask_email

ask_date

ask_location

ask_button

ask_list

condition

switch

data_lookup

Switch Operator Cheat Sheet

set_variable

delay

jump_to

end

human_handoff

release_to_bot

tag_conversation

add_note

persist_lead

notify_team

google_sheets

Google Sheets OAuth2 (Single Service)

Prerequisites

SmsPort Connection Modes

Set Up OAuth2 (Recommended)

Use in Node

Troubleshooting