Vext documentation

Overview

A Vext workspace contains devices, workflows, agents, and contact databases. Devices connect your WhatsApp or Telegram account. Workflows define outbound automations. Agents handle inbound conversations. Integrations bring data in and push data out.

Everything is triggered by one of four sources: an inbound message, a schedule, an API call, or an external integration (Zapier, ChatGPT, CRM webhooks, MCP clients).

Getting started

A typical first setup:

1. Create your workspace and add credits to the account.
2. Pair a device: scan the QR for WhatsApp or paste your Telegram bot token.
3. Create a contact database or import contacts from CSV, Excel, or Google Sheets.
4. Build a workflow (outbound) or an agent (inbound) and assign it to the device.
5. Launch it and monitor delivery and replies from the dashboard.

For outbound automation, generate an API token for your workflow and trigger it from your app, from Zapier, or from ChatGPT. For inbound, the agent is active as soon as the device is connected.

Devices

A device is the account Vext uses to send and receive messages. Each device is either a WhatsApp account (personal or Business API) or a Telegram bot.

• Pairing — scan the QR code for WhatsApp, or paste the bot token for Telegram. Pairing keeps the session alive until you disconnect.
• Status — connected, disconnected, or under maintenance. Disconnected devices can be re-paired at any time.
• Credit guard — devices automatically pause when the workspace runs out of credits and resume when credits are added.
• Start / stop — devices can be stopped manually for maintenance and restarted on demand.

Contacts and databases

Contacts live in named databases inside your workspace. You can have separate databases for different campaigns, segments, or clients.

How contacts get into Vext

• CSV — upload a file; the delimiter (comma, semicolon, tab) is detected automatically.
• Excel (.xlsx) — native upload with column mapping.
• Google Sheets — paste a sheet URL to sync contacts live.
• CRM sync — pulled automatically from HubSpot, GoHighLevel, or Zoho when connected.
• Contact form — lead-capture form you can embed on a landing page.
• Agent or API — created during a conversation or pushed from your app.

Each contact stores name, phone, email, notes, and any custom fields imported from the source.

Workflows

A workflow is a repeatable outbound automation. You pick who it messages, what it sends, and what triggers it.

Trigger types

API

Fire the workflow with an HTTP request. Used for custom apps, backend systems, and in-house scripts.

Zapier

Trigger from any Zapier automation by sending the Zap to the workflow's webhook URL.

ChatGPT

Connect Vext to ChatGPT as a custom action so the assistant can create workflows, launch them, or add contacts on your behalf.

MCP

Expose workflows to any MCP-compatible AI tool or assistant, which can list and trigger them.

Excel / CSV batch

Upload a list of contacts and the workflow runs through the batch respecting send windows and pacing.

CRM event

Triggered by events from connected CRMs (new contact, new deal, stage change).

Inbound message

Run a workflow when a specific message pattern arrives on a connected channel.

Modes

• Instant — dispatch as soon as the trigger fires (subject to send windows).
• Scheduled — run at a specific date and time.
• Recurring — run on a defined cadence while the schedule stays active.

Agents

Agents are AI responders that read incoming messages on a connected device and reply automatically. They can hold a conversation, remember context, and perform actions when the conversation calls for it.

What you configure

• Instructions — the persona, tone, and rules the agent must follow.
• Knowledge — background info the agent can draw from (FAQs, policies, product details).
• Model — defaults to a fast cost-effective model; switchable to stronger models when quality matters.
• Answer mode — reply to every message, or only when intent matches.
• Working hours — timezone, days of the week, time windows, and weekend behavior.
• Actions — which actions the agent is allowed to perform (see below).
• Conversation history — optionally persist chat history for review and export.

Actions

Actions are the things your agents and workflows can do beyond sending a plain reply. Enable the ones you need per agent or workflow.

Reply to chat

Send a WhatsApp or Telegram message to the contact.

Send email

Deliver an email with subject and body to the contact or to your team.

Update CRM

Create or update a contact, add a note, or move a deal to a new stage in HubSpot, GoHighLevel, or Zoho.

Save contact

Create or update a contact in a Vext contact database.

Book appointment

Create a Google Calendar event with date, time, duration, and description.

Add to sheet

Append a row to a Google Sheet — useful for lead capture and reporting.

Schedule follow-up

Send a message later (e.g. in 30 minutes, tomorrow, or on a specific date).

Escalate to human

Hand the conversation over to a human operator and stop automated replies.

Call API

Fire a webhook to your own system with a summary of the conversation and the collected data.

Integrations

Integrations bring data into Vext and push updates back out. All integrations use secure OAuth where possible, and connections can be revoked at any time from the dashboard.

CRM

HubSpot

Sync contacts both ways, create and update deals, add notes to records, and move deals through stages. Workflows can be triggered by HubSpot events.

GoHighLevel

Manage contacts and opportunities, add notes, and update stages. Webhook support lets GHL events trigger Vext workflows.

Zoho CRM

Upsert contacts and deals, attach notes, and update custom fields.

Google

Google Calendar

Agents and workflows can create events with title, description, date, time, and duration. Ideal for appointment booking flows.

Google Sheets

Append rows with contact data and conversation outcomes. Also usable as a live source of contacts for workflows.

Automation platforms

Zapier

