RELAY Client

1
client = RelayClient(
2
    project="your-project-id",
3
    token="your-api-token",
4
    host="your-space.signalwire.com",
5
)

1
client = RelayClient(
2
    jwt_token="your-jwt-token",
3
    host="your-space.signalwire.com",
4
)

1
# With env vars set, no arguments needed
2
client = RelayClient(contexts=["default"])

1
# Subscribe at connection time
2
client = RelayClient(contexts=["sales", "support"])
3
4
# Or subscribe dynamically after connecting
5
await client.receive(["new-context"])
6
7
# Unsubscribe from contexts
8
await client.unreceive(["old-context"])

1
async with RelayClient(contexts=["default"]) as client:
2
    # Connected and authenticated
3
    call = await client.dial(...)
4
    # Automatically disconnects on exit

1
#!/usr/bin/env python3
2
"""Handle inbound calls with RELAY."""
3
4
from signalwire.relay import RelayClient
5
6
client = RelayClient(contexts=["ivr"])
7
8
@client.on_call
9
async def handle_call(call):
10
    print(f"Inbound call from {call.device}")
11
    await call.answer()
12
13
    # Play a menu
14
    action = await call.play([
15
        {"type": "tts", "text": "Press 1 for sales, 2 for support."}
16
    ])
17
    await action.wait()
18
19
    # Collect a digit
20
    collect = await call.collect(
21
        digits={"max": 1, "digit_timeout": 5.0},
22
        initial_timeout=10.0,
23
    )
24
    result = await collect.wait()
25
26
    digit = result.params.get("result", {}).get("digits", "")
27
    if digit == "1":
28
        await call.connect([[{"type": "phone", "params": {"to_number": "+15551001000"}}]])
29
    elif digit == "2":
30
        await call.connect([[{"type": "phone", "params": {"to_number": "+15552002000"}}]])
31
    else:
32
        play = await call.play([{"type": "tts", "text": "Invalid selection. Goodbye."}])
33
        await play.wait()
34
        await call.hangup()
35
36
client.run()

1
#!/usr/bin/env python3
2
"""Make an outbound call with RELAY."""
3
4
import asyncio
5
from signalwire.relay import RelayClient
6
7
client = RelayClient(contexts=["default"])
8
9
async def main():
10
    async with client:
11
        call = await client.dial(
12
            devices=[[{
13
                "type": "phone",
14
                "params": {
15
                    "from_number": "+15551234567",
16
                    "to_number": "+15559876543",
17
                    "timeout": 30,
18
                },
19
            }]],
20
        )
21
        print(f"Call answered: {call.call_id}")
22
23
        action = await call.play([
24
            {"type": "tts", "text": "This is an automated message from SignalWire."}
25
        ])
26
        await action.wait()
27
        await call.hangup()
28
29
asyncio.run(main())

1
# Serial dial: try first, then second
2
devices = [
3
    [{"type": "phone", "params": {"to_number": "+15551111111", "from_number": "+15550000000"}}],
4
    [{"type": "phone", "params": {"to_number": "+15552222222", "from_number": "+15550000000"}}],
5
]
6
7
# Parallel dial: ring both simultaneously
8
devices = [
9
    [
10
        {"type": "phone", "params": {"to_number": "+15551111111", "from_number": "+15550000000"}},
11
        {"type": "phone", "params": {"to_number": "+15552222222", "from_number": "+15550000000"}},
12
    ],
13
]

1
# Play TTS
2
action = await call.play([{"type": "tts", "text": "Hello!"}])
3
await action.wait()
4
5
# Play audio file
6
action = await call.play([{"type": "audio", "url": "https://example.com/audio.mp3"}])
7
8
# Control playback
9
await action.pause()
10
await action.resume()
11
await action.volume(5.0)  # -40.0 to 40.0 dB
12
await action.stop()

1
# Start recording
2
action = await call.record(audio={"direction": "both", "format": "mp3"})
3
4
# Pause/resume recording
5
await action.pause()
6
await action.resume()
7
8
# Stop and get result
9
await action.stop()
10
result = await action.wait()
11
url = result.params.get("record", {}).get("url", "")
12
print(f"Recording URL: {url}")

1
# Collect digits with prompt
2
collect = await call.play_and_collect(
3
    media=[{"type": "tts", "text": "Enter your account number."}],
4
    collect={
5
        "digits": {
6
            "max": 10,
7
            "digit_timeout": 3.0,
8
            "terminators": "#",
9
        },
10
    },
11
)
12
result = await collect.wait()
13
digits = result.params.get("result", {}).get("digits", "")
14
15
# Standalone collect (no prompt)
16
collect = await call.collect(
17
    digits={"max": 4, "digit_timeout": 5.0},
18
    speech={"end_silence_timeout": 2.0},
19
)
20
result = await collect.wait()

1
# Answering machine detection
2
detect = await call.detect(
3
    detect={"type": "machine", "params": {"initial_timeout": 4.5}},
4
    timeout=30.0,
5
)
6
result = await detect.wait()
7
machine_result = result.params.get("detect", {})

