SignalWire Shell (swsh) API Documentation 🔗 ↑ TOC

Overview 🔗 ↑ TOC

SignalWire Shell (swsh) is a command-line interface for managing SignalWire telecommunication services. This document provides comprehensive documentation for all available API functions and CLI commands.

Table of Contents 🔗 ↑ TOC

1. API Functions
2. CLI Commands
3. Environment Setup
4. Usage Examples

API Functions 🔗 ↑ TOC

Core HTTP Functions 🔗 ↑ TOC

http_request(signalwire_space, project_id, rest_api_token, destination, req_type, payload={}, headers={}, url="", query_params="") 🔗 ↑ TOC

Base HTTP request function used by all other API functions.

• Parameters:
• signalwire_space: Your SignalWire space name
• project_id: Your project ID
• rest_api_token: Your REST API token
• destination: API endpoint path
• req_type: HTTP method (GET, POST, PUT, DELETE)
• payload: Request body (optional)
• headers: HTTP headers (optional)
• url: Base URL (optional, defaults to relay/rest API)
• query_params: Query string parameters (optional)
• Returns: HTTP response object

Resource-Specific API Functions 🔗 ↑ TOC

Phone Numbers 🔗 ↑ TOC

phone_number_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /phone_numbers - Description: Manage phone numbers in your project - Methods: GET (list/retrieve), POST (create), PUT (update), DELETE (release)

phone_number_lookup(query_params) - Endpoint: /lookup/phone_number/{number} - Description: Look up information about a phone number

SIP Endpoints 🔗 ↑ TOC

sip_endpoint_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /endpoints/sip - Description: Manage SIP endpoints - Methods: GET, POST, PUT, DELETE

SIP Profiles 🔗 ↑ TOC

sip_profile_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /sip_profile - Description: Manage SIP profile settings - Methods: GET, PUT

LaML Bins 🔗 ↑ TOC

laml_bin_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /Accounts/{project_id}/LamlBins (Compatibility API) - Description: Manage LaML XML response templates - Methods: GET, POST, PUT, DELETE

LaML Applications 🔗 ↑ TOC

laml_app_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /Accounts/{project_id}/Applications (Compatibility API) - Description: Manage LaML applications - Methods: GET, POST, PUT, DELETE

Domain Applications 🔗 ↑ TOC

domain_application_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /domain_applications - Description: Manage domain applications for SIP - Methods: GET, POST, PUT, DELETE

Number Groups 🔗 ↑ TOC

number_group_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /number_groups - Description: Manage number groups for organization - Methods: GET, POST, PUT, DELETE

FIFO Queues 🔗 ↑ TOC

fifo_queue_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /Accounts/{project_id}/Queues (Compatibility API) - Description: Manage FIFO call queues - Methods: GET, POST, PUT, DELETE

Faxes 🔗 ↑ TOC

fax_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /Accounts/{project_id}/Faxes (Compatibility API) - Description: Manage fax operations - Methods: GET, POST, PUT, DELETE

Calls 🔗 ↑ TOC

call_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /Accounts/{project_id}/Calls (Compatibility API) - Description: Manage voice calls - Methods: GET, POST

Projects 🔗 ↑ TOC

project_func(query_params="", req_type="GET", headers={}, payload={}) - Endpoint: /Accounts (Compatibility API) - Description: Manage projects/subprojects - Methods: GET, POST

Utility Functions 🔗 ↑ TOC

get_environment() 🔗 ↑ TOC

• Returns: Tuple of (signalwire_space, project_id, rest_api_token) from environment

validate_signalwire_creds(signalwire_space, project_id, rest_api_token) 🔗 ↑ TOC

• Returns: Boolean indicating if credentials are valid

encode_auth(project_id, rest_api_token) 🔗 ↑ TOC

• Returns: Base64 encoded authentication string

validate_http(status_code) 🔗 ↑ TOC

• Returns: Boolean indicating if HTTP status code is successful (2xx)

validate_json(output) 🔗 ↑ TOC

• Returns: Boolean indicating if string is valid JSON

json_nice_print(j) 🔗 ↑ TOC

• Description: Pretty prints JSON output

Shell Variable Functions 🔗 ↑ TOC

• set_shell_env(var): Set a shell variable (format: KEY=value)
• get_shell_env(var): Get a shell variable value
• get_shell_env_all(): Display all shell variables
• is_env_var(args): Replace $VARIABLE references in arguments

CLI Commands 🔗 ↑ TOC

SIP Endpoint Commands 🔗 ↑ TOC

Manage SIP endpoints for VoIP connectivity.

sip_endpoint list 🔗 ↑ TOC

sip_endpoint list [-i ID] [-j] [-n NAME]

• -i, --id: List specific endpoint by ID
• -j, --json: Output in JSON format
• -n, --name: Search by username

sip_endpoint create 🔗 ↑ TOC

