Node.js SDK

Official Devotel Node.js/TypeScript SDK quickstart

Node.js SDK

The official Devotel Node.js SDK provides a fully typed client for the Devotel API. Built with TypeScript, it supports all Devotel services — messaging, voice, agents, flows, numbers, and verify.

Installation

npm install @devotel/sdk

Or with other package managers:

pnpm add @devotel/sdk
yarn add @devotel/sdk

Quick Start

import { Devotel } from '@devotel/sdk';

const orbit = new Devotel({
  apiKey: 'dv_live_sk_your_key_here',
});

// Send an SMS
const message = await orbit.messages.send({
  channel: 'sms',
  to: '[phone]',
  body: 'Hello from Orbit!',
});

console.log(message.data.message_id); // msg_abc123

Messaging

// Send WhatsApp template
const waMessage = await orbit.messages.send({
  channel: 'whatsapp',
  to: '[phone]',
  type: 'template',
  template: {
    name: 'order_confirmation',
    language: 'en',
    components: [
      { type: 'body', parameters: [{ type: 'text', text: 'ORD-12345' }] },
    ],
  },
});

// Send Email
const email = await orbit.messages.send({
  channel: 'email',
  to: '[e-mail]',
  from: '[e-mail]',
  subject: 'Welcome!',
  html: '<h1>Welcome to Acme</h1>',
});

Voice

// Make an outbound call
const call = await orbit.voice.calls.create({
  to: '[phone]',
  from: '[phone]',
  webhookUrl: 'https://yourapp.com/webhooks/voice',
});

// Connect to an AI agent
const agentCall = await orbit.voice.calls.create({
  to: '[phone]',
  from: '[phone]',
  agentId: 'agent_support_bot',
});

// Retrieve call details
const callDetails = await orbit.voice.calls.get(call.data.id);

Verify

// Send OTP
const verification = await orbit.verify.send('[phone]', 'sms');

// Check OTP
const result = await orbit.verify.check('[phone]', '482901');

console.log(result.data.status); // 'approved'

Webhooks

// Verify webhook signature in an Express handler
import { verifyWebhookSignature } from '@devotel/sdk';

app.post('/webhooks/orbit', (req, res) => {
  const isValid = verifyWebhookSignature(
    req.rawBody,
    req.headers['x-devotel-signature'],
    'whsec_your_secret',
  );

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = req.body;
  switch (event.type) {
    case 'message.delivered':
      // Handle delivery confirmation
      break;
    case 'call.completed':
      // Handle call completion
      break;
  }

  res.status(200).json({ received: true });
});

Error Handling

import { Devotel, OrbitApiError } from '@devotel/sdk'

try {
  await orbit.messages.send({ channel: 'sms', to: 'invalid', body: 'Hi' });
} catch (error) {
  if (error instanceof OrbitApiError) {
    console.error(error.code);       // 'INVALID_PHONE_NUMBER'
    console.error(error.statusCode); // 422
    console.error(error.message);    // 'The to field must be a valid E.164 phone number'
  }
}

Configuration

Option	Type	Default	Description
apiKey	string	—	Your Devotel API key (required)
baseUrl	string	https://orbit-api.devotel.io/api/v1	API base URL

Requirements

• Node.js 18 or later
• TypeScript 5.0+ (recommended but not required)