Skip to content

Latest commit

 

History

History
394 lines (299 loc) · 11.1 KB

sms.md

File metadata and controls

394 lines (299 loc) · 11.1 KB
Raw

The SMS client

The SMS client wraps the SMS section of 46elks.se docs

Available services

Dispatcher

The dispatcher service handles outgoing SMS and MMS. You can access the services in a couple of ways.

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');
// Here are some ways you can access the SMS dispatcher
$SMS = $Php46ElksClient->sms()->SMSDispatcher();
$SMS = $Php46ElksClient->sms()->dispatcher(); // default is sms
$SMS = $Php46ElksClient->sms()->dispatcher('sms');
// for MMS
$MMS = $Php46ElksClient->sms()->MMSDispatcher();
$MMS = $Php46ElksClient->sms()->dispatcher('mms'); // default is sms

Send an SMS

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$SMS = $Php46ElksClient->sms()->SMSDispatcher();

$SMS
    ->from('Php46Elks')
    ->recipient('+467EnterYourNumberHere')
    ->content('This is a text message!')
    ->send();

Send an MMS

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$MMS = $Php46ElksClient->sms()->MMSDispatcher();

$MMS
    ->from('<valid number for MMS>')
    ->recipient('+467yourNumber')
    ->image('https://i.imgur.com/M8XL4Wq.png')
    ->content('Optional text')
    ->send();

Send to multiple recipients

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$SMS = $Php46ElksClient->sms()->SMSDispatcher();

$SMS
    ->from('Php46Elks') 
    ->recipient('+46Number1')
    ->recipient('+46Number2')
    ->recipient('+46Number3')
    ->content('Hello!')
    ->send();

// alternative way

$SMS
    ->from('Php46Elks') 
    ->setRecipients(['+46Number1', '+46Number2', '+46Number3'])
    ->content('Hello!')
    ->send();

Lines and content

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$SMS = $Php46ElksClient->sms()->SMSDispatcher();

$SMS
    ->from('Php46Elks') 
    ->setRecipients(['+46Number1', '+46Number2', '+46Number3'])
    ->line('First line')
    ->line('Second line')
    ->line('')// new line
    ->line('Fourth line')
    ->send();

// alternative way

$SMS
    ->from('Php46Elks') 
    ->setRecipients(['+46Number1', '+46Number2', '+46Number3'])
    ->setLines([
        'First line',
        'Second line',
        '', // new line
        'Fourth line'
    ])  
    ->send();

Send flash messages / Push notifications

This feature only works for SMS

Flash messages will be displayed immediately upon arrival and not stored.

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$SMS = $Php46ElksClient->sms()->SMSDispatcher();

$SMS
    ->from('Php46Elks') 
    ->flash()
    ->recipient('+46number')
    ->line('Hello')
    ->line('Here is your code')
    ->line('ABC123')
    ->send();

Delivery webhooks

To receive status updates for your sent SMS or MMS, you want to use the whendelivered option to your messages. To handle incoming DLRs check out the next chapter Delivery reports (DLRs)

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$SMS = $Php46ElksClient->sms()->SMSDispatcher();

$SMS
    ->from('Php46Elks') 
    ->recipient('+46number')
    ->line('Hello did you receive this message?')
    ->whenDelivered('https://yourapp.io/dlr') // This webhook URL will receive a POST request every time the delivery status changes. See "Receive delivery reports" to handle these events
    ->send();

Delivery reports (DLRs)

The DLR service handles SMS and MMS SMS Delivery Reports (DLRs).

Because handling DLRs does not require authentication to 46elks API, we could access this service in two different ways.

use Tarre\Php46Elks\Clients\SMS\Services\SMSDLRService;
use Tarre\Php46Elks\Client as Php46ElkClient;

// Via the Php46ElkClient
$Php46ElksClient = new Php46ElkClient('username', 'password');
$dlr = $Php46ElksClient->sms()->dlr();

// Without using the client
$dlr = new SMSDLRService;

The is done for convenience sake. All examples will be using the first method to maintain continuity.

Receive delivery reports

use Tarre\Php46Elks\Clients\SMS\Resources\DeliveryReport;
use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$dlr = $Php46ElksClient->sms()->dlr();

$dlr->handleRequest(function (DeliveryReport $SMS) {
    print_r([
        'id' => $SMS->id(),
        'status' => $SMS->status(),
        'delivered' => $SMS->delivered(),
    ]);
});