sip_endpoint create -u USERNAME -p PASSWORD -s SEND_AS -n CALLER_ID [OPTIONS]

• -u, --username: SIP username (required)
• -p, --password: SIP password (required)
• -s, --send-as: Default outbound number (required)
• -n, --caller-id: Friendly caller ID name (required)
• -e, --encryption: Encryption setting (default/required/optional)
• --codecs: Supported codecs (OPUS, G722, PCMU, PCMA, VP8, H264)
• --ciphers: Encryption ciphers

sip_endpoint update 🔗 ↑ TOC

sip_endpoint update -i ID [OPTIONS]

• -i, --id: Endpoint ID to update (required)
• All create options available as optional parameters

sip_endpoint delete 🔗 ↑ TOC

sip_endpoint delete -i ID [-f]

• -i, --id: Endpoint ID to delete (required)
• -f, --force: Skip confirmation

Phone Number Commands 🔗 ↑ TOC

Manage phone numbers in your SignalWire project.

phone_number list 🔗 ↑ TOC

phone_number list [-j] [-n NAME] [-i ID] [-N NUMBER]

• -j, --json: JSON output
• -n, --name: Filter by name
• -i, --id: Get specific number by ID
• -N, --number: Get specific number by E.164 format

phone_number update 🔗 ↑ TOC

phone_number update [-i ID | -N NUMBER] [OPTIONS]

• -i, --id or -N, --number: Identify number (one required)
• -n, --name: Update friendly name

• Call handler options:

• --call-handler: Handler type (relay_context, laml_webhooks, etc.)

• --call-receive-mode: voice or fax
• --call-request-url: Webhook URL
• --call-request-method: POST or GET
• --call-fallback-url: Fallback webhook
• --call-laml-application-id: LaML app ID
• --call-relay-context: Relay context name
• --call-sip-endpoint-id: SIP endpoint ID

• Message handler options:

• --message-handler: Handler type

• --message-request-url: SMS webhook URL
• --message-request-method: POST or GET
• --message-laml-application-id: LaML app ID
• --message-relay-context: Relay context name

phone_number release 🔗 ↑ TOC

phone_number release [-i ID | -n NUMBER] [-f]

• -i, --id or -n, --number: Identify number (one required)
• -f, --force: Skip confirmation

phone_number lookup 🔗 ↑ TOC

phone_number lookup --number NUMBER [--cnam] [--carrier]

• --number: Phone number in E.164 format (required)
• --cnam: Include CNAM lookup
• --carrier: Include carrier information

phone_number buy 🔗 ↑ TOC

Interactive wizard to purchase new phone numbers.

LaML Bin Commands 🔗 ↑ TOC

Manage LaML XML response templates.

laml_bin list 🔗 ↑ TOC

laml_bin list [-n NAME] [-i ID] [-j]

laml_bin create 🔗 ↑ TOC

laml_bin create -n NAME [--contents CONTENTS]

• -n, --name: Bin name (required)
• --contents: XML contents (opens editor if not provided)

laml_bin update 🔗 ↑ TOC

laml_bin update -i ID [-n NAME] [--contents CONTENTS]

laml_bin delete 🔗 ↑ TOC

laml_bin delete -i ID [-f]

LaML Application Commands 🔗 ↑ TOC

Manage LaML applications for handling calls and messages.

laml_app list 🔗 ↑ TOC

laml_app list [-i ID] [-j]

laml_app create 🔗 ↑ TOC

laml_app create -n NAME [OPTIONS]

• -n, --name: Application name (required)

• Voice options:

• --voice-url: Voice webhook URL

• --voice-method: POST or GET
• --voice-fallback-url: Fallback URL
• --voice-caller-id-lookup: true or false

• SMS options:

• --sms-url: SMS webhook URL

• --sms-method: POST or GET
• --sms-fallback-url: Fallback URL

• Status callbacks:

• --status-callback: General status URL

• --message-status-callback: Message status URL
• --sms-status-callback: SMS status URL

laml_app update 🔗 ↑ TOC

laml_app update -i ID [OPTIONS]

laml_app delete 🔗 ↑ TOC

laml_app delete -i ID [-f]

Communication Commands 🔗 ↑ TOC

send_call 🔗 ↑ TOC

send_call -f FROM_NUM -t TO_NUM [-u URL | --laml-bin-id ID]

• -f, --from-num: Your SignalWire number (required)
• -t, --to-num: Destination number (required)
• -u, --url: Webhook URL or --laml-bin-id: LaML Bin ID

send_text 🔗 ↑ TOC

send_text -f FROM_NUM -t TO_NUM -b TEXT_BODY

• -f, --from-num: Your number (must be campaign registered)
• -t, --to-num: Recipient number
• -b, --text-body: Message content

fax send 🔗 ↑ TOC

fax send --to_num TO_NUM --from_num FROM_NUM -m MEDIA_URL [-b]