1
# Bridge to another number
2
await call.connect(
3
    devices=[[{
4
        "type": "phone",
5
        "params": {"to_number": "+15559876543", "from_number": "+15551234567"},
6
    }]],
7
    ringback=[{"type": "ringtone", "name": "us"}],
8
)
9
10
# Disconnect (unbridge)
11
await call.disconnect()

1
# Join a conference
2
await call.join_conference("team-standup", muted=False, beep="true")
3
4
# Leave a conference
5
await call.leave_conference("conference-id-here")

1
await call.hold()
2
# ... do something ...
3
await call.unhold()

1
await call.denoise()
2
# ... later ...
3
await call.denoise_stop()

1
ai = await call.ai(
2
    prompt={"text": "You are a helpful assistant."},
3
    languages=[{"name": "English", "code": "en-US", "voice": "rime.spore"}],
4
)
5
await ai.wait()  # Blocks until AI session ends

1
action = await call.play([{"type": "tts", "text": "Hello"}])
2
3
# Fire-and-forget: don't wait for completion
4
print(f"Play started, control_id={action.control_id}")
5
6
# Or wait for completion
7
result = await action.wait(timeout=30.0)
8
print(f"Play finished: {result.params.get('state')}")

1
async def on_play_done(event):
2
    print(f"Play finished: {event.params.get('state')}")
3
4
action = await call.play(
5
    [{"type": "tts", "text": "Processing..."}],
6
    on_completed=on_play_done,
7
)
8
# No need to await — callback fires automatically

1
message = await client.send_message(
2
    to_number="+15559876543",
3
    from_number="+15551234567",
4
    body="Hello from SignalWire RELAY!",
5
)
6
print(f"Message ID: {message.message_id}")
7
8
# Wait for delivery confirmation
9
result = await message.wait(timeout=30.0)
10
print(f"Final state: {message.state}")  # delivered, failed, etc.

1
message = await client.send_message(
2
    to_number="+15559876543",
3
    from_number="+15551234567",
4
    body="Check out this image!",
5
    media=["https://example.com/photo.jpg"],
6
)

1
@client.on_message
2
async def handle_message(message):
3
    print(f"From: {message.from_number}")
4
    print(f"Body: {message.body}")
5
    if message.media:
6
        print(f"Media: {message.media}")

1
from signalwire.relay import EVENT_CALL_STATE, EVENT_CALL_PLAY
2
3
@client.on_call
4
async def handle_call(call):
5
    def on_state_change(event):
6
        print(f"Call state: {event.params.get('call_state')}")
7
8
    def on_play_event(event):
9
        print(f"Play state: {event.params.get('state')}")
10
11
    call.on(EVENT_CALL_STATE, on_state_change)
12
    call.on(EVENT_CALL_PLAY, on_play_event)
13
14
    await call.answer()
15
    action = await call.play([{"type": "tts", "text": "Hello"}])
16
    await call.wait_for_ended()

1
# Via constructor
2
client = RelayClient(contexts=["default"], max_active_calls=100)

1
from signalwire.relay import RelayClient, RelayError
2
3
try:
4
    call = await client.dial(devices=[[{...}]])
5
except RelayError as e:
6
    print(f"RELAY error {e.code}: {e.message}")

1
#!/usr/bin/env python3
2
"""Complete IVR system with RELAY."""
3
4
from signalwire.relay import RelayClient, EVENT_CALL_STATE
5
6
client = RelayClient(contexts=["main-ivr"])
7
8
@client.on_call
9
async def handle_call(call):
10
    await call.answer()
11
12
    # Start recording
13
    recording = await call.record(audio={"direction": "both", "format": "mp3"})
14
15
    # Play welcome and collect input
16
    collect = await call.play_and_collect(
17
        media=[
18
            {"type": "tts", "text": "Welcome to Acme Corp."},
19
            {"type": "tts", "text": "Press 1 for sales, 2 for support, or 3 to leave a message."},
20
        ],
21
        collect={"digits": {"max": 1, "digit_timeout": 5.0}},
22
    )
23
    result = await collect.wait()
24
    digit = result.params.get("result", {}).get("digits", "")
25
26
    if digit == "1":
27
        await call.play([{"type": "tts", "text": "Connecting you to sales."}])
28
        await call.connect([[{
29
            "type": "phone",
30
            "params": {"to_number": "+15551001000", "from_number": "+15550000000"},
31
        }]])
32
    elif digit == "2":
33
        await call.play([{"type": "tts", "text": "Connecting you to support."}])
34
        await call.connect([[{
35
            "type": "phone",
36
            "params": {"to_number": "+15552002000", "from_number": "+15550000000"},
37
        }]])
38
    elif digit == "3":
39
        play = await call.play([
40
            {"type": "tts", "text": "Please leave your message after the beep."},
41
            {"type": "audio", "url": "https://example.com/beep.wav"},
42
        ])
43
        await play.wait()
44
        voicemail = await call.record(audio={
45
            "direction": "listen",
46
            "format": "mp3",
47
            "end_silence_timeout": 3.0,
48
        })
49
        await voicemail.wait()
50
    else:
51
        play = await call.play([{"type": "tts", "text": "Invalid option. Goodbye."}])
52
        await play.wait()
53
54
    # Stop recording and hang up
55
    await recording.stop()
56
    await call.hangup()
57
58
if __name__ == "__main__":
59
    client.run()