For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inSign up
Support
GuidesReference
GuidesReference
    • Core
      • Overview
    • Agents
      • Overview
      • AgentBase
      • AgentServer
      • Configuration
      • ContextBuilder
      • DataMap
      • FunctionResult
      • Helper Functions & Utilities
      • LiveWire
      • PomBuilder
      • Prefabs
      • SkillBase
      • SkillManager
      • SkillRegistry
      • Skills
      • SwaigFunction
      • SwmlBuilder
      • SWMLService
    • RELAY
      • Overview
      • Actions
      • Call
      • Constants
      • Events
      • Message
      • RelayClient
        • connect
        • dial
        • disconnect
        • execute
        • onCall
        • onMessage
        • receive
        • run
        • sendMessage
        • unreceive
      • RelayError
    • REST Client
      • Overview
      • Addresses
      • Calling
      • ChatResource
      • Compat
      • Datasphere
      • Fabric
      • ImportedNumbersResource
      • Logs
      • LookupResource
      • MFA
      • Number Groups
      • Phone Numbers
      • Project
      • PubSubResource
      • Queues
      • Recordings
      • Registry
      • RestClient
      • RestError
      • Short Codes
      • SIP Profile
      • Verified Callers
      • Video
LogoLogoSignalWire Docs
Log inSign up
Support
On this page
  • Parameters
  • Returns
  • Examples
  • Send SMS
  • Send MMS with media
  • With completion callback
RELAYRelayClient

sendMessage

|View as Markdown|Open in Claude|
Was this page helpful?
Edit this page
Previous

unreceive

Next
Built with

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

toNumber
stringRequired

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

fromNumber
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_API_TOKEN!,
6  contexts: ['default']
7});
8
9await client.connect();
10
11const message = await client.sendMessage({
12  toNumber: '+15559876543',
13  fromNumber: '+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);
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_API_TOKEN!,
6  contexts: ['default']
7});
8
9await client.connect();
10
11const message = await client.sendMessage({
12  toNumber: '+15559876543',
13  fromNumber: '+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_API_TOKEN!,
6  contexts: ['default']
7});
8
9await client.connect();
10
11const message = await client.sendMessage({
12  toNumber: '+15559876543',
13  fromNumber: '+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();