TwilioRpc

TwilioRpc exposes RPC endpoints for finding Twilio phone numbers, purchasing a number, and releasing an assigned number. The methods delegate the actual telephony and channel-management work to TwilioService, and some operations rely on the current request context for tenant-scoped behavior.

Endpoints

POST /api/rpc (Method: TwilioRpc.searchNumbers)

Searches for available phone numbers to purchase.

The service first searches the local phone-number inventory and then falls back to Twilio’s available-number listings. Results may include numbers from either source, with pricing and capability information normalized for the client.

Request Body:

{
  "method": "TwilioRpc.searchNumbers",
  "params": {
    "countryCode": "US",
    "areaCode": "212",
    "capabilities": ["sms", "voice"]
  }
}

Parameters:

Response:

{
  "success": true,
  "data": [
    {
      "phoneNumber": "+12125550123",
      "friendlyName": "+12125550123",
      "region": "New York",
      "locality": "New York",
      "capabilities": ["sms", "voice"],
      "source": "provider",
      "pricing": {
        "monthlyPrice": 1.25,
        "priceUnit": "USD"
      }
    }
  ]
}

The returned array may contain entries from the local inventory or from Twilio. Inventory-sourced entries include source: "inventory" and a pricing object populated from stored inventory costs. Provider-sourced entries include source: "provider" and pricing derived from Twilio pricing plus the configured markup.

Example (cURL):

curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "TwilioRpc.searchNumbers",
    "params": {
      "countryCode": "US",
      "areaCode": "212",
      "capabilities": ["sms", "voice"]
    }
  }'

POST /api/rpc (Method: TwilioRpc.purchaseNumber)

Purchases a new phone number and creates its channel configuration.

This method reserves billing funds, assigns the number either from local inventory or from Twilio, creates a channel configuration through ChannelManagerService, and attempts to configure Twilio webhooks for inbound SMS and voice traffic.

Request Body:

{
  "method": "TwilioRpc.purchaseNumber",
  "params": {
    "phoneNumber": "+12125550123",
    "friendlyName": "Support Line",
    "inboundSmsWorkflowId": null,
    "inboundVoiceWorkflowId": null
  }
}

Parameters:

Response:

{
  "success": true,
  "data": {
    "success": true,
    "config": {
      "_id": "66cfa5f6e1f2d3a4b5c6d7e8"
    }
  }
}

The returned payload contains a success flag and a config object from the created channel configuration. If billing reservation fails, if the number cannot be acquired, or if channel creation fails, the method throws an error instead of returning a success payload.

The method uses the request context for tenant-scoped work, including subscriptionId and serviceCode.

Example (cURL):

curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "TwilioRpc.purchaseNumber",
    "params": {
      "phoneNumber": "+12125550123",
      "friendlyName": "Support Line",
      "inboundSmsWorkflowId": null,
      "inboundVoiceWorkflowId": null
    }
  }'

POST /api/rpc (Method: TwilioRpc.releaseNumber)

Releases a purchased phone number.

This method validates that the channel configuration belongs to the current subscription, marks any matching inventory record as available, clears the Twilio webhook for the number when applicable, and deletes the associated channel configuration.

Request Body:

{
  "method": "TwilioRpc.releaseNumber",
  "params": {
    "configId": "66cfa5f6e1f2d3a4b5c6d7e8"
  }
}

Parameters:

Response:

{
  "success": true,
  "data": {
    "success": true
  }
}

If the configuration is not found or does not belong to the current subscription, the method throws an access error. The method uses the request context to enforce subscription scoping.

Example (cURL):

curl -X POST "${APP_BASE_URL}/api/rpc" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "TwilioRpc.releaseNumber",
    "params": {
      "configId": "66cfa5f6e1f2d3a4b5c6d7e8"
    }
  }'