⚠️ DEPRECATED — Callr API v1 (JSON-RPC)

This SDK targets the legacy Callr JSON-RPC API (v1), which is deprecated and will be shut down on 30 June 2027. After that date this SDK will stop working.

➡️ Please migrate to the new Callr REST API v2.

• 📘 Migration guide (JSON-RPC → REST API v2): https://docs.callr.com/reference/migrating-from-json-rpc-v1
• 📣 What's new in REST API v2: https://docs.callr.com/changelog/rest-api-v2-is-here
• 🌐 REST API v2 base URL: https://api.callr.com/v2.0
• ✉️ Questions / migration help: support@callr.com

Your existing API credentials work with REST API v2 — no new keys required.

Official Callr REST API v2 SDKs are coming in the near future. In the meantime, you can call the REST API directly, or generate a client from the OpenAPI 3.1 spec (see Generate a REST API v2 client today below).

---

Generate a REST API v2 client today

An official Callr REST API v2 SDK for Node.js / TypeScript is coming soon. Until then, generate a fully-typed client from the OpenAPI 3.1 spec with OpenAPI Generator (requires v7.x+ for OpenAPI 3.1):

docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli generate \
  -g typescript-axios \
  -i https://api.callr.com/v2.0/openapi.json \
  -o /local/callr-v2-node

Authenticate with your API Key via the x-api-key header (or HTTP Basic: Account SID + API Key). The base URL https://api.callr.com/v2.0 is baked into the generated client — see its generated docs/ for the available endpoints.

---

sdk-nodejs

SDK in NodeJS for CALLR API For more examples see the the nodejs examples (https://github.com/THECALLR/examples-nodejs) repo.

Quick start

Install via NPM

npm install callr

Or get sources from Github

Authenticating for older SDK versions 1.x

• Please see the documentation here for how to authenticate using older 1.x versions of the SDK.

Different methods of authentication

When you initialise the callr api object with your chosen authentication method, you can also pass in any options like the following:

var options = {
    ...
}
var callr = require('callr');
var api = new callr.api(<authentication method>, options);
...

Init with login and password

var callr = require('callr');
var api = new callr.api(callr.loginPasswordAuth('login', 'password'));

Init with Api-Key token

• see https://www.callr.com/docs/api/services/api-key/

var callr = require('callr');
var api = new callr.api(callr.apiKeyAuth('987654321abcdef987654321abcdef987654321abcdef987654321abcdef987654321abcdef987654321abcdef987654321a'));

Init with User session token

• see https://www.callr.com/docs/api/services/session/

var callr = require('callr');
var api = new callr.api(callr.userSessionAuth('987654321abcdef987654321abcdef987654321a'));

Init with Login As

var callr = require('callr');
var options = {
    loginas: {
        type: 'user',       // available types: user, account
        target: '<login>'   // available targets: <login> for type user,
    }                       // <hash> for type account
}

var api = new callr.api(callr.loginPasswordAuth('login', 'password'), options);

Set Login As after Init

var callr = require('callr');
var api = new callr.api('login', 'password');
...

api.setLoginAs('user', '<login>'); // available types: user, account
                                   // available targets: <login> for type user,
                                   // <hash> for type account

API return value management

Set your success/error callback to get data returned by the API

api.call('system.get_timestamp').success(function(response) {
    // success callback
}).error(function(error) {
    // error callback
});

Usage

Sending SMS

Without options

api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', null).success(function(response) {
    // success callback
});

Method

• sms.send

Personalized sender

Your sender must have been authorized and respect the sms_sender format

api.call('sms.send', 'Your Brand', '+33123456789', 'Hello world!', null);

Method

• sms.send

If you want to receive replies, do not set a sender - we will automatically use a shortcode

api.call('sms.send', '', '+33123456789', 'Hello world!', null);

Method

• sms.send

Force GSM encoding

var optionSMS = { force_encoding: 'GSM' };

