Sync API Client

The Sync API Client is a PHP package that exposes classes and methods for interacting with your hosted sim on Cecula Sync Cloud and Messaging Account via the Cecula Sync API.

Language: php

Table of Content

Getting Started

Requirements

  • Hosted SIM on Cecula Sync Cloud
  • PHP8.0 Installation

Hosting a SIM

Cecula Sync API Client uses hosted SIM to send and receive sms and calls. You could own a sim at Cecula Sync Farm either by purchasing on the Sync Platform or sending your existing sim.

See detailed information on how to host your sim to our mailing address.

Installation

Install Cecula Sync API Client using the Composer Dependency Management tool by running:

composer require cecula/sync-api-client

This will additionally install the package Cecula Sync Client requires: Ryan McCue’s rmccue/requests package. Once installation is done, proceed to configuration.

Configuration

Change directory to your project root directory. Navigate to vendor/cecula/sync-api-client and copy the .ceculasync.json.example file to your project's root directory. Rename the file .ceculasync.json.

You can do this on a unix shell by running the command below from your project's root directory:

cp vendor/cecula/sync-api-client/.ceculasync.json.example .ceculasync.json

Open and edit the .ceculasync.json file with your IDE or any text editor of your choice. This is what your configuration file should look like:

                        
{
    "apiKey": ""
}
                        
                    

The configuration file has a single attribute: the apiKey.

API Key

If you do not already have an API key, login to the Cecula Sync Platform. Navigate to Account > Settings. Select the API Key tab and copy your API Key.

SMS

Sending SMS

SyncSms::sendSMS(string $text, array $recipients ): object

This method sends sms to single or multiple recipients. Recipient number should be in international format. eg. +2349090000246

A successfully sent message will return status 1801 and a reports array which comprises of trackingId and recipient attribute for each mobile number.

Sample Request:

                        
use CeculaSyncApiClient\SyncSms;

$testMobile = "+2349090000246";
$syncSms = new SyncSms();
var_dump($syncSms->sendSMS("Hello Sync", [$testMobile]));
                        
                    

Output:

                        
object(stdClass)#21 (3) {
    status=>
    string(4) "1801"
    ["report"]=>
    array(1) {
        [0]=>
        object(stdClass)#17 (2) {
        [ "recipient" ]=>
        string(13) "2349090000246"
        [ "trackingId" ]=>
        int(38382)
        }
    }
    [ "response" ]=>
    string(10) "Successful"
}
                        
                    

Receiving SMS

SyncSMS::getUnreadSMS(): array

A call to this method fetches the most recent unread sms from the cecula sync service in descending order.

Sample Request:

                        
use CeculaSyncApiClient\SyncSms;

$syncSms = new SyncSms();
var_dump($syncSms->getUnreadSMS());
                        
                    

Output:

                        
array(5) {
    [0]=>
    object(stdClass)#26 (4) {
        ["originator"]=>
        string(13) "2349090000246"
        ["receiver"]=>
        string(11) "08176473712"
        ["text"]=>
        string(5) "Hello"
        ["timeReceived"]=>
        string(16) "2021/10/16 18:45"
    }
    [1]=>
    object(stdClass)#24 (4) {
        ["originator"]=>
        string(13) "2347034647749"
        ["receiver"]=>
        string(11) "08176473712"
        ["text"]=>
        string(8) "Trying you"
        ["timeReceived"]=>
        string(16) "2021/09/15 13:57"
    }
    ...
}
                        
                    

It is also possible to have the service forward incoming sms to you. In this case, you will have to setup a webhook for receiving inbound sms. Read about setting up webhook on Cecula Sync.

Checking Sent SMS Status

SyncSms::getSentMessageStatus(string $smsTrackingId ): object

This method uses the trackingId that was returned during the sendSMS method call to query for the status of the sent sms.

Sample Request:

                        
use CeculaSyncApiClient\SyncSms;

$syncSms = new SyncSms();
var_dump($syncSms->getSentMessageStatus("38382"));
                        
                    

