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.