api.call('sms.send', '', '+33123456789', 'Hello world!', optionSMS);

Method

• sms.send

Objects

• SMS.Options

Long SMS (availability depends on carrier)

var text = 'Some super mega ultra long text to test message longer than 160 characters ' +
           'Some super mega ultra long text to test message longer than 160 characters ' +
           'Some super mega ultra long text to test message longer than 160 characters';
api.call('sms.send', 'SMS', '+33123456789', text, null);

Method

• sms.send

Specify your SMS nature (alerting or marketing)

var optionSMS = { nature: 'ALERTING' };

api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', optionSMS);

Method

• sms.send

Objects

• SMS.Options

Custom data

var optionSMS = { user_data: '42' };

api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', optionSMS);

Method

• sms.send

Objects

• SMS.Options

Delivery Notification - set webhook URL to receive notifications

var optionSMS = {
    webhook: {
        endpoint: 'http://yourdomain.com/webhook_endpoint'
    }
};

api.call('sms.send', 'SMS', '+33123456789', 'Hello world!', optionSMS).success(function(response) {
    // success callback
});

Method

• sms.send

Objects

• SMS.Options
• Webhook

Inbound SMS - set webhook endpoint to receive inbound messages (MO) and replies

Do not set a sender if you want to receive replies - we will automatically use a shortcode.

var optionSMS = {
    webhook: {
        endpoint: 'http://yourdomain.com/webhook_endpoint'
    }
};

api.call('sms.send', '', '+33123456789', 'Hello world!', optionSMS).success(function(response) {
    // success callback
});

Method

• sms.send

Objects

• SMS.Options
• Webhook

Get an SMS

api.call('sms.get', 'SMSHASH').success(function(response) {
    // success callback
});

Method

• sms.get

Objects

• SMS

---

REALTIME

Create a REALTIME app with a callback URL

var options = {
    url: 'http://yourdomain.com/realtime_callback_url'
};

api.call('apps.create', 'REALTIME10', 'Your app name', options).success(function(app) {
    // app.hash will be used for realtime call
});

Method

• apps.create

Objects

• REALTIME10
• App

Start a REALTIME outbound call

var target = {
    number: '+33132456789',
    timeout: 30
};

var callOptions = {
    cdr_field: '42',
    cli: 'BLOCKED'
};

api.call('dialr/call.realtime', 'appHash', target, callOptions).success(function(callID) {
    // success callback
}).error(function(error) {
    // error callback
});

Method

• dialr/call.realtime

Objects

• Target
• REALTIME10.Call.Options

Inbound Calls - Assign a phone number to a REALTIME app

api.call('apps.assign_did', 'appHash', 'DID ID').success(function(result) {
    //
});

Method

• apps.assign_did

Objects

• App
• DID

---

DIDs

List available countries with DID availability

api.call('did/areacode.countries').success(function(result) {
    //
});

Method

• did/areacode.countries

Objects

• DID.Country

Get area codes available for a specific country and DID type

api.call('did/areacode.get_list', 'US', null).success(function(result) {
    //
});

Method

• did/areacode.get_list

Objects

• DID.AreaCode

Get DID types available for a specific country

api.call('did/areacode.types', 'US').success(function(result) {
    //
});

Method

• did/areacode.types

Objects

• DID.Type

Buy a DID (after a reserve)

api.call('did/store.buy_order', 'OrderToken').success(function(result) {
    //
});

Method

• did/store.buy_order

Objects

• DID.Store.BuyStatus

Cancel your order (after a reserve)

api.call('did/store.cancel_order', 'OrderToken').success(function(result) {
    //
});

Method

• did/store.cancel_order

Cancel a DID subscription

api.call('did/store.cancel_subscription', 'DID ID').success(function(result) {
    //
});

Method

• did/store.cancel_subscription

View your store quota status

api.call('did/store.get_quota_status').success(function(result) {
    //
});

Method

• did/store.get_quota_status

Objects