• --to_num: Destination fax number
• --from_num: Your fax-enabled number
• -m, --media-url: URL to PDF document
• -b, --background: Send without waiting for result

Additional Commands 🔗 ↑ TOC

Domain Applications 🔗 ↑ TOC

domain_application list [-d DOMAIN] [-n NAME] [-i ID] [-j]
domain_application create -n NAME --identifier IDENTIFIER --call-handler HANDLER [OPTIONS]
domain_application update -i ID [OPTIONS]
domain_application delete -i ID

Number Groups 🔗 ↑ TOC

number_group list [-n NAME] [-i ID] [-j]
number_group create -n NAME [-s STICKY_SENDER]
number_group update -i ID [-n NAME] [-s STICKY_SENDER]
number_group delete -i ID [-f]

FIFO Queues 🔗 ↑ TOC

fifo_queue list [-i ID] [-j]
fifo_queue create -n NAME [-m MAXSIZE]
fifo_queue update -i ID -n NAME [-m MAXSIZE]
fifo_queue delete -i ID [-f]

Space Management 🔗 ↑ TOC

space cd -n HOSTNAME -t TOKEN -p PROJECT_ID
space show [-t]
project list [-n NAME] [-i ID] [-j]
project create -n NAME
project update -i ID -n NAME

Environment Setup 🔗 ↑ TOC

Required Environment Variables 🔗 ↑ TOC

# Linux/macOS
export SIGNALWIRE_SPACE=your-space-name
export PROJECT_ID=your-project-id
export REST_API_TOKEN=your-api-token

# Windows
setx SIGNALWIRE_SPACE your-space-name
setx PROJECT_ID your-project-id
setx REST_API_TOKEN your-api-token

Shell Variables 🔗 ↑ TOC

Set temporary variables within swsh:

swsh> VAR_NAME=value
swsh> echo $VAR_NAME

Usage Examples 🔗 ↑ TOC

Basic Phone Number Management 🔗 ↑ TOC

# List all phone numbers
swsh> phone_number list

# Update number to use webhook
swsh> phone_number update -N +15551234567 --call-handler laml_webhooks \
      --call-request-url https://example.com/voice

# Look up number info
swsh> phone_number lookup --number +15551234567 --carrier --cnam

SIP Endpoint Setup 🔗 ↑ TOC

# Create SIP endpoint
swsh> sip_endpoint create -u john.doe -p SecurePass123 \
      -s +15551234567 -n "John Doe" --encryption required

# List endpoints
swsh> sip_endpoint list -j

LaML Bin Management 🔗 ↑ TOC

# Create LaML bin (opens editor)
swsh> laml_bin create -n "IVR Menu"

# Create with inline content
swsh> laml_bin create -n "Simple Response" --contents "<Response><Say>Hello!</Say></Response>"

# Update existing bin
swsh> laml_bin update -i abc123def456 -n "Updated IVR Menu"

Sending Communications 🔗 ↑ TOC

# Make a call
swsh> send_call -f +15551234567 -t +15559876543 --laml-bin-id xyz789

# Send SMS
swsh> send_text -f +15551234567 -t +15559876543 -b "Hello from SignalWire!"

# Send fax
swsh> fax send --from_num +15551234567 --to_num +15559876543 \
      -m https://example.com/document.pdf

Using Shell Variables 🔗 ↑ TOC

# Set variables
swsh> MY_NUMBER=+15551234567
swsh> WEBHOOK_URL=https://example.com/webhook

# Use in commands
swsh> phone_number update -N $MY_NUMBER --call-request-url $WEBHOOK_URL

Non-Interactive Mode 🔗 ↑ TOC

Execute commands directly from shell:

# Single command
$ swsh "phone_number list"

# Multiple commands
$ swsh "phone_number list -j && sip_endpoint list"

# With shell variables
$ swsh "MY_NUM=+15551234567 && phone_number lookup --number \$MY_NUM"

API Response Formats 🔗 ↑ TOC

Success Response 🔗 ↑ TOC

Most API calls return JSON:

{
  "data": [...],
  "links": {
    "first": "...",
    "self": "...",
    "next": "..."
  }
}

Error Response 🔗 ↑ TOC

{
  "errors": [
    {
      "code": "20404",
      "detail": "The requested resource was not found.",
      "title": "Not Found"
    }
  ]
}

Notes 🔗 ↑ TOC

1. API Endpoints: The tool uses two API types:

2. Relay/REST API: Default for most operations

3. Compatibility API: For LaML operations (Twilio-compatible)

4. Authentication: Uses HTTP Basic Auth with base64 encoding

5. Environment Variables: Can be used in any command argument with $VARIABLE syntax

6. Interactive Editor: Commands that accept content (like LaML bins) will open an editor if content not provided inline

7. Force Flags: Delete operations typically ask for confirmation unless -f flag is used

8. JSON Output: Most list commands support -j flag for JSON output, useful for scripting

9. Error Handling: The tool validates HTTP responses and provides formatted error messages