Send a message to (one or) multple contacts or to (one or) multiple groups
Send a message - Basic Usage
You can now send messages to multiple contacts OR to multiple contact groups at once. And you get back a query ID for every contact you send to.
PHP POST
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.smsjuice.com/send");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_HEADER, FALSE);
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{
"key":"gghs68y",
"secret":"e5087bac141897ab37af89bae8d5dc1447ab4efe",
"from":"Nyaradzo",
"message":"Hello world",
"recipientType":"numbers",
"to":[
"277790839483", "263778394993"
]
}');
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json"));
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
PHP SDK
include("../class/Message.class.php");
include("../TextMessagingService.php");
//creates a new message object with your key and secret
$m = new Message("key", "secret");
//FROM address
$m->setSender("Restaurant");
//Recipient Type. Options - "groups" OR "numbers". Default is 'numbers' if not manually set
$m->setRecipientType("numbers");
//Set a "to" recipient list with an array of numbers
$m->setRecipientList(array("447900239984", "447900392828"));
//Add a contact phone number to the recipient list
$m->addToRecipientList("447900385486");
//content to send
$m->setMessage("Hello world");
//Send the message and get the response from the server
$result = TextMessagingService::sendMessage($m);
echo $result;
Parameters
| Parameter | Description | Required |
|---|---|---|
| key | account authentication key | Required |
| secret | account authentication secret | Required |
| from | sender address for the message. This must be no longer than 11 alphanumeric characters or 13 numeric characters. | Required |
| to | phone number(s) of the recipient(s) OR group names of contact groups on your SMSJuice account. If it's phone numnbers they have to start with the international code. Plus sign is optional Acceptable format examples: 447900000000 OR +447900000000. The group names can be alphanumeric |
Required |
| message | the message to send to the recipient. Message can be up to 765 characters long, which equates to 5 text messages. | Required |
| encoding | the character encoding that the message is in Default value = 0 (GSM3.38). For unicode use 8. For more info see https://en.wikipedia.org/wiki/Character_encoding |
Optional |
| schedule | the time you want the message to be sent Format : Y-m-d H:i |
Optional |
| expiry | the time that you want the message to expire if not delivered. Format : Y-m-d H:i |
Optional |
| reciptientType | Default : 'numbers' Options : 'numbers', 'groups'. You set this parameter to change the type of recipients you want to send to. If you wish to send to groups on your account then you need to change it to 'groups' AND put group names (instead of phone numbers) in the 'to' field/parameter. If you wish to send to single recipients/contact numbers then you need to change it to 'numbers' AND put the recipients' phone numbers in the 'to' field/parameter. |
Optional |
| receipt | Indicator if a receipt is needed for the message. The receipt will be sent to the callback URL you provide in settings Default value = 0 |
Optional |
Response
{
"submit":"success",
"error":"",
"total_recipients":3,
"messages_used_per_recipient":1,
"message":"Hello world",
"your_reference":"",
"from":"Nyaradzo",
"info":"",
"message_query_ids":[
{
"to":"447900385486",
"message_id":"lng-71jirzh56ero7256ss"
},
{
"to":"447000000000",
"message_id":"lng-71jirzh56ero7256ss"
},
{
"to":"447900392828",
"message_id":"lng-71jirzh56f02sz256ss"
}
],
"invalid_numbers":[
],
"schedule":"2016-08-17 23:33",
"expiry":"2016-08-19 23:33"
}
Success Response Codes
| Success Response | Description |
|---|---|
| submit | The status of the submission. In this case it's 'success' |
| error | Any possible errors. EMpty in the case os a successful submission |
| total_recipients | Total number of recipients to whom the message was sent |
| messages_used_per_recipient | Number of message credits used per recipient (depends on the length of the message) |
| message | Message sent to recipient(s) |
| your_reference | RESERVED |
| from | The ID the message was sent from |
| info | Any other information and warnings |
| message_query_ids | IDs of the messages sent to the correspondint recipients. You use this message_query_id to query if a message has been delivered |
| invalid_numbers | Any recipient numbers considered by the system as invalid |
| schedule | The date when the message was sent |
| expiry | The date when the message is deemed useless if not yet delivered to recipient |
| messages_used | Number of SMS messages (or credits) used up by your message. Usually is more than 1 when your message is longer than 160 characters (or 70bytes unicode) |
Errors
{
"submit":"failed",
"error":"invalid_credentials",
"total_recipients":0,
"messages_used_per_recipient":0,
"message":null,
"your_reference":"",
"from":null,
"info":"",
"message_query_ids":[
],
"invalid_numbers":[
],
"schedule":null,
"expiry":null
}
Error Response Codes
| Error Response | Description |
|---|---|
| invalid_credentials | Invalid API key and/or secret |
| unsupported_encoding | Invalid character encoding value. Should be between 0-8 inclusive |
| invalid_schedule_date | Invalid date format or date value. |
| invalid_expiry_date | Invalid date format or date value. |
| insufficient_balance | Not enough balance |
| invalid_from_address | Malformed FROM address or sender ID |
| invalid_to_address | Malformed TO phone number |
| empty_message | Empty Message. Message has to have at least 1 character |
| internal_error | Internal System Error |