DataFlows SMS for Node.js

The official Node.js client for the DataFlows SMS API. It has no dependencies and needs Node 18 or newer.

Install

npm install @dataflows/sms

Send your first SMS

Find your API token in your DataFlows account under Developers, and keep it in an environment variable:

export DATAFLOWS_API_TOKEN="your-token"

import { DataFlows } from '@dataflows/sms';

const client = new DataFlows();

const result = await client.sms.send({
  recipient: '61404235133',
  senderId: 'YOUR_SENDER_ID',
  message: 'Hello from DataFlows',
});

console.log(result.campaign_id);

This really sends a text and uses your credit, so change the number first. require works too:

const { DataFlows } = require('@dataflows/sms');

What you can do

| Call | What it does | |---|---| | client.account.profile() | Your account details | | client.account.balance() | Your remaining balance | | client.senderIds.list() | Your active sender IDs | | client.sms.send({ recipient, senderId, message, scheduleTime }) | Send or schedule an SMS | | client.sms.list({ page, limit }) | A page of your sent messages | | client.sms.get(uid) | One message | | client.groups.list({ page }) | A page of your contact groups | | client.groups.create({ name }) | Add a group | | client.groups.get(groupUid) | One group | | client.groups.update(groupUid, { name }) | Rename a group | | client.groups.delete(groupUid) | Delete a group | | client.contacts.list(groupUid, { page }) | A page of a group's contacts | | client.contacts.create(groupUid, { phone, firstName, lastName, fields }) | Add a contact | | client.contacts.get(groupUid, contactUid) | One contact | | client.contacts.update(groupUid, contactUid, { phone, firstName, lastName, fields }) | Change a contact | | client.contacts.delete(groupUid, contactUid) | Delete a contact |

Sending

Numbers go in international format, such as 61404235133. A number containing letters is refused before anything is sent.

Several numbers: pass a list as recipient. They're sent during the request, so a long list takes longer, and you get one result per number.

Scheduling: set scheduleTime to YYYY-MM-DD HH:mm in your account's timezone.

Delivery status: a message's customer_status of Delivered means the carrier accepted it. It doesn't confirm the message reached the phone.

Trial accounts can only send to numbers they have verified.

Contacts

Adding a contact sends the group's welcome text if you've set one up on that group. fields holds your group's custom fields, by tag. Leave phone out of an update to keep the current number.

Errors

Every failure throws a DataFlowsError. This includes errors the API answers with HTTP 200, which many of them do.

import { DataFlows, DataFlowsError } from '@dataflows/sms';

try {
  await client.sms.send({ recipient: '61404235133', senderId: 'YOUR_SENDER_ID', message: 'Hello' });
} catch (error) {
  if (error instanceof DataFlowsError) {
    console.error(error.code, error.httpStatus, error.message);
  } else {
    throw error;
  }
}

| error.code | Meaning | |---|---| | api_error | DataFlows refused the request. error.message says why | | invalid_input | Something is missing or wrong. Nothing was sent to DataFlows | | rate_limited | Over 600 requests per minute for this token | | timeout | No answer in time. A send may still have gone out | | network_error | DataFlows couldn't be reached | | invalid_response | DataFlows sent back something unexpected |

Nothing is retried automatically, so a message can't go out twice because of this client. After a timeout, check client.sms.list() before you send again.

Options

const client = new DataFlows({
  apiToken: 'your-token', // defaults to DATAFLOWS_API_TOKEN
  timeout: 60000,         // milliseconds per request, this is the default
});

More

• Developer hub
• API reference
• OpenAPI spec
• Help: [email protected]

License

MIT