# VirtualSMS — Pipedream Connect

> Real carrier SIMs from 145+ countries

- API slug: `virtualsms` (use in MCP headers and tool keys)
- Auth: API key (Pipedream-managed)
- Categories: Security
- Website: https://virtualsms.io
- This page (HTML): https://pipedream.com/apps/virtualsms
- Tools: 8 actions · 1 trigger

## Connect via MCP (recommended)

- Endpoint: `https://remote.mcp.pipedream.net/v3`
- Headers: `Authorization: Bearer <token>` · `x-pd-project-id` · `x-pd-environment` · `x-pd-external-user-id` · `x-pd-app-slug: virtualsms`

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "virtualsms",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// e.g. run Cancel Rental:
const result = await mcp.callTool({
  name: "virtualsms-cancel-rental",
  arguments: {
    orderId: "Order ID",
  },
})
```

Docs: [MCP guide](https://pipedream.com/docs/connect/mcp/developers.md)

## API proxy

For a VirtualSMS endpoint with no pre-built tool, the proxy forwards your request with the connected user's credentials attached.

```bash
# The path segment is the target URL, URL-safe base64 encoded:
# https://virtualsms.io/api/v1/customer/balance

curl "https://api.pipedream.com/v1/connect/{project_id}/proxy/aHR0cHM6Ly92aXJ0dWFsc21zLmlvL2FwaS92MS9jdXN0b21lci9iYWxhbmNl?external_user_id={external_user_id}&account_id=apn_xxxxxxx" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-pd-environment: production"
```

Docs: [API proxy guide](https://pipedream.com/docs/connect/api-proxy.md)

## SDK

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "virtualsms-cancel-rental",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    virtualsms: { authProvisionId: "apn_xxxxxxx" },
    orderId: "Order ID",
  },
})
```

Docs: [Managed auth guide](https://pipedream.com/docs/connect/managed-auth/quickstart.md) · [Tools guide](https://pipedream.com/docs/connect/components.md)

## Actions (8)

### `virtualsms-cancel-rental` — Cancel Rental (Write)

Cancel an active rental and refund any unused balance. Cancellation is only possible while the rental is still active and no SMS has been received (or the cancellation policy permits a refund). See the documentation

Full schema: https://pipedream.com/apps/virtualsms/actions/cancel-rental.md

### `virtualsms-check-messages` — Check Messages (Read-only)

Poll an active rental for any SMS messages received so far. Returns the current order state, including a messages array (each item has sender, content, received_at) when one or more SMS have arrived. For event-driven workflows prefer the New SMS Received trigger. See the documentation

Full schema: https://pipedream.com/apps/virtualsms/actions/check-messages.md

### `virtualsms-get-balance` — Get Balance (Read-only)

Retrieve the current account balance in USD. Useful for low-balance alerts or pre-flight checks before renting numbers. See the documentation

Full schema: https://pipedream.com/apps/virtualsms/actions/get-balance.md

### `virtualsms-list-countries` — List Countries (Read-only)

List all supported countries with current stock indicators (available_phones, total_phones). Use the returned country_id (ISO-3166-1 alpha-2) when calling Rent Number. See the documentation

Full schema: https://pipedream.com/apps/virtualsms/actions/list-countries.md

### `virtualsms-list-country-options` — List Country Options (Read-only)

Retrieves available options for the Country field.

Full schema: https://pipedream.com/apps/virtualsms/actions/list-country-options.md

### `virtualsms-list-order-id-options` — List Order ID Options (Read-only)

Retrieves available options for the Order ID field.

Full schema: https://pipedream.com/apps/virtualsms/actions/list-order-id-options.md

### `virtualsms-list-services` — List Services (Read-only)

List all supported services (700+) with their service codes, categories, and base prices. Use the returned service_id (or code) when calling Rent Number. See the documentation

Full schema: https://pipedream.com/apps/virtualsms/actions/list-services.md

### `virtualsms-rent-number` — Rent Number (Write)

Rent a real-SIM virtual phone number to receive an SMS verification code. Returns the order ID and assigned phone number — pair this with the New SMS Received trigger or the Check Messages action to retrieve the code. See the documentation

Full schema: https://pipedream.com/apps/virtualsms/actions/rent-number.md

## Triggers (1)

### `virtualsms-new-sms-received` — New SMS Received (Polling)

Emit new event for each SMS message received on any of your active rentals. Polls the VirtualSMS API on the configured interval (default 60s) and de-duplicates so each SMS is emitted exactly once. See the documentation

Full schema: https://pipedream.com/apps/virtualsms/triggers/new-sms-received.md

---

- All apps: https://pipedream.com/apps — index: https://pipedream.com/llms.txt
- Pipedream docs for agents: https://pipedream.com/docs/llms.txt