RELAYRelayClient

send_message

View as MarkdownOpen in Claude

Send an outbound SMS or MMS message. Returns a Message object that tracks delivery state changes. Use await message.wait() to block until the message reaches a terminal state (delivered, undelivered, or failed).

All parameters are keyword-only.

At least one of body or media must be provided. Providing both sends an MMS with text and attached media.

Parameters

to_number
strRequired

Destination phone number in E.164 format (e.g., "+15559876543").

from_number
strRequired

Sender phone number in E.164 format. Must be a number owned by your SignalWire project.

context
Optional[str]

Context for receiving state-change events for this message. Defaults to the server-assigned relay protocol string, or "default" if no protocol has been assigned yet.

body
Optional[str]

Text body of the message. Required for SMS. Optional for MMS if media is provided.

media
Optional[list[str]]

List of publicly accessible media URLs for MMS attachments (e.g., images, audio files).

tags
Optional[list[str]]

Optional tags to attach to the message for filtering or tracking.

region
Optional[str]

Origination region for the message.

on_completed
Optional[Callable]

Callback function invoked when the message reaches a terminal state (delivered, undelivered, or failed). Receives the terminal event as its argument.

Returns

Message — A message object in the "queued" state. Use await message.wait() to block until delivery confirmation.

Examples

Send SMS

1import asyncio
2from signalwire.relay import RelayClient
3
4client = RelayClient(
5    project="your-project-id",
6    token="your-api-token",
7    host="your-space.signalwire.com",
8    contexts=["default"],
9)
10
11async def send_sms():
12    async with client:
13        message = await client.send_message(
14            to_number="+15559876543",
15            from_number="+15551234567",
16            body="Hello from SignalWire RELAY!",
17        )
18        print(f"Message ID: {message.message_id}")
19
20        # Wait for delivery confirmation
21        result = await message.wait(timeout=30.0)
22        print(f"Final state: {message.state}")
23
24asyncio.run(send_sms())

Send MMS with media

1import asyncio
2from signalwire.relay import RelayClient
3
4client = RelayClient(
5    project="your-project-id",
6    token="your-api-token",
7    host="your-space.signalwire.com",
8    contexts=["default"],
9)
10
11async def send_mms():
12    async with client:
13        message = await client.send_message(
14            to_number="+15559876543",
15            from_number="+15551234567",
16            body="Check out this image!",
17            media=["https://example.com/photo.jpg"],
18        )
19
20asyncio.run(send_mms())

With completion callback

1import asyncio
2from signalwire.relay import RelayClient
3
4client = RelayClient(
5    project="your-project-id",
6    token="your-api-token",
7    host="your-space.signalwire.com",
8    contexts=["default"],
9)
10
11async def on_delivered(event):
12    print(f"Message delivered: {event.params}")
13
14async def send_with_callback():
15    async with client:
16        message = await client.send_message(
17            to_number="+15559876543",
18            from_number="+15551234567",
19            body="Important notification",
20            on_completed=on_delivered,
21        )
22        # No need to await -- callback fires automatically
23
24asyncio.run(send_with_callback())