SignalWire SDK for PHP

Build AI voice agents, control live calls over WebSocket, and manage every SignalWire resource over REST -- all from one package.

Documentation · Report an Issue · Packagist

---

What's in this SDK

Capability	What it does	Quick link
AI Agents	Build voice agents that handle calls autonomously -- the platform runs the AI pipeline, your code defines the persona, tools, and call flow	Agent Guide
RELAY Client	Control live calls and SMS/MMS in real time over WebSocket -- answer, play, record, collect DTMF, conference, transfer, and more	RELAY docs
REST Client	Manage SignalWire resources over HTTP -- phone numbers, SIP endpoints, Fabric AI agents, video rooms, messaging, and 18+ API namespaces	REST docs

composer require signalwire/sdk

---

AI Agents

Each agent is a self-contained microservice that generates SWML (SignalWire Markup Language) and handles SWAIG (SignalWire AI Gateway) tool calls. The SignalWire platform runs the entire AI pipeline (STT, LLM, TTS) -- your agent just defines the behavior.

require 'vendor/autoload.php';

use SignalWire\Agent\AgentBase;
use SignalWire\SWAIG\FunctionResult;

$agent = new AgentBase(name: 'my-agent', route: '/agent');

$agent->addLanguage(name: 'English', code: 'en-US', voice: 'inworld.Mark');
$agent->promptAddSection('Role', 'You are a helpful assistant.');

$agent->defineTool(
    name:        'get_time',
    description: 'Get the current time',
    parameters:  ['type' => 'object', 'properties' => []],
    handler: function (array $args, array $rawData): FunctionResult {
        return new FunctionResult('The time is ' . date('H:i:s'));
    },
);

$agent->run();

List an agent's SWAIG tools in-process, without running a server:

vendor/bin/swaig-test --file examples/simple_agent.php --list-tools

Dump its SWML or execute a tool against a running agent (--url mode):

vendor/bin/swaig-test --url http://user:pass@localhost:3000/simple --dump-swml
vendor/bin/swaig-test --url http://user:pass@localhost:3000/simple --exec get_time

Agent Features

• Prompt Object Model (POM) -- structured prompt composition via promptAddSection()
• SWAIG tools -- define functions with defineTool() that the AI calls mid-conversation, with native access to the call's media stack
• Skills system -- add capabilities with one-liners: $agent->addSkill('datetime')
• Contexts and steps -- structured multi-step workflows with navigation control
• DataMap tools -- tools that execute on SignalWire's servers, calling REST APIs without your own webhook
• Dynamic configuration -- per-request agent customization for multi-tenant deployments
• Call flow control -- pre-answer, post-answer, and post-AI verb insertion
• Prefab agents -- ready-to-use archetypes (InfoGatherer, Survey, FAQ, Receptionist, Concierge)
• Multi-agent hosting -- serve multiple agents on a single server with AgentServer
• SIP routing -- route SIP calls to agents based on usernames
• Session state -- persistent conversation state with global data and post-prompt summaries
• Security -- auto-generated basic auth, function-specific HMAC tokens, SSL support
• Serverless -- auto-detects CGI/FastCGI, AWS Lambda, Google Cloud Functions, and Azure Functions

Agent Examples

The examples/ directory contains working examples:

Example	What it demonstrates
simple_agent.php	POM prompts, SWAIG tools, multilingual support, LLM tuning
contexts_demo.php	Multi-persona workflow with context switching and step navigation
datamap_demo.php	Server-side API tools without webhooks
skills_demo.php	Loading built-in skills (datetime, math)
call_flow_and_actions_demo.php	Call flow verbs, debug events, FunctionResult actions
session_and_state_demo.php	on_summary, global data, post-prompt summaries
multi_agent_server.php	Multiple agents on one server
simple_dynamic_agent.php	Per-request dynamic configuration, multi-tenant routing

See examples/README.md for the full list organized by category.

---

RELAY Client

Real-time call control and messaging over WebSocket. The RELAY client connects to SignalWire via the Blade protocol and gives you imperative, blocking control over live phone calls and SMS/MMS.

require 'vendor/autoload.php';

use SignalWire\Relay\Client;

$client = new Client([
    'project'  => $_ENV['SIGNALWIRE_PROJECT_ID'],
    'token'    => $_ENV['SIGNALWIRE_API_TOKEN'],
    'host'     => $_ENV['SIGNALWIRE_SPACE'] ?? 'relay.signalwire.com',
    'contexts' => ['default'],
]);

$client->onCall(function ($call) {
    $call->answer();
    $action = $call->play(media: [
        ['type' => 'tts', 'params' => ['text' => 'Welcome to SignalWire!']],
    ]);
    $action->wait();
    $call->hangup();
});

$client->connect();  // opens the WebSocket and authenticates
$client->run();

• 57+ calling methods (play, record, collect, detect, tap, stream, AI, conferencing, and more)
• SMS/MMS messaging with delivery tracking
• Action objects with wait(), stop(), pause(), resume()
• Auto-reconnect with exponential backoff

See the RELAY documentation for the full guide, API reference, and examples.

---

REST Client

Synchronous REST client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required.

require 'vendor/autoload.php';

use SignalWire\REST\RestClient;

$client = new RestClient(
    project: $_ENV['SIGNALWIRE_PROJECT_ID'],
    token:   $_ENV['SIGNALWIRE_API_TOKEN'],
    host:    $_ENV['SIGNALWIRE_SPACE'],
);

$client->fabric()->aiAgents()->create(['name' => 'Support Bot', 'prompt' => ['text' => 'You are helpful.']]);
$client->calling()->play($callId, play: [['type' => 'tts', 'params' => ['text' => 'Hello!']]]);
$client->phoneNumbers()->search(['areacode' => '512']);
$client->datasphere()->documents()->search(queryString: 'billing policy');

• 22 namespaced API surfaces: Fabric (16 resource types), Calling (37 commands), Video, Datasphere, Phone Numbers, SIP, Queues, Recordings, and more
• Lightweight HTTP via cURL (one handle per request)
• Array returns -- raw data, no wrapper objects

See the REST documentation for the full guide, API reference, and examples.

---

Installation

composer require signalwire/sdk

Requires PHP 8.2+ with the json, mbstring, and openssl extensions.

Documentation

Full reference documentation is available at developer.signalwire.com/sdks/agents-sdk.

Guides are also available in the docs/ directory:

Getting Started

• Agent Guide -- creating agents, prompt configuration, dynamic setup
• Architecture -- SDK architecture and core concepts
• SDK Features -- feature overview, SDK vs raw SWML comparison

Core Features

• SWAIG Reference -- function results, actions, post_data lifecycle
• Contexts and Steps -- structured workflows, navigation, gather mode
• DataMap Guide -- serverless API tools without webhooks
• LLM Parameters -- temperature, top_p, barge confidence tuning
• SWML Service Guide -- low-level construction of SWML documents

Skills and Extensions

• Skills System -- built-in skills and the modular framework
• Third-Party Skills -- creating and publishing custom skills

Deployment

• CLI Guide -- swaig-test command reference
• Cloud Functions -- Lambda, Google Cloud Functions, Azure deployment
• Configuration -- environment variables, SSL, proxy setup
• Security -- authentication and security model

Reference

• API Reference -- complete class and method reference
• Web Service -- HTTP server and endpoint details
• Skills Parameter Schema -- skill parameter definitions

Environment Variables

Get your project id, API token, and space hostname from the SignalWire dashboard (API → Credentials). Copy .env.example to .env for the full list of variables the SDK reads; see docs/configuration.md for the complete reference (custom CA bundles, RELAY overrides, and more).

Variable	Used by	Description
SIGNALWIRE_PROJECT_ID	RELAY, REST	Project identifier
SIGNALWIRE_API_TOKEN	RELAY, REST	API token
SIGNALWIRE_SPACE	RELAY, REST	Space hostname (e.g. example.signalwire.com)
SWML_BASIC_AUTH_USER	Agents	Basic auth username (default: auto-generated)
SWML_BASIC_AUTH_PASSWORD	Agents	Basic auth password (default: auto-generated)
SWML_PROXY_URL_BASE	Agents	Base URL when behind a reverse proxy
SWML_SSL_ENABLED	Agents	Enable HTTPS (true, 1, yes)
SWML_SSL_CERT_PATH	Agents	Path to SSL certificate
SWML_SSL_KEY_PATH	Agents	Path to SSL private key
SIGNALWIRE_LOG_LEVEL	All	Logging level (debug, info, warn, error)
SIGNALWIRE_LOG_MODE	All	Set to off to suppress all logging

Testing, Formatting, and Linting

Test / format / lint go through the canonical scripts/run-*.sh entry points. They self-bootstrap their tool environment (put vendor/bin on PATH, composer install if vendor/ is missing) and run correctly from any directory, so you never have to invoke the raw tools by hand. scripts/run-ci.sh calls these same scripts, so local behavior matches CI.

# Run the full test suite (canonical entry point; self-bootstraps, any CWD)
bash scripts/run-tests.sh

# Run a subset — pass a filter (phpunit --filter): a test name / class / regex
bash scripts/run-tests.sh LoggerTest

# Format (php-cs-fixer): APPLY in place (default) / --check = verify-only (CI)
bash scripts/run-format.sh
bash scripts/run-format.sh --check

# Lint (phpstan level 9, zero findings)
bash scripts/run-lint.sh

# Coverage (requires Xdebug or PCOV)
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage/

License

MIT -- see LICENSE for details.