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
str | NoneDefaults to None

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
str | NoneDefaults to None

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

media
list[str] | NoneDefaults to None

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

tags
list[str] | NoneDefaults to None

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

region
str | NoneDefaults to None

Origination region for the message.

on_completed
Callable[[RelayEvent], Any] | NoneDefaults to None

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

import asyncio
from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
async def send_sms():
    async with client:
        message = await client.send_message(
            to_number="+15559876543",
            from_number="+15551234567",
            body="Hello from SignalWire Relay!",
        )
        print(f"Message ID: {message.message_id}")
        # Wait for delivery confirmation
        result = await message.wait(timeout=30.0)
        print(f"Final state: {message.state}")
asyncio.run(send_sms())

Send MMS with media

import asyncio
from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
async def send_mms():
    async with client:
        message = await client.send_message(
            to_number="+15559876543",
            from_number="+15551234567",
            body="Check out this image!",
            media=["https://example.com/photo.jpg"],
        )
asyncio.run(send_mms())

With completion callback

import asyncio
from signalwire.relay import RelayClient
client = RelayClient(
    project="your-project-id",
    token="your-api-token",
    contexts=["default"],
)
async def on_delivered(event):
    print(f"Message delivered: {event.params}")
async def send_with_callback():
    async with client:
        message = await client.send_message(
            to_number="+15559876543",
            from_number="+15551234567",
            body="Important notification",
            on_completed=on_delivered,
        )
        # No need to await -- callback fires automatically
asyncio.run(send_with_callback())