Skip to main content
Getting StartedGuidesTechnical Reference

Client

A Messaging client is used to listen to inbound SMS and MMS messages, and to send outbound SMS and MMS messages.

Messaging Client​

Setting up a Messaging Client​

To create a Messaging client, you will first need to create a SignalWire Realtime-Client. After the SignalWire Client is created, you can access the Messaging client using the messaging namespace.

Example​

import { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({ project: "ProjectID Here", token: "Token Here"})

const messageClient = client.messaging;

This example demonstrates how to set up a messaging client using the SignalWire API.

Methods​

listen​

▸ listen({ event: Callback }): Promise<MessageEvents>

Listens for message events.

Parameters​

params
objectrequired

Object containing the parameters of the method.

params.topics
string[]required

List of topics to listen to. Previously known as contexts.

params.EVENT
Callback

The event to listen to. List of events can be found here. Example event: onMessageReceived.

Returns​

Promise<MessageEvents>

A promise that resolves to a MessageEvents object that you can use to view the current state or results of the event.

Example​

In this example, we listen for inbound messages on the topic "office" and log any received messages.

import { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({ project: "ProjectID Here", token: "Token Here"})

await client.messaging.listen({
  topics: ["office"],
  async onMessageReceived(message) {
    console.log("message.received", message);
  }
})

send​

▸ send(params): Promise<MessagingSendResult>

Send an outbound SMS or MMS message.

Parameters​

params
objectrequired

Object containing the parameters of the method.

params.from
stringrequired

The phone number to place the message from. Must be a SignalWire phone number or short code that you own.

params.to
stringrequired

The phone number to send to.

params.body
string

The content of the message. Required if media is not present.

params.media
string[]

Array of URLs to send in the message. Required if body is not present.

params.topic
string

Inbound events for the message will be received on this topic. Previously known as "context".

params.region
string

Region of the world to originate the message from. A default value is picked based on account preferences or device location.

params.tags
string[]

Array of strings to tag the message with for searching in the UI.

Returns​

Promise<MessagingSendResult>

A promise that resolves to a MessagingSendResult object that you can use to view the result of the sent message.

Example​

In this example, we send an outbound message to a phone number with the content "Hello World!".

import { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({ project: "ProjectID Here", token: "Token Here"})

let messageClient = client.messaging;

try {
  const sendResult = await messageClient.send({
    from: "+1xxx",
    to: "+1yyy",
    body: "Hello World!"
  });
  console.log("Message ID: ", sendResult.messageId);
} catch (e) {
  console.error(e.message);
}

Events​

onMessageReceived​

• client.messaging.listen({onMessageReceived: Callback})

Emitted whenever a message is received. Your event handler will be called with an instance of MessageContract.

Parameters​

message
MessageContractrequired

The message that has been received. See MessageContract.

onMessageUpdated​

• client.messaging.listen({onMessageUpdated: Callback})

Emitted when the status of a message is updated. You can use this event to track the different stages that an outbound message goes through for delivery. Your event handler will be called with an instance of MessageContract.

Parameters​

message
MessageContractrequired

The message that has been updated. See MessageContract.