Output:

                        
object(stdClass)#26 (6) {
    ["trackingId"]=>
    int(38382)
    ["originator"]=>
    string(11) "08176473712"
    ["recipient"]=>
    string(14) "+2349090000246"
    ["status"]=>
    string(9) "delivered"
    ["sendTime"]=>
    string(19) "2021-10-18 13:28:0"
    ["doneTime"]=>
    string(19) "2021-10-18 13:28:03"
}
                        
                    

For the comprehensive list of sms statuses refer to the Cecula Sync API Reference Guide.

Setting SMS Auto-Response Message

SyncSMS::setSMSAutoResponseText(string $text): object

An auto-response message is a programmed sms that will be sent as a reply when a number sends sms to your hosted sim. This method can be used to set Auto-Response messages from your code.

Sample Request:

                        
use CeculaSyncApiClient\SyncSms;

$syncSms = new SyncSms();
var_dump($syncSms->setSMSAutoResponseText("Thank you. I'll revert ASAP"));
                        
                    

Output:

                        
object(stdClass)#26 (1) {
    ["status"]=>
    string(7) "Success"
}
                        
                    

Call

Making Calls

SyncCall::dial(string $receiver ): object

This method is used to dial mobile phone numbers from your hosted sim. Since the service does not have any provision for transmitting voice, it terminates the call as soon as the dialled party answers the call.

The receiver argument passed in is the mobile number that should be dialled.

Sample Request:

                        
use CeculaSyncApiClient\SyncCall;

$syncCall = new SyncCall();
var_dump($syncCall->dial($testMobile));
                        
                    

Output:

                        
object(stdClass)#27 (4) {
    ["status"]=>
    string(4) "1801"
    ["receiver"]=>
    string(11) "09090000246"
    ["trackingId"]=>
    int(2020012708)
    ["message"]=>
    string(10) "Successful"
}
                        
                    

IMPORTANT: It is compulsory to prefix Non-Nigerian numbers with their country code.

Receiving Call Notification

SyncCall::getNewMissedCalls(): array

This method is used to query for the list of missed calls.

Sample Request:

                        
use CeculaSyncApiClient\SyncCall;

$syncCall = new SyncCall();
var_dump($syncCall->getNewMissedCalls());
                        
                    

Output:

                        
    array(10) {
        [0]=>
        object(stdClass)#26 (4) {
            ["originator"]=>
            string(11) "09090000246"
            ["receiver"]=>
            string(11) "08176473712"
            ["callDuration"]=>
            int(0)
            ["callTime"]=>
            string(19) "2021-10-15 08:57:30"
        }
        [1]=>
        object(stdClass)#24 (4) {
            ["originator"]=>
            string(11) "08119604551"
            ["receiver"]=>
            string(11) "08176473712"
            ["callDuration"]=>
            int(0)
            ["callTime"]=>
            string(19) "2021-09-25 17:19:26"
        }
        ...
    }
                        
                    

Alternatively, you could have the service push incoming call notifications to your app server. This can be done by setting up a fixed or dynamic webhook. You can setup a fixed webhook on Cecula Sync Platform or register a dynamic webhook at runtime.

Querying Dialled Call Status

SyncCall::getCallStatus(string $callTrackingId): object

This method allows you to query for the status of a dialled call using the trackingId that was returned when you called the dial method.

Sample Request:

                        
use CeculaSyncApiClient\SyncCall;

$syncCall = new SyncCall();
var_dump($syncCall->getCallStatus("2020012676"));
                        
                    

Output:

                        
object(stdClass)#26 (5) {
    ["originator"]=>
    string(11) "08176473712"
    ["receiver"]=>
    string(11) "09090000246"
    ["status"]=>
    string(12) "Not Answered"
    ["trackingId"]=>
    int(2020012708)
    ["callTime"]=>
    string(19) "2021/10/18 17:09:08"
}
                        
                    

For the comprehensive list of call statuses refer to the Cecula Sync API Reference Guide.

Setting Auto-Response Message

SyncCall::saveCallAutoResponseText(string $text): object

Considering that calls made to your hosted number will not be answered, this method makes it possible to program an automated response sms that would be sent to callers.

