README

⚠️ 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 PHP 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 php \
  -i https://api.callr.com/v2.0/openapi.json \
  -o /local/callr-v2-php

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.

PHP SDK for CALLR API

JSON-RPC 2.0 PHP class, to use with CALLR API.

• API documentation: http://www.callr.com/docs/

• SDK Installation guide: see INSTALLING.php.md

• Example projects: https://github.com/THECALLR/examples-php

• JSON-RPC 2.0 Specification: http://www.jsonrpc.org/specification

• Easy to use Client class, built for PHP 5.4+

• Can be used for both the API and Real-time calls

• Requires: php5-curl

Composer

You should use Composer (https://getcomposer.org/) to manage your PHP dependencies. If you do not have a composer.json file yet, create one at the root of your project, download Composer, and launch composer update.

The composer.json file should look like this:

{
  "require": {
    "callr/sdk-php": "^0.11"
  }
}

Add all the libraries you need in composer.json. Do not forget to run composer update each time you edit the file.

Then you just need to include one file in your code:

<?php

require 'vendor/autoload.php';

Usage

Init

$api = new CALLR\API\Client;

// using login + password (note ; that is to be deprecated)
$api->setAuth(new CALLR\API\Authentication\LoginPasswordAuth('username', 'password'));

// If you are using a long-term token ("api-key"), here is what you need to do ;
$api->setAuth(new CALLR\API\Authentication\ApiKeyAuth('your-api-key'));

Login-as

If you want to log in as another sub-customer or sub-user (one you have access to), you can call the logAs method on the chosen authenticator :

$auth = new CALLR\API\Authentication\LoginPasswordAuth('username', 'password');
$auth = $auth->logAs('User', 'username_2');

$api = new CALLR\API\Client;
$api->setAuth($auth);

Available authenticators are the classic login / password (sent through a BASIC http request) or the Api-Key. Both supports the Login-As feature.

Sending SMS

Without options

$from = 'SMS';
$to   = '+33123456789';
$text = 'Hello, SMS world!';

$result = $api->call('sms.send', [$from, $to, $text, null]);

Method

• sms.send

Personalized sender

Your sender must have been authorized and respect the sms_sender format

$from = 'Your Brand';
$to   = '+33123456789';
$text = 'Hello, SMS world!';

$result = $api->call('sms.send', [$from, $to, $text, null]);

Method

• sms.send

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

$from = '';
$to   = '+33123456789';
$text = 'Hello, SMS world!';

$result = $api->call('sms.send', [$from, $to, $text, null]);

Method

• sms.send

Force GSM encoding

The default behaviour is to send your SMS with GSM 7-bit encoding. However, if your text contains a character that is not in the GSM 7-bit charset (Basic Character Set), we will send it as 16-bit UCS-2 (UNICODE) - using 2 bytes per character.

You can however force the encoding to be used at any time, using the force_encoding property.

If you force a GSM encoding, we will try to convert non-GSM characters to GSM ones. « becomes ", € becomes e, etc. The full mapping is available when calling the method sms.get_gsm_charset_mapping.

Please note that whatever the encoding forced or used, you always send your text as a JSON string to our API, without any special processing. The charset is applied in our platform before sending to the carriers.

$from = '';
$to   = '+33123456789';
$text = 'Hello, SMS world!';

$options = new stdClass;
$options->force_encoding = 'GSM'; // or 'UNICODE'

$result = $api->call('sms.send', [$from, $to, $text, $options]);

Method

• sms.send

Objects

• SMS.Options

Long SMS (availability depends on carrier)

We automatically handle concatenated SMS. The number of SMS parts billed will be set on the parts property of the SMS object. The object can be sent to you using Webhooks.

If your SMS is GSM 7-bit encoded:

• If it's equals or less than 160 characters, it counts as 1 SMS.
• If it's more than 160 characters, the split is done every 153 characters.

If your SMS is UNICODE encoded:

• If it's equals or less than 70 characeters, it counts as 1 SMS.
• If it's more than 70 characters, the split is done every 67 characters.

$from = 'SMS';
$to   = '+33123456789';
$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';

$result = $api->call('sms.send', [$from, $to, $text, null]);

Method

• sms.send

Specify your SMS nature (alerting or marketing)

$from = 'SMS';
$to   = '+33123456789';
$text = 'Hello, SMS world!';

$options = new stdClass;
$options->nature = 'ALERTING'; // or 'MARKETING'

$result = $api->call('sms.send', [$from, $to, $text, $options]);

Method

• sms.send

Objects

• SMS.Options

Custom data

$from = 'SMS';
$to   = '+33123456789';
$text = 'Hello, SMS world!';

$options = new stdClass;
$options->user_data = '42';

$result = $api->call('sms.send', [$from, $to, $text, $options]);

Method

• sms.send

Objects

• SMS.Options

Delivery Notification - set URL to receive notifications

To receive delivery notifications (DLR), you have to subscribe to the webhook sms.mt.status_update (see below).

Method

• sms.send
• webhooks.subscribe

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

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

To receive inbound messages (MO), you have to subscribe to the webhook sms.mo (see below).

Method

• webhooks.subscribe

Get an SMS

$result = $api->call('sms.get', ['SMSHASH']);

Method

• sms.get

Objects

• SMS

Webhooks

See our online documentation: http://www.callr.com/docs/webhooks/

Subscribe to webhooks

$type = 'sms.mt.status_update';
$endpoint = 'http://yourdomain.com/webhook_url';

$result = $api->call('webhooks.subscribe', [ $type, $endpoint, null ]);

Method

• webhooks.subscribe

Objects

• Webhook

List available webhooks

$result = $api->call('webhooks.get_event_types');

Method

• webhooks.get_event_types

REALTIME

Create a REALTIME app with a callback URL

App name format

$options = new stdClass;
$options->url = 'http://yourdomain.com/realtime_callback_url';

$result = $api->call('apps.create', ['REALTIME10', 'Your app name', $options]);

Method

• apps.create

Objects

• REALTIME10
• App

Start a REALTIME outbound call

$target = new stdClass;
$target->number = '+33132456789';
$target->timeout = 30;

$callOptions = new stdClass;
$callOptions->cdr_field = '42';
$callOptions->cli = 'BLOCKED';

$result = $api->call('calls.realtime', ['appHash', $target, $callOptions]);

Method

• calls.realtime

Objects

• Target
• REALTIME10.Call.Options

Inbound Calls - Assign a phone number to a REALTIME app

$result = $api->call('apps.assign_did', ['appHash', 'DID ID']);

Method

• apps.assign_did

Objects

• App
• DID

DIDs

List available countries with DID availability

$result = $api->call('did/areacode.countries');

Method

• did/areacode.countries

Objects

• DID.Country

Get area codes available for a specific country and DID type

$result = $api->call('did/areacode.get_list', ['US', null]);

Method

• did/areacode.get_list

Objects

• DID.AreaCode

Get DID types available for a specific country

$result = $api->call('did/areacode.types', ['US']);

Method

• did/areacode.types

Objects

• DID.Type

Buy a DID (after a reserve)

$result = $api->call('did/store.buy_order', ['OrderToken']);

Method

• did/store.buy_order

Objects

• DID.Store.BuyStatus

Cancel your order (after a reserve)

$result = $api->call('did/store.cancel_order', ['OrderToken']);

Method

• did/store.cancel_order

Cancel a DID subscription

$result = $api->call('did/store.cancel_subscription', ['DID_ID']);

Method

• did/store.cancel_subscription

View your store quota status

$result = $api->call('did/store.get_quota_status');

Method

• did/store.get_quota_status

Objects

• DID.Store.QuotaStatus

Get a quote without reserving a DID

$result = $api->call('did/store.get_quote', [0, 'GOLD', 1]);

Method

• did/store.get_quote

*Objects/

• DID.Store.Quote

Reserve a DID

$result = $api->call('did/store.reserve', [0, 'GOLD', 1, 'RANDOM']);

Method

• did/store.reserve

Objects

• DID.Store.Reservation

View your order

$result = $api->call('did/store.view_order', ['OrderToken']);

Method

• did/store.buy_order

Objects

• DID.Store.Reservation

Conferencing

Create a conference room

$params = new stdClass;
$params->open = true;

$access = [];

$result = $api->call('conference/10.create_room', ['room name', $params, $access]);

Method

• conference/10.create_room

Objects

• CONFERENCE10
• CONFERENCE10.Room.Access

Assign a DID to a room

$result = $api->call('conference/10.assign_did', ['Room ID', 'DID ID']);

Method

• conference/10.assign_did

Create a PIN protected conference room

$params = new stdClass;
$params->open = true;

$access = [
    (object)['pin' => '1234', 'level' => 'GUEST'],
    (object)['pin' => '4321', 'level' => 'ADMIN', 'phone_number' => '+33123456789']
];

$result = $api->call('conference/10.create_room', ['room name', $params, $access]);

Method

• conference/10.create_room

Objects

• CONFERENCE10
• CONFERENCE10.Room.Access

Call a room access

$result = $api->call('conference/10.call_room_access', ['Room Access ID', 'BLOCKED', true]);

Method

• conference/10.call_room_access

Media

List your medias

$result = $api->call('media/library.get_list', [null]);

Method

• media/library.get_list

Create an empty media

$result = $api->call('media/library.create', ['name']);

Method

• media/library.create

Upload/Import a media

$webhook_url = 'http://yourdomain.com/webhook_url';
$audio_data = base64_encode(file_get_contents('/tmp/audio.mp3'));

$result = $api->call('media.import_file_from_base64_async', [$audio_data, $webhook_url]);

Method

• media.import_file_from_base64_async

Use Text-to-Speech

$media_id = 0;

$result = $api->call('media/tts.set_content', [$media_id, 'Hello world!', 'TTS_EN-GB_SERENA', null]);

Method

• media/tts.set_content

CDR

Get inbound or outbound CDRs

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

$result = $api->call('cdr.get', ['OUT', $from, $to, null, null]);

Method

• cdr.get

Objects

• CDR.In
• CDR.Out

Broadcast messages to a target

$target = new stdClass;
$target->number = '+33123456789';
$target->timeout = 30;

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

$options = new stdClass;
$options->cdr_field = 'userData';
$options->cli = 'BLOCKED';
$options->loop = 2;

$result = $api->call('calls.broadcast_1', [$target, $messages, $options]);

Without options

$target = new stdClass;
$target->number = '+33123456789';
$target->timeout = 30;

$messages = [131, 132, 134];

$result = $api->call('calls.broadcast_1', [$target, $messages, null]);

Method

• calls.broadcast_1

Objects

• Target
• Calls.Broadcast1.Options