PHP SDK

PHP SDK

This library requires a minimum PHP version of 5.5

Installation

To install the PHP client to your project, we recommend using Composer.

composer require toucantext/php-sdk

Instantiating the SDK Client

Pass in the configuration to the client:

$config = [
  'username' => '{your_api_username}',
  'password' => '{your_api_password}'
];

$toucan = new \ToucanText\Client($config);

Using the Client

Getting all messages

To return a list of all your messages (both inbound and delivery receipts):

// return all your messages
$messages = $toucan->messages->all();

By default, this returns a maximum of 25 messages but does NOT acknowledge them. To override this, pass the following parameters (the first denotes whether to acknowledge messages; the second for the maximum number of messages to return):

// return 15 messages maximum and acknowledge them
$messages = $toucan->messages->all(true, 15);

Getting inbound messages or delivery receipts only

To return a list of inbound messages or delivery receipts:

// return only inbound messages
$messages = $toucan->messages->get('messagesOnly');

// return only delivery receipts
$receipts = $toucan->messages->get('dlrsOnly');

By default, this returns a maximum of 25 inbound messages or delivery receipts but does NOT acknowledge them. To override this, pass the following parameters (the second denotes whether to acknowledge messages; the third for the maximum number of messages to return):

// return 15 inbound messages maximum and acknowledge them
$messages = $toucan->messages->get('messagesOnly', true, 15);

// return 15 delivery receipts maximum and acknowledge them
$receipts = $toucan->messages->get('dlrsOnly', true, 15);

Sending a message

To send a message you, can call the following:

// send a message
$message = [
  'destinationAddress' => '{the_destination_address}',
  'message' => '{your_message}'
];

$toucan->messages->send($message);

You can also set a source address and request a delivery receipt:

// send a message with source address and request delivery receipt
$message = [
  'sourceAddress' => '{your_source_address}',
  'destinationAddress' => '{the_destination_address}',
  'message' => '{your_message}'
  'deliveryReceipt' => true
];

$toucan->messages->send($message);

Acknowledging delivery receipts and messages

When you retrieve your inbound messages or delivery receipts, there is a MbStorageId element within the response of the query. This ID can be used to acknowledge messages and delivery receipts individually.

To acknowledge a message or delivery receipt create an array with the ID’s to acknowledge and then call the following:

// array of message ID's to acknowledge
$messages = [
  245, 4564, 456
];

$toucan->messages->acknowledge($messages);

Handling Exceptions

Aside from errors that may occur due to the call, there may be other Exceptions thrown. To handle them, wrap your call in a try catch block:

try {
$messages = $toucan->messages->all();
}  catch (\Exception $e) {
// do something with $e
}