CONNECT APP
Build with VirtualSMS
Security
- API key
MCP
Give your agent VirtualSMS tools
Every VirtualSMS action is exposed as an MCP tool on Pipedream's remote server. Point a client at it with your end user's ID and Connect resolves that user's VirtualSMS account for each tool call — you store no tokens.
// accessToken: mint a short-lived token with the Connect SDK — see the MCP guide
const transport = new StreamableHTTPClientTransport(
new URL("https://remote.mcp.pipedream.net/v3"),
{
requestInit: {
headers: {
Authorization: `Bearer ${accessToken}`,
"x-pd-project-id": "{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",
},
})# access_token: mint a short-lived token with the Connect SDK — see the MCP guide
headers = {
"Authorization": f"Bearer {access_token}",
"x-pd-project-id": "{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",
}
async with streamablehttp_client("https://remote.mcp.pipedream.net/v3", headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
# e.g. run Cancel Rental:
result = await session.call_tool("virtualsms-cancel-rental", {
"orderId": "Order ID",
})API PROXY
Call the VirtualSMS API directly
For an endpoint with no pre-built tool, the Connect proxy forwards your request to the VirtualSMS API with the connected user's credentials attached. You store no tokens and write no refresh logic.
const resp = await pd.proxy.get({
externalUserId: "{external_user_id}", // any stable ID for this user in your system
accountId: "apn_xxxxxxx",
url: "https://virtualsms.io/api/v1/customer/balance",
})
// Any allowed VirtualSMS endpoint works here. Pipedream attaches the
// connected account's credentials to the outgoing request.# 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"SDK
Run VirtualSMS actions from your backend
Connect a user's VirtualSMS account once, then run Cancel Rental on their behalf from your own code — TypeScript, Python, or plain HTTP.
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",
},
})from pipedream import Pipedream
pd = Pipedream(
client_id="{oauth_client_id}",
client_secret="{oauth_client_secret}",
project_id="{project_id}",
project_environment="production",
)
result = pd.actions.run(
id="virtualsms-cancel-rental",
external_user_id="{external_user_id}", # any stable ID for this user in your system
configured_props={
"virtualsms": {"authProvisionId": "apn_xxxxxxx"},
"orderId": "Order ID",
},
)curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
-H "Content-Type: application/json" \
-H "X-PD-Environment: production" \
-H "Authorization: Bearer {access_token}" \
-d '{
"external_user_id": "{external_user_id}",
"id": "virtualsms-cancel-rental",
"configured_props": {
"virtualsms": { "authProvisionId": "apn_xxxxxxx" },
"orderId": "Order ID"
}
}'TOOLS
VirtualSMS actions
On-demand operations your product or agent can configure and run on behalf of a connected user.
-
Cancel Rental
actionCancel 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 documentationWritev0.0.2 -
Check Messages
actionPoll an active rental for any SMS messages received so far. Returns the current order state, including amessagesarray (each item hassender,content,received_at) when one or more SMS have arrived. For event-driven workflows prefer the New SMS Received trigger. See the documentationRead-onlyv0.0.2 -
Get Balance
actionRetrieve the current account balance in USD. Useful for low-balance alerts or pre-flight checks before renting numbers. See the documentationRead-onlyv0.0.1 -
List Countries
actionList all supported countries with current stock indicators (available_phones,total_phones). Use the returnedcountry_id(ISO-3166-1 alpha-2) when calling Rent Number. See the documentationRead-onlyv0.0.2 -
List Country Options
actionRetrieves available options for the Country field.Read-onlyv0.0.1 -
List Order ID Options
actionRetrieves available options for the Order ID field.Read-onlyv0.0.1 -
List Services
actionList all supported services (700+) with their service codes, categories, and base prices. Use the returnedservice_id(orcode) when calling Rent Number. See the documentationRead-onlyv0.0.2 -
Rent Number
actionRent 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 documentationWritev0.0.2
EVENTS
VirtualSMS triggers
Event sources your backend can deploy for users and receive through a webhook.
- App slug
- virtualsms
- Authentication
- API key
- Categories
- Security
- Actions
- 8
- Triggers
- 1
- API proxy
- Available