RELAYRelayClient

sendMessage

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).

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

Parameters

to
stringRequired

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

from
stringRequired

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

context
string | undefined

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
string | undefined

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

media
string[] | undefined

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

tags
string[] | undefined

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

region
string | undefined

Origination region for the message.

onCompleted
(event: any) => void | Promise<void>

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

Returns

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

Examples

Send SMS

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9await client.connect();
10
11const message = await client.sendMessage({
12  to: '+15559876543',
13  from: '+15551234567',
14  body: 'Hello from SignalWire RELAY!',
15});
16console.log(`Message ID: ${message.messageId}`);
17
18// Wait for delivery confirmation
19const result = await message.wait(30_000);
20console.log(`Final state: ${message.state}`);
21
22await client.disconnect();

Send MMS with media

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9await client.connect();
10
11const message = await client.sendMessage({
12  to: '+15559876543',
13  from: '+15551234567',
14  body: 'Check out this image!',
15  media: ['https://example.com/photo.jpg'],
16});
17
18await client.disconnect();

With completion callback

1import { RelayClient } from '@signalwire/sdk';
2
3const client = new RelayClient({
4  project: process.env.SIGNALWIRE_PROJECT_ID!,
5  token: process.env.SIGNALWIRE_TOKEN!,
6  contexts: ['default']
7});
8
9await client.connect();
10
11const message = await client.sendMessage({
12  to: '+15559876543',
13  from: '+15551234567',
14  body: 'Important notification',
15  onCompleted: (event) => {
16    console.log(`Message delivered: ${JSON.stringify(event.params)}`);
17  },
18});
19// No need to await -- callback fires automatically
20
21await client.disconnect();