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
        • on
        • wait
      • RelayClient
      • 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
  • Properties
  • Events
  • Methods
  • Examples
  • Listening for state changes
  • Waiting for delivery with timeout
RELAY

Message

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

on

Next
Built with

The Message class represents a single SMS/MMS message in the RELAY messaging namespace. It tracks the lifecycle of a sent or received message through state events. Outbound messages progress through queued, initiated, sent, and then reach a terminal state (delivered, undelivered, or failed). Inbound messages arrive fully formed with state received.

Obtain a Message instance from RelayClient.sendMessage() or from the client.onMessage() handler for inbound messages.

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: '+15551234567',
13  fromNumber: '+15559876543',
14  body: 'Hello from SignalWire!',
15});
16
17// Wait for delivery confirmation
18const result = await message.wait(30);
19console.log(`Final state: ${message.state}`);
20
21await client.disconnect();

Properties

messageId
string

Unique identifier for this message, assigned by SignalWire.

context
string

The messaging context this message belongs to.

direction
string

Message direction. Valid values:

  • "inbound" — incoming message
  • "outbound" — outgoing message
fromNumber
string

Sender phone number in E.164 format.

toNumber
string

Recipient phone number in E.164 format.

body
string

Text content of the message.

media
string[]

List of media URLs for MMS messages. Empty list for SMS-only messages.

segments
number

Number of SMS segments required for this message.

state
string

Current message state. See Message Constants for valid values.

  • "queued" — message has been accepted and is waiting to be processed
  • "initiated" — message processing has started
  • "sent" — message has been dispatched to the carrier
  • "delivered" — message was successfully delivered to the recipient
  • "undelivered" — carrier was unable to deliver the message
  • "failed" — message could not be sent
  • "received" — inbound message received from the network
reason
string

Failure reason when the message reaches an error state. Empty string if no failure has occurred.

tags
string[]

Optional tags associated with this message.

isDone
boolean

true if the message has reached a terminal state (delivered, undelivered, or failed). Read-only property.

result
RelayEvent | null

The terminal RelayEvent that resolved this message, or null if the message has not yet completed.

Events

Events are emitted during the lifecycle of a message. Register handlers using message.on() to react to state changes on outbound messages.

See the Events reference for the full list of messaging events, their parameters, and typed event classes.

Methods

on

Register an event listener for state changes on this message.

wait

Block until the message reaches a terminal state.

Examples

Listening for state changes

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: '+15551234567',
13  fromNumber: '+15559876543',
14  body: 'Order confirmed',
15});
16
17const onStateChange = (event) => {
18  console.log(`Message ${message.messageId} -> ${message.state}`);
19};
20
21message.on(onStateChange);
22await message.wait();
23
24await client.disconnect();

Waiting for delivery with timeout

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: '+15551234567',
13  fromNumber: '+15559876543',
14  body: 'Your verification code is 123456',
15});
16
17try {
18  const event = await message.wait(30);
19  if (message.state === 'delivered') {
20    console.log('Message delivered successfully');
21  } else {
22    console.log(`Message failed: ${message.reason}`);
23  }
24} catch (err) {
25  console.log('Timed out waiting for delivery confirmation');
26}
27
28await client.disconnect();