[DOC] - SignalWire Calling Commands

[briankwest]

📖 Documentation Request: SignalWire Calling Commands

Feature or Topic Summary

The documentation request is for detailing the available SignalWire Calling API commands, including calling.end, calling.ai_hold, calling.ai_unhold, calling.transfer, and calling.ai_message. The request should specify how each command functions and provide example payloads.

Current Documentation Issues

• The existing documentation does not clearly list or explain these commands in a single, structured format.
• Example payloads and parameter descriptions are missing or unclear.
• No clear explanation of the expected behavior for each command.

Information Needed

• A dedicated section listing all available calling commands.
• Explanation of each command's purpose and functionality.
• JSON payload examples for each command.
• Expected responses and possible errors.
• Best practices for implementing these commands in real-world scenarios.

Target Audience

• Developers integrating SignalWire's calling API.
• Engineers implementing AI-driven call flows.
• Technical support teams troubleshooting call automation issues.

Use Cases

• Hanging up a call programmatically using calling.end.
• Placing a call on hold and resuming it using calling.ai_hold and calling.ai_unhold.
• Transferring a call with audio feedback using calling.transfer.
• Sending AI-generated or user-input messages during a call using calling.ai_message.

Additional Context or References

• The current API documentation: SignalWire Calling API
• Example JSON structures for the commands:

Hang Up a Call

{
    "id": "call_id",
    "command": "calling.end",
    "params": {
        "reason": "hangup"
    }
}

Place a Call on AI Hold

{
    "id": "call_id",
    "command": "calling.ai_hold",
    "params": {}
}

Resume a Call from AI Hold

{
    "id": "call_id",
    "command": "calling.ai_unhold",
    "params": {}
}

Transfer a Call

{
    "id": "call_id",
    "command": "calling.transfer",
    "params": {
        "dest": {
            "version": "1.0.0",
            "sections": {
                "main": [
                    {
                        "set": {
                            "say_voice": "voice"
                        }
                    },
                    {
                        "play": {
                            "url": "say:Please hold while I transfer your call."
                        }
                    },
                    {
                        "connect": {
                            "to": "phone"
                        }
                    }
                ]
            }
        }
    }
}

Send an AI Message During a Call

{
    "id": "call_id",
    "command": "calling.ai_message",
    "params": {
        "role": "system",
        "message_text": "content"
    }
}

Priority

• 🔴 Critical – Documentation is missing or blocking development
• 🟠 High – Documentation is unclear or outdated and impacts productivity
• 🔵 Medium – Documentation is needed but not urgent
• ⚪ Low – Minor enhancement or nice-to-have