First Steps with Messaging with the Realtime SDK

- language:nodejs - sdk:relayrealtime3 - sdk:relayrealtime4 - product:messaging sidebar_custom_props: platform: javascript import LangSwitchMessage from @site/docs/_common/languageSwitcher.mdx; Send and receive SMS messages from your own Node.js application. ## Installation First, you need to obtain the Realtime SDK. If you are using npm or yarn, from your terminal you can run the following command: shell npm2yarn npm install @signalwire/realtime-api@~3 shell npm2yarn npm install @signalwire/realtime-api Then, you can include the package in JavaScript as follows: js import { Messaging } from @signalwire/realtime-api; js import { SignalWire } from @signalwire/realtime-api; let messageClient = client.messaging; ## Obtaining and configuring a number [Log in](https://signalwire.com/signin) to your SignalWire Space. From the Phone Numbers section, you can [buy a new phone number](/platform/phone-numbers/getting-started/buying-a-phone-number). You will need at least one number to send and receive messages. After you have acquired a number, open its settings by clicking on Edit Settings. Scroll down until you reach Messaging Settings, as shown in the next figure, and configure it to: - handle messages using a Relay application, - forward the call to the office Relay context - handle messages using a Relay application, - forward the call to the office Relay topic

import TopicExplanation from @site/docs/_common/context_topic.mdx; :::info Ensuring message delivery If you are sending messages to the US from a 10DLC number, you _must_ register your traffic with the Campaign Registry. Otherwise, the carriers will not deliver your messages. Please see our [**Campaign Registry - Everything You Need To Know**](/messaging/get-started/campaign-registry) guide for more information. ::: ## Sending your first message To send a message from Node.js you need to instantiate a Messaging client, and then call its send method. js import { Messaging } from @signalwire/realtime-api; const client = new Messaging.Client({ project: your-project-id, token: your-api-token, contexts: [office], }); try { const status = await client.send({ context: office, from: +1xxx, // The number you bought from SignalWire to: +1yyy, body: Hello World!, }); console.log(status); } catch (e) { console.error(e); } We used the office context in two places: first, when initializing the Messaging client. Then, when calling send. You use the contexts array in the Client constructor to specify the list of contexts you want to listen to for events. Instead, the context in the send method determines the context to associate to the message. If the two contexts match, your Client will receive events (message.updated) for this outgoing message too. js import { SignalWire } from @signalwire/realtime-api; const client = await SignalWire({ project: your-project-id, token: your-api-token, topics: [office], }); let messageClient = client.messaging; try { const sendResult = await messageClient.send({ topic: office, from: +1xxx, to: +1yyy, body: Hello World!, }); console.log(sendResult); } catch (e) { console.error(e.message); } We used the office topic in two places: first, when initializing the Messaging client. Then, when calling send. You use the topics array in the Client constructor to specify the list of contexts you want to listen to for events. Instead, the topic in the send method determines the topic to associate to the message. If the two topics match, your Client will receive events (message.updated) for this outgoing message too. You also need to specify a Project ID and API token: find these in the API section of your space, as shown in the following figure. Make sure that your token has the Messaging scope enabled.

## Receiving incoming messages Once a Client is initialized, you can listen for incoming messages on the selected contexts (in our example, just office). For example: js client.on(message.received, (message) => { console.log(Message received:, message); }); Once a Client is initialized, you can listen for incoming messages on the selected topic (in our example, just office). For example: js await messageClient.listen({ topics: [office], onMessageReceived: async (message) => { console.log(Message received, message); }, }); We used the office topic when listening to the messaging clients events. The topics array is used only listen to the phone numbers that you have put in that specific topic from the SignalWire dashboard. Your event handler receives a message object, which you can use to access fields such as message.body, message.from, message.to, etc. ## Next steps Congratulations! You can now send and receive messages with your Node.js application. You are now ready to explore the advanced guides in the Messaging section from the left menu.