Sample Request:

                        
use CeculaSyncApiClient\SyncCall;

$syncCall = new SyncCall();
var_dump($syncCall->saveCallAutoResponseText("This is an SMS only number. Pls call us on  ..."));
                        
                    

Output:

                        
object(stdClass)#26 (1) {
    ["status"]=>
    string(7) "Success"
}
                        
                    

Account

Getting SIM Number

SyncAccount::getSimMSISDN(): object

This method is used to fetch your hosted sim subscriber mobile number. Useful in scenarios where you want to display the number.

Sample Request:

                        
use CeculaSyncApiClient\SyncAccount;

$syncAccount = new SyncAccount();
var_dump($syncAccount->getSimMSISDN());
                        
                    

Output:

                        
    object(stdClass)#26 (1) {
        ["msisdn"]=>
        string(11) "08176473712"
    }
                        
                    

Checking Balance

SyncAccount::getCeculaBalance(): object

This method returns your Cecula messaging account balance.

Sample Request:

                        
use CeculaSyncApiClient\SyncAccount;

$syncAccount = new SyncAccount();
var_dump($syncAccount->getCeculaBalance());
                        
                    

Output:

                        
object(stdClass)#26 (1) {
    ["balance"]=>
    float(9322.7)
}
                        
                    

Getting Subscription Status

SyncAccount::getSubscriptionStatus(): object

This method can be invoked at runtime to check the status of your Cecula Sync subscription.

Sample Request:

                        
use CeculaSyncApiClient\SyncAccount;

$syncAccount = new SyncAccount();
var_dump($syncAccount->getSubscriptionStatus());
                        
                    

Output:

                        
object(stdClass)#26 (3) {
    ["subscriptionStatus"]=>
    string(6) "ACTIVE"
    ["subscriptionPlan"]=>
    NULL
    ["expiryDate"]=>
    string(0) ""
}
                        
                    

Registering Dynamic Webhook

SyncAccount::setDynamicWebhook(string $url, string $clientMsisdn, string $verificationType, int $validityPeriod ): object

This method is used for registering dynamic webhook - for forwarding of incoming sms or call notification at runtime.

url
The webhook uniform resource location where Cecula Sync will forward incoming call data to.
clientMsisdn
Cecula sync will listen for call or sms from this number. When call arrives it forwards to the url specified.
verificationType
This should be set to value of SMS or CALL depending on the use case
validityPeriod
This parameter defines the amount of time service should wait for the call/sms to arrive. If call/sms is not received during this time, the dynamic webhook is removed.

Sample Request:

                        
use CeculaSyncApiClient\SyncAccount;

$syncAccount = new SyncAccount();
var_dump($syncAccount->setDynamicWebhook("https://bookdown.ng/lab", "08050209037", "CALL", 30));
                        
                    

Output:

                        
object(stdClass)#26 (1) {
    ["status"]=>
    string(10) "successful"
}
                        
                    

Refreshing SIM

SyncAccount::refreshSIM(): object

This method is used to reboot the sim, in event where attempts to send sms or call to the sim fails.

Sample Request:

                        
use CeculaSyncApiClient\SyncAccount;

$syncAccount = new SyncAccount();
var_dump($syncAccount->refreshSIM());
                        
                    

Output:

                        
object(stdClass)#26 (2) {
    ["status"]=>
    int(1801)
    ["message"]=>
    string(10) "Successful"
}
                        
                    

Get SIM Status

SyncAccount::getSimStatus(): object

This method is used to query the status of a hosted sim.

Sample Request:

                        
use CeculaSyncApiClient\SyncAccount;

$syncAccount = new SyncAccount();
var_dump($syncAccount->getSimStatus());
                        
                    

Output:

                        
object(stdClass)#26 (1) {
    ["status"]=>
    string(5) "READY"
}
                        
                    

Others

Response Codes & Meanings

The complete list of response codes returned by this SDK and their meanings is managed at the Cecula Sync API Reference Documentation.

Getting Started
SMS
Call
Account
Others