PlayBackgroundFileSkill

Control background audio/video playback during calls using SWML playback actions. Supply files and the skill emits a single tool whose action enum includes start_<key> for each configured file plus stop. The skill refuses to load when files is empty.

Class: PlayBackgroundFileSkill

Tools: play_background_file (configurable via tool_name)

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. Required when registering multiple instances on the same agent.

files

object[]Required

Array of pre-configured file entries that become selectable via the tool’s action enum.

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.

Example

import { AgentBase, PlayBackgroundFileSkill } from '@signalwire/sdk';
const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');
await agent.addSkill(new PlayBackgroundFileSkill({
  tool_name: 'play_testimonial',
  files: [
    {
      key: 'massey',
      description: 'Customer success story from Massey Energy',
      url: 'https://example.com/massey.mp4',
      wait: true,
    },
  ],
}));
agent.run();