For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
GuidesReference
GuidesReference
    • Core
      • Overview
    • Agents
      • Overview
      • AgentBase
      • AgentServer
      • Configuration
      • ContextBuilder
      • DataMap
      • FunctionResult
      • Helper Functions & Utilities
      • LiveWire
      • PomBuilder
      • Prefabs
      • SkillBase
      • SkillManager
      • SkillRegistry
      • Skills
        • ApiNinjasTriviaSkill
        • AskClaudeSkill
        • ClaudeSkillsSkill
        • CustomSkillsSkill
        • DataSphereServerlessSkill
        • DataSphereSkill
        • DateTimeSkill
        • GoogleMapsSkill
        • InfoGathererSkill
        • JokeSkill
        • MathSkill
        • McpGatewaySkill
        • NativeVectorSearchSkill
        • PlayBackgroundFileSkill
        • SpiderSkill
        • SwmlTransferSkill
        • WeatherApiSkill
        • WebSearchSkill
        • WikipediaSearchSkill
      • SwaigFunction
      • SwmlBuilder
      • SWMLService
    • RELAY
      • Overview
      • Actions
      • Call
      • Constants
      • Events
      • Message
      • RelayClient
      • RelayError
    • REST Client
      • Overview
      • Addresses
      • Calling
      • ChatResource
      • Compat
      • Datasphere
      • Fabric
      • ImportedNumbersResource
      • Logs
      • LookupResource
      • MFA
      • Number Groups
      • Phone Numbers
      • Project
      • PubSubResource
      • Queues
      • Recordings
      • Registry
      • RestClient
      • RestError
      • Short Codes
      • SIP Profile
      • Verified Callers
      • Video
LogoLogoSignalWire Docs
Log inSign up
Support
On this page
  • tool_name
  • files
  • default_file_url
  • allowed_domains
  • Example — pre-configured files
  • Example — free-form URL
AgentsSkills

PlayBackgroundFileSkill

|View as Markdown|Open in Claude|
Was this page helpful?
Edit this page
Previous

SpiderSkill

Next
Built with

Control background audio/video playback during calls using SWML playback actions. Two configuration modes are supported:

  • Pre-configured mode (matches Python) — supply files and the skill emits a single tool whose action enum includes start_<key> for each configured file plus stop.
  • Free-form mode (TypeScript-specific) — omit files and supply default_file_url and/or allowed_domains. The skill emits two tools, play_background and stop_background, which accept arbitrary URLs (with optional domain allowlist).

Class: PlayBackgroundFileSkill

Tools (pre-configured mode): play_background_file (configurable via tool_name)

Tools (free-form mode): play_background, stop_background

Env vars: None

Multi-instance: yes — set a distinct tool_name per instance.

tool_name
stringDefaults to play_background_file

Custom name for the generated SWAIG tool in pre-configured mode. Required when registering multiple instances on the same agent.

files
object[]

Array of pre-configured file entries that become selectable via the tool’s action enum. When supplied (and non-empty), the skill runs in pre-configured mode; when omitted or empty, the skill falls back to free-form mode.

Each entry has:

  • key (string, required) — unique identifier (alphanumeric, underscores, hyphens); mapped to start_<key> in the action enum.
  • description (string, required) — human-readable description shown to the AI.
  • url (string, required) — URL of the audio/video file.
  • wait (boolean, optional, default false) — whether to wait for the file to finish playing.
default_file_url
string

Default audio file URL for free-form mode. When set, the file_url parameter on the play_background tool becomes optional.

allowed_domains
string[]

Allowlist of domains for audio file URLs in free-form mode. When set, only URLs whose hostname matches or is a subdomain of one of these entries are accepted.

Example — pre-configured files

1import { AgentBase, PlayBackgroundFileSkill } from '@signalwire/sdk';
2
3const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
4agent.setPromptText('You are a helpful assistant.');
5
6await agent.addSkill(new PlayBackgroundFileSkill({
7  tool_name: 'play_testimonial',
8  files: [
9    {
10      key: 'massey',
11      description: 'Customer success story from Massey Energy',
12      url: 'https://example.com/massey.mp4',
13      wait: true,
14    },
15  ],
16}));
17
18agent.run();

Example — free-form URL

1await agent.addSkill(new PlayBackgroundFileSkill({
2  default_file_url: 'https://example.com/hold-music.mp3',
3  allowed_domains: ['example.com', 'cdn.example.com'],
4}));