ToucanText SMS APIs

using ToucanText.Api.SenderApi;

MessageSender messageSender = new MessageSender("userName", "password");

MessageSender messageSender = new MessageSender("userName", "password");
messageSender.SendMessage("sourceAddress", "destinationAddress", "message");

C# Asynchronous

Add the API

In C# you should add the following to any .cs files that need to use the API.

using ToucanText.Api.SenderApi;

Run the Code

To use the API create a new instance of the MessageSender(); object. Replace the user name and password with your Toucan API user name and password.

MessageSender messageSender = new MessageSender("userName", "password");

Parameters

Get the Code

To send a message use the SendMessage(); method. The sender address can be an alphanumeric or numeric (depending on the country).

async public void SubmitPage(String c, String message)
{
MessageSender messageSender = new MessageSender("userName", "password");
var result = await messageSender.SendMessageAsync("sourceAddress", "destinationAddress", "message");
}

async private void button1_Click(object sender, EventArgs e)
{
MessageSender messageSender = new MessageSender("userName", "password");
var result = await messageSender.SendMessageAsync("sourceAddress", "destinationAddress","message");
}

ToucanText API Requirements

Target Application

The ToucanText .NET API requires a minimum of .NET Framework 4.5 or .NET 10 to operate.

HTTP API

The basic construct of our API is as follows.

Parameters

Get the Code

The DESTADDR parameter should be the destination number to send the message to in the format cc = Country code and nnnnnnnnnn is the phone number (with the leading 0 removed if present) i.e. 447123456789

https://api.toucantext.com/bin/send.xml?USERNAME=apiusername&PASSWORD=apipassword&DESTADDR=ccnnnnnnnnnn&MESSAGE=messagecontent

Set the sender in a call

It is also possible to set the sender in a call, to do this you pass the SOURCEADDR in the URL. The SOURCEADDR can either be passed as a correctly formatted number (in the same format as the DESTADDR) or can be specified as alphanumeric text.

Numeric

https://api.toucantext.com/bin/send.xml?USERNAME=apiusername&PASSWORD=apipassword&SOURCEADDR=ccnnnnnnnnnn&DESTADDR=ccnnnnnnnnnn&MESSAGE=messagecontent

Alphanumeric

https://api.toucantext.com/bin/send.xml?USERNAME=apiusername&PASSWORD=apipassword&DESTADDR=alphanumerictext&MESSAGE=messagecontent

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
}

REST API

Send and receive messages using the ToucanText REST API. The full interactive reference for every endpoint is available in Swagger.

Authentication

The API uses HTTP Basic authentication. Use your ToucanText account ID as the username and your API token as the password.

Send a message

Send a message to one or more recipients by posting a JSON body to:

POST https://ttapi.toucantext.com/Message

Parameters

Example

curl -u "ACCOUNT_ID:API_TOKEN" -X POST https://ttapi.toucantext.com/Message \
  -H "Content-Type: application/json" \
  -d '{"senderID": "ToucanText", "recipientList": ["447123456789"], "messageDetail": "Hello from ToucanText"}'

The response contains a results array and your account balance. Check the status and statustext of each result to confirm the outcome for each recipient; each result also includes the msgid assigned to the message.

Retrieve messages and delivery reports

Retrieve inbound messages and delivery reports from your account's inbound queue:

GET https://ttapi.toucantext.com/Message

Parameters

Example

curl -u "ACCOUNT_ID:API_TOKEN" \
  "https://ttapi.toucantext.com/Message?MaxMessageCount=25&AckMessages=False"

The response contains a messageList array. Each entry includes the sourceAddr, destAddr, messageContents and arrivalTimeUTC. Delivery reports have dlr set to true, with dlrOriginalMessageId identifying the original message.