Developer Platform

Build on VirtualText

RESTful API, real-time webhooks, and conversation intelligence — everything you need to integrate VirtualText into your stack.

Get API Key Read the Docs

terminal

 $ curl -X POST https://api.virtualpbx.com/v1/messages \

  -H "Authorization: Bearer pk_live_..." \

  -H "Content-Type: application/json" \

  -d '{"to": "+15551234567", "body": "Hello!"}'
 
 // 201 Created
 { "id": "msg_01HZ3...", "status": "queued" }

99.9%

API Uptime

<50ms

Avg Response

40+

Endpoints

Everything you need to integrate

Four core APIs that cover messaging, contacts, AI, and real-time events.

Messages API

Send and receive SMS, MMS, and webchat messages programmatically. Delivery status callbacks in real time.

POST /v1/messages GET /v1/messages/:id

Contacts API

Create, update, and search contacts. Access conversation history, sentiment data, and AI observations.

GET /v1/contacts POST /v1/contacts

AI Agents API

Configure agents, manage playbooks, and trigger actions. Let AI handle conversations from your own interface.

GET /v1/agents POST /v1/agents/:id/trigger

Webhooks

Real-time event notifications for messages, conversations, sentiment changes, and agent handoffs.

POST /v1/webhooks GET /v1/webhooks/:id/deliveries

Ship faster with clean APIs

Simple, RESTful endpoints that do what you'd expect. No SDK required — just HTTP requests from any language.

JSON in, JSON out

Standard REST conventions. No XML, no SOAP, no surprises.

Idempotent by design

Safe to retry. Every mutating endpoint supports idempotency keys.

Consistent error format

Structured error responses with codes, messages, and field-level details.

  // POST /v1/messages POST https://api.virtualpbx.com/v1/messages Authorization: Bearer pk_live_abc123...
Content-Type: application/json

{
"to": "+15551234567",
"channel": "sms",
"body": "Your appointment is confirmed for tomorrow at 2pm.",
"idempotency_key": "appt-confirm-9x7k"
}
// Response: 201 Created
{
"id": "msg_01HZ3...",
"status": "queued",
"created_at": "2026-04-10T14:30:00Z"
}
 

  // GET /v1/conversations GET https://api.virtualpbx.com/v1/conversations?status=active&limit=20 Authorization: Bearer pk_live_abc123...
// Response: 200 OK
{
"data": [
    {
"id": "conv_01HZ4...",
"contact": {
"id": "ct_01HZ2...",
"name": "Sarah Chen",
"phone": "+15551234567"
},
"last_message_at": "2026-04-10T14:28:00Z",
"sentiment": "positive",
"assigned_to": "agent_ai"
}
  ],
"has_more": true
}
 

  // POST /v1/webhooks POST https://api.virtualpbx.com/v1/webhooks Authorization: Bearer pk_live_abc123...
Content-Type: application/json

{
"url": "https://yourapp.com/webhooks/virtualpbx",
"events": [
"message.received",
"conversation.handoff",
"sentiment.changed"
],
"secret": "whsec_your_signing_secret"
}
// Response: 201 Created
{
"id": "wh_01HZ5...",
"status": "active"
}
 

Up and running in minutes

Three steps from sign-up to your first API call.

Create an account

Make your first call

Use the sandbox to send a test message. No phone number provisioning needed — the sandbox handles it all.

Go live

Swap your sandbox key for a production key and start sending real messages. Same endpoints, same code, zero changes.

webhook payload


{
"id": "evt_01HZ6Q...",
"type": "message.received",
"created_at": "2026-04-10T14:32:11Z",
"data": {
"message_id": "msg_01HZ6R...",
"contact": {
"id": "ct_01HZ2...",
"name": "Sarah Chen",
"phone": "+15551234567"
},
"body": "Can I reschedule to 3pm instead?",
"channel": "sms",
"conversation_id": "conv_01HZ4..."
}
}

Real-time events, delivered instantly

Subscribe to the events that matter. VirtualText sends webhook payloads the moment something happens — new messages, sentiment shifts, agent handoffs, conversation closures.

message.receivedFired when a new inbound message arrives

message.sentFired when an outbound message is delivered

conversation.handoffFired when AI escalates to a human

sentiment.changedFired when contact sentiment shifts

contact.createdFired when a new contact is added

What you can build

The VirtualText API is the foundation for whatever your business needs.

Custom Dashboards

Pull conversation data, sentiment trends, and agent performance into your own analytics tools.

Analytics Reporting BI Tools

CRM Sync

Sync contacts and conversation history with Salesforce, HubSpot, or your custom CRM. Keep everything in sync automatically.

Salesforce HubSpot Custom CRM

Workflow Automation

Trigger actions in VirtualText from your existing tools — Zapier, Make, n8n, or direct API calls.

Zapier Make n8n

Built for developers

Everything you need to go from zero to production, fast.

API Key Auth

Simple bearer token authentication. Generate and rotate keys from your dashboard.

Scoped permissions · Key rotation · Multiple keys per account

Comprehensive Docs

Every endpoint documented with request/response examples, error codes, and rate limits.

OpenAPI spec · Try-it-live console · Copy-paste examples

Sandbox Environment

Test your integration without affecting live data. Full API parity with production.

Test phone numbers · Simulated webhooks · Seed data included

Developer Support

Stuck? Our engineering team responds to API questions directly. No ticket queues.

Avg response <2 hours · Dedicated Slack channel for Pro plans

Developer FAQ

What authentication does the API use?

VirtualText uses Bearer token authentication. Generate API keys from your account dashboard. Keys can be scoped to specific permissions and rotated at any time.

Is there a rate limit?

Yes. The standard rate limit is 100 requests per second per API key. If you need higher throughput, contact our team to discuss enterprise limits.

Do I need an SDK?

No. VirtualText's API is standard REST with JSON payloads — you can use it from any language with HTTP support. That said, we're working on official SDKs for Python, Node.js, and Ruby.

How do webhooks handle failures?

VirtualText retries failed webhook deliveries with exponential backoff — up to 5 attempts over 24 hours. Each delivery includes a signature header so you can verify authenticity.

Can I use the API to send messages on behalf of users?

Yes. The Messages API lets you send SMS, MMS, and webchat messages programmatically. Messages appear in the unified inbox alongside manually sent ones.