• DID.Store.QuotaStatus

Get a quote without reserving a DID

api.call('did/store.get_quote', 0, 'GOLD', 1).success(function(result) {
    //
});

Method

• did/store.get_quote

*Objects/

• DID.Store.Quote

Reserve a DID

api.call('did/store.reserve', 0, 'GOLD', 1, 'RANDOM').success(function(result) {
    //
});

Method

• did/store.reserve

Objects

• DID.Store.Reservation

View your order

api.call('did/store.view_order', 'OrderToken').success(function(result) {
    //
});

Method

• did/store.buy_order

Objects

• DID.Store.Reservation

---

Conferencing

Create a conference room

var params = { open: true };
var access = [];

api.call('conference/10.create_room', 'room name', params, access).success(function(result) {
    //
});

Method

• conference/10.create_room

Objects

• CONFERENCE10
• CONFERENCE10.Room.Access

Assign a DID to a room

api.call('conference/10.assign_did', 'Room ID', 'DID ID');

Method

• conference/10.assign_did

Create a PIN protected conference room

var params = { open: true };
var access = [
    { pin: '1234', level: 'GUEST' },
    { pin: '4321', level: 'ADMIN', phone_number: '+33123456789' }
];

api.call('conference/10.create_room', 'room name', params, access).success(function(result) {
    //
});

Method

• conference/10.create_room

Objects

• CONFERENCE10
• CONFERENCE10.Room.Access

Call a room access

api.call('conference/10.call_room_access', 'Room Access ID', 'BLOCKED', true).success(function(result) {
    //
});

Method

• conference/10.call_room_access

---

Media

List your medias

api.call('media/library.get_list', null).success(function(result) {
    //
});

Method

• media/library.get_list

Create an empty media

api.call('media/library.create', 'name').success(function(media_id) {
    //
});

Method

• media/library.create

Upload a media

var media_id = 0;

api.call('media/library.set_content', media_id, 'text', 'base64_audio_data').success(function(result) {
    //
});

Method

• media/library.set_content

Use Text-to-Speech

var media_id = 0;

api.call('media/tts.set_content', media_id, 'Hello world!', 'TTS-EN-GB_SERENA', null).success(function(result) {
    //
});

Method

• media/tts.set_content

---

CDR

Get inbound or outbound CDRs

var from = 'YYYY-MM-DD HH:MM:SS';
var to = 'YYYY-MM-DD HH:MM:SS';

api.call('cdr.get', 'OUT', from, to, null, null).success(function(result) {
    //
});

Method

• cdr.get

Objects

• CDR.In
• CDR.Out

---

Calling

Broadcast messages to a target

var target = {
    number: '+33123456789',
    timeout: 30
};

var messages = [131, 132, 'TTS|TTS_EN-GB_SERENA|Hello world! how are you ? I hope you enjoy this call. good bye.'];

var options = {
    cdr_field: 'userData',
    cli: 'BLOCKED',
    loop: 2
};

api.call('calls.broadcast_1', target, messages, options).success(function(result) {
    //
});

Without options

var target = {
    number: '+33123456789',
    timeout: 30
};

var messages = [131, 132, 134];

api.call('calls.broadcast_1', target, messages, null).success(function(result) {
    //
});

Method

• calls.broadcast_1

Objects

• Target
• Calls.Broadcast1.Options

---

Fatal error management

try {
    api.call('sms.get', 'unknown hash');
} catch (e) {
    console.log('Error\n', e);
}

Authentication for older versions

• Deprecated method for authenticating with 1.x versions of the SDK.

For authenticating with older versions of the API SDK can be done the following way:

var callr = require('callr');
var api = new callr.api('login', 'password');
...

Or when passing options

var callr = require('callr');
var options = {
    loginas: {
        type: 'user',       // available types: user, account
        target: '<login>'   // available targets: <login> for type user,
    }                       // <hash> for type account
}

var api = new callr.api('login', 'password', options);
...

---