register_verb_handler

Register a custom verb handler for specialized validation and configuration of a SWML verb. When a verb with a registered handler is added via add_verb(), the handler’s validate_config() method is used instead of generic schema validation.

The SDK ships with a built-in AIVerbHandler for the ai verb. Register your own handlers for custom verbs or to override default validation behavior.

Custom verb handlers are useful when a verb has complex validation rules that go beyond JSON Schema checks — for example, mutually exclusive parameters or conditional requirements.

Parameters

handler

SWMLVerbHandlerRequired

An instance of a class that extends SWMLVerbHandler. Must implement three methods:

get_verb_name() — returns the verb name string this handler manages
validate_config(config) — returns a (bool, list[str]) tuple of (is_valid, errors)
build_config(**kwargs) — returns a configuration dictionary for the verb

Returns

None

Example

1 from signalwire import SWMLService
2 from signalwire.core.swml_handler import SWMLVerbHandler
3 
4 class CustomVerbHandler(SWMLVerbHandler):
5     def get_verb_name(self):
6         return "my_verb"
7 
8     def validate_config(self, config):
9         errors = []
10         if "target" not in config:
11             errors.append("Missing required field 'target'")
12         return len(errors) == 0, errors
13 
14     def build_config(self, **kwargs):
15         return {"target": kwargs.get("target")}
16 
17 service = SWMLService(name="custom-service")
18 service.register_verb_handler(CustomVerbHandler())
19 
20 # Now add_verb will use the custom handler for validation
21 service.add_verb("my_verb", {"target": "https://example.com"})
22 print(service.render_document())