Skip to main content

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

NameTypeDescription
paramsObjectObject containing the parameters of the method.
params.topicsstring[]List of topics to listen to. Previously known as contexts.
params.EVENTCallbackThe event to listen to. List of events can be found here.
Example event: (E.g: onMessageReceived)

Returns

Promise<MessageEvents>

A promise that resolves to an 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

NameTypeDescription
paramsObject-
params.body?stringThe content of the message. Optional if media is present.
params.topicstringInbound events for the message will be received on this topic. Previously known as "context".
params.fromstringThe phone number to place the message from. Must be a SignalWire phone number or short code that you own.
params.media?string[]Array of URLs to send in the message. Optional if body is present.
params.region?stringRegion 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.
params.tostringThe phone number to send to.

Returns

Promise<MessagingSendResult>

A promise that resolves to an 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

NameTypeDescription
messageMessageContractThe message that has been received.

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

NameTypeDescription
messageMessageContractThe message that has been updated.