Trigger any Vext workflow from a Zap. Use the workflow's webhook URL in a Webhooks-by-Zapier step, or in any Zap action that supports custom webhooks.

ChatGPT

Connect Vext as a ChatGPT action so the assistant can list your devices, create workflows, launch them, manage contact databases, and save contacts — all from chat.

MCP

Any MCP-compatible AI tool can list your MCP-enabled workflows and trigger them for a given phone number.

Webhooks

Any system that can send an HTTP POST can trigger a workflow via its webhook URL.

Scheduler and send windows

Vext paces messages instead of blasting them out. You define send windows per workspace, and workflows and agents respect them automatically.

• Timezone — pick the timezone the schedule follows.
• Days of week — choose which days messages may be sent.
• Time windows — set one or more time ranges (e.g. 09:00–13:00 and 15:00–18:00).
• Date range — optional start and end dates.
• Specific day of month — optional for monthly recurring sends.
• Weekend override — allow or block weekend sends.

Messages that arrive outside the window are held and dispatched at the next valid start. Messages inside the window are still paced to keep delivery behavior natural.

Credits and billing

Vext runs on credits. Credits are consumed when the platform does actual work on your behalf.

• Messages sent on your connected channels
• Agent replies (AI-generated responses)
• CRM operations (contact and deal updates, notes)
• Google Calendar events and Google Sheets rows
• Outbound emails
• Workflow triggers from API, Zapier, and MCP

If the workspace runs out of credits, devices pause automatically and resume once credits are added. Every action is recorded in the usage ledger, so you can review exactly what was spent and when.

Contact forms

Each workspace can publish a hosted contact form for lead capture. Submissions create or update a contact in the chosen database and can trigger a workflow or start an agent conversation.

Public API

The public API lets you trigger workflows and check delivery status from your own code. Authenticate with a bearer token generated for the workflow or trigger.

Core endpoints

POST /api/v1/triggers/events

Fire a workflow with a contact and message payload.

POST /api/v1/send

Backward-compatible alias of the trigger endpoint.

GET /api/v1/messages/:id

Check the delivery status of a submitted message.

Trigger a workflow

Fields: phone (or to), optional name, message, channel, device_id, trigger_type, metadata.

curl -X POST https://vext.chat/api/v1/triggers/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+391234567890",
    "name": "Mario Rossi",
    "message": "Hi Mario, your appointment is confirmed for tomorrow.",
    "channel": "whatsapp",
    "trigger_type": "appointment_reminder",
    "metadata": {
      "crm_id": "contact_123",
      "campaign": "spring-reminders"
    }
  }'

Check message status

curl -X GET https://vext.chat/api/v1/messages/MESSAGE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

ChatGPT-scoped endpoints

These endpoints are designed for the ChatGPT integration but are usable directly with a ChatGPT-scoped token.

GET /api/v1/chatgpt/workspace

Summary of your workspace (credits, plan, counts).

GET /api/v1/chatgpt/devices

List paired devices.

GET /api/v1/chatgpt/workflows

List workflows.

POST /api/v1/chatgpt/workflows/instant

Create an instant workflow from chat.

POST /api/v1/chatgpt/workflows/:id/launch

Activate a workflow.

GET /api/v1/chatgpt/databases

List contact databases.

POST /api/v1/chatgpt/databases

Create a contact database.

POST /api/v1/chatgpt/databases/:id/contacts

Add a contact to a database.

MCP server

Vext exposes an MCP server at /api/v1/mcp so any MCP-compatible AI client (Claude Desktop, MCP Inspector, custom clients) can discover and trigger your workflows. Authenticate with an MCP-scoped bearer token.

Available tools

list_mcp_workflows

Returns the MCP-enabled workflows in the workspace.

trigger_workflow

Run a workflow for a given phone number, with an optional custom message.

Initialize the session

curl -X POST https://vext.chat/api/v1/mcp \
  -H "Authorization: Bearer YOUR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

Call a tool

curl -X POST https://vext.chat/api/v1/mcp \
  -H "Authorization: Bearer YOUR_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "trigger_workflow",
      "arguments": {
        "workflow_id": "WORKFLOW_ID",
        "phone": "+391234567890",
        "message": "Hello from an MCP client"
      }
    }
  }'

Limits

Public API routes

300 req/min per IP

Browser routes

120 req/min per IP

ChatGPT-scoped API

60 req/min

message field

≤ 4096 chars

Accepted requests may still be delayed by pacing, send windows, daily limits, or missing credits. Accepted never means instantly delivered.

Platform rules

Vext does not allow spam, illegal activity, abusive messaging, deceptive behavior, or misuse of automations, agents, APIs, or integrations.

Prohibited

• Unsolicited spam or bulk abuse
• Illegal, fraudulent, or harmful use
• Harassment, phishing, impersonation, or deceptive content
• Attempts to evade platform safeguards or policy enforcement

Suspicious activity may be reviewed. Violating accounts may be restricted, suspended, or banned. Read the Acceptable Use Policy.

Response codes

202

Accepted for processing.

401

Bearer token missing, invalid, or expired.

402

Workspace does not have enough credits.

403

Workflow not active or execution not allowed.

422

Invalid payload.

429

Rate limit exceeded.

503

Workflow could not be dispatched right now.

FAQ