Notes

  • $_REQUEST is used to fetch the request data that 46elks sends, it can be overridden by passing another array as the second parameter of handleRequest

Receiver

The receiver service handles incoming SMS and MMS sent by 46elks.

Because receiving messages does not require authentication to 46elks API, we could access this service in two different ways.

use Tarre\Php46Elks\Client as Php46ElkClient;
use Tarre\Php46Elks\Clients\SMS\Services\SMSReceiverService;

// Via the Php46ElkClient
$Php46ElksClient = new Php46ElkClient('username', 'password');
$receiver = $Php46ElksClient->sms()->receiver();

// Without using the client
$receiver = new SMSReceiverService;

The is done for convenience sake. All examples will be using the first method to maintain continuity.

Receive an SMS or MMS

  • $_REQUEST is used to handle the request data that 46elks sends, it can be overridden by passing another key->val array as the second parameter of handleRequest
  • If the Message is an SMS you can reply to the sender by returning $SMS->reply('Thanks for the text!')
use Tarre\Php46Elks\Clients\SMS\Resources\Message;
use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$receiver = $Php46ElksClient->sms()->receiver();

$receiver->handleRequest(function (Message $SMS) {
    print_r([
        'direction' => $SMS->direction(),
        'id' => $SMS->id(),
        'from' => $SMS->from(),
        'to' => $SMS->to(),
        'created' => $SMS->created(),
        'message' => $SMS->message(),
        'images' => $SMS->images(),
        'cost' => $SMS->cost() 
    ]);
});

Reply to SMS

Instead of using the SMS dispatcher to reply to the message. You could simply return $SMS->reply('text') to reply to the sender

use Tarre\Php46Elks\Clients\SMS\Resources\Message;
use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$receiver = $Php46ElksClient->sms()->receiver();

$receiver->handleRequest(function (Message $SMS) {
    // ... 
    return $SMS->reply('Thank you!');
});

Forward SMS

Besides replying to SMS you could also forward the message. With optional suffixes and prefixes

use Tarre\Php46Elks\Clients\SMS\Resources\Message;
use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$receiver = $Php46ElksClient->sms()->receiver();

$receiver->handleRequest(function (Message $SMS) {
    // ... 
    return $SMS->forward('+46928398213', 'This message was forwarded: ', 'Have a nice day!');
});

History

This is how you fetch SMS history from 46elks.

Notes

  • Log retention is set in your account settings

Get all history

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$history = $Php46ElksClient->sms()->history('sms'); // sms or mms

$paginator = $history->get(); 

foreach($paginator->getData() as $SMS){
    print_r([
        'direction' => $SMS->direction(),
        'id' => $SMS->id(),
        'from' => $SMS->from(),
        'to' => $SMS->to(),
        'created' => $SMS->created(),
        'message' => $SMS->message(),
        'images' => $SMS->images(),
        'cost' => $SMS->cost() 
    ]);
}

Filter requests

There exists a couple of filter settings you can use to search and narrow your results

  • start($date) Retrieve SMS before this date.
  • end($date) Retrieve SMS after this date.
  • limit($number) Limit the number of results on each page.
  • to($e164Number) Filter on recipient.

These filters MUST to be used before get is invoked. After get has been invoked, you can use next() to get the next "page"

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$history = $Php46ElksClient->sms()->history('sms'); // sms or mms

$paginator = $history
    ->to('+467012232343')
    ->start('2020-02-14T09:52:07.302000')
    ->end('2020-02-15T09:52:07.302000')
    ->get(); 

foreach($paginator->getData() as $SMS){
    print_r([
        'direction' => $SMS->direction(),
        'id' => $SMS->id(),
        'from' => $SMS->from(),
        'to' => $SMS->to(),
        'created' => $SMS->created(),
        'message' => $SMS->message(),
        'images' => $SMS->images(),
        'cost' => $SMS->cost() 
    ]);
}

Get single

To retrieve a single resource you can invoke the getById instead of get

use Tarre\Php46Elks\Client as Php46ElkClient;
// Initialize client
$Php46ElksClient = new Php46ElkClient('username', 'password');

$history = $Php46ElksClient->sms()->history('sms'); // sms or mms

$SMS = $history->getById('enter sms or MMS id here');

print_r([
    'direction' => $SMS->direction(),
    'id' => $SMS->id(),
    'from' => $SMS->from(),
    'to' => $SMS->to(),
    'created' => $SMS->created(),
    'message' => $SMS->message(),
    'images' => $SMS->images(),
    'cost' => $SMS->cost() 
]);