SignalWire SDK for C++

Build AI voice agents, control live calls over WebSocket, and manage every SignalWire resource over REST -- all from modern C++17.

Documentation · Report an Issue · GitHub

---

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 21 API namespaces	REST docs

# Requirements: C++17 compiler, CMake 3.16+, OpenSSL
git clone https://github.com/signalwire/signalwire-cpp.git
cd signalwire-cpp && mkdir build && cd build
cmake .. && make -j$(nproc)

---

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.

#include <signalwire/agent/agent_base.hpp>
#include <ctime>

using namespace signalwire;
using json = nlohmann::json;

class MyAgent : public agent::AgentBase {
public:
    MyAgent() : AgentBase("my-agent", "/agent") {
        add_language({"English", "en-US", "inworld.Mark"});
        prompt_add_section("Role", "You are a helpful assistant.");

        define_tool("get_time", "Get the current time",
            {{"type", "object"}, {"properties", json::object()}},
            [](const json& /*args*/, const json& /*raw*/) -> swaig::FunctionResult {
                auto now = std::time(nullptr);
                char buf[32];
                std::strftime(buf, sizeof(buf), "%H:%M:%S", std::localtime(&now));
                return swaig::FunctionResult(std::string("The time is ") + buf);
            });
    }
};

int main() {
    MyAgent agent;
    agent.run();  // Serves on http://0.0.0.0:3000/agent
}

Test locally without running a server:

bin/swaig-test http://localhost:3000/agent --list-tools
bin/swaig-test http://localhost:3000/agent --dump-swml
bin/swaig-test http://localhost:3000/agent --exec get_time

Agent Features

• Prompt Object Model (POM) -- structured prompt composition via prompt_add_section()
• SWAIG tools -- define functions with define_tool() that the AI calls mid-conversation, with native access to the call's media stack
• Skills system -- add capabilities with one-liners: agent.add_skill("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 (InfoGathererAgent, SurveyAgent, FAQBotAgent, ReceptionistAgent, ConciergeAgent)
• 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
• C API -- extern "C" wrapper for FFI from C, Python, Ruby, Lua, etc.

Agent Examples

The examples/ directory contains 55+ working examples:

Example	What it demonstrates
simple_agent.cpp	POM prompts, SWAIG tools, hints, languages, SIP routing
contexts_demo.cpp	Multi-persona workflow with context switching and step navigation
datamap_demo.cpp	Server-side API tools without webhooks
skills_demo.cpp	Loading built-in skills (datetime, math, web_search)
call_flow_and_actions_demo.cpp	5-phase verb pipeline: pre-answer, answer, post-answer, post-AI
session_and_state_demo.cpp	Global data, session tokens, callbacks
multi_agent_server.cpp	Multiple agents on one server
comprehensive_dynamic_agent.cpp	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 control over live phone calls and SMS/MMS.

#include <signalwire/relay/client.hpp>

using namespace signalwire::relay;

int main() {
    auto client = RelayClient::from_env();

    client.on_call([](Call& call) {
        call.answer();
        auto action = call.play({
            {{"type", "tts"}, {"params", {{"text", "Welcome to SignalWire!"}}}}
        });
        action.wait();
        call.hangup();
    });

    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.

#include <signalwire/rest/rest_client.hpp>

using namespace signalwire::rest;
using json = nlohmann::json;

int main() {
    auto client = RestClient::from_env();

    auto agents = client.fabric().ai_agents.list();
    auto call   = client.calling().dial({
        {"to", "+15551234567"}, {"from", "+15559876543"},
        {"url", "https://example.com/handler"}
    });
    auto numbers = client.phone_numbers().search({{"area_code", "512"}});
    auto results = client.datasphere().documents.search({{"query_string", "billing policy"}});
}

• 21 namespaced API surfaces: Fabric (13 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), Phone Numbers, SIP, Queues, Recordings, and more
• Generic CRUD resources with list(), create(), get(), update(), del()
• JSON dict returns via nlohmann/json -- no wrapper objects

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

---

Installation

Prerequisites

• C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)
• CMake 3.16+
• OpenSSL 3.0+ development libraries
• pthreads
• Network access at configure time (CMake fetches the IXWebSocket dependency used by the RELAY transport)

Build from Source

git clone https://github.com/signalwire/signalwire-cpp.git
cd signalwire-cpp
mkdir build && cd build
cmake ..
make -j$(nproc)

This produces the static library libsignalwire.a and the run_tests binary.

Link to Your Project

Use CMake -- add_subdirectory (or FetchContent) wires up the static library plus all of its transitive dependencies (OpenSSL, pthreads, IXWebSocket, and the Apple CoreFoundation/Security frameworks on macOS) automatically. Add to your CMakeLists.txt:

add_subdirectory(signalwire-cpp)
add_executable(my_agent my_agent.cpp)
target_link_libraries(my_agent signalwire)

Or pull it in directly with FetchContent:

include(FetchContent)
FetchContent_Declare(
    signalwire
    GIT_REPOSITORY https://github.com/signalwire/signalwire-cpp.git
    GIT_TAG        main
)
FetchContent_MakeAvailable(signalwire)

add_executable(my_agent my_agent.cpp)
target_link_libraries(my_agent signalwire)

The public headers live under include/ and the vendored header-only dependencies (nlohmann/json, cpp-httplib) under deps/; both are added to the signalwire target's public include path, so consumers do not need to set them manually. Compiling against the static archive by hand (raw g++) also requires linking IXWebSocket and, on macOS, the CoreFoundation/Security frameworks -- CMake is the supported path.

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
• MCP Gateway -- Model Context Protocol integration

Deployment

• CLI Guide -- swaig-test command reference
• Cloud Functions -- containerized 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
• REST Client -- REST API client
• RELAY Client -- real-time call control

Environment Variables

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

# Build and run the test suite
mkdir build && cd build
cmake .. && make -j$(nproc)
./run_tests

# Run by category via ctest
ctest -R agent
ctest -R relay
ctest -R rest

The test suite contains 258 tests covering all components.

License

MIT -- see LICENSE for details.