/**
* Sends a message to the specified addresses.
*
* @param array $addresses strings that holds the addresses to which
* the specified messages will be sent.
* @param string|null $text text body of message or null if none
* @param string|null $subject subject of message or null if none
* @param array|null $fnames file names of attachments or null if none
* @param bool|null $isGroup whether to send as broadcast or null to
* use default
*
* @return string message id
* @throws ServiceException if API request was not successful
*/
public function sendMessage($addresses, $text, $subject, $fnames = null, $isGroup = null)
{
$endpoint = $this->getFqdn() . '/myMessages/v2/messages';
$req = new RESTFulRequest($endpoint);
$req->setHeader('Accept', 'application/json')->setHeader('Content-Type', 'application/json')->setAuthorizationHeader($this->getToken());
$vals = array('addresses' => $addresses);
$vals['isGroup'] = $isGroup ? 'true' : 'false';
if ($text !== null) {
$vals['text'] = $text;
}
if ($subject !== null) {
$vals['subject'] = $subject;
}
$messageRequest = array('messageRequest' => $vals);
$jvals = json_encode($messageRequest);
$result = null;
if ($fnames == null) {
// no attachments; send basic POST
$req->setHeader('Content-Type', 'application/json');
$httpPost = new HttpPost();
$httpPost->setBody($jvals);
$result = $req->sendHttpPost($httpPost);
} else {
// attachments; send as multipart
$mpart = new HttpMultipart();
$mpart->addJSONPart($jvals);
foreach ($fnames as $fname) {
$mpart->addFilePart($fname);
}
$result = $req->sendHttpMultipart($mpart);
}
$responseArr = Service::parseJson($result);
return $responseArr['id'];
}
/**
* Sends a request to the API for getting device capabilities.
*
* @return DCResponse API response.
* @throws ServiceException if API request was not successful
*/
public function getDeviceInformation()
{
$endpoint = $this->getFqdn() . '/rest/2/Devices/Info';
$req = new RESTFulRequest($endpoint);
$result = $req->setAuthorizationHeader($this->getToken())->setHeader('Accept', 'application/json')->sendHttpGet();
$arr = Service::parseJson($result);
return DCResponse::fromArray($arr);
}
/**
* Sends a request to the API for getting any SMS messages that were sent
* to the specified short code.
*
* @param string $shortCode gets messages sent to this short code
*
* @return GetSMSResponse API response
* @throws ServiceException if API request was not successful
*/
public function getMessages($shortCode, $raw_response = false)
{
$endpoint = $this->getFqdn() . '/sms/v3/messaging/inbox/' . urlencode($shortCode);
$req = new RESTFulRequest($endpoint);
$result = $req->setAuthorizationHeader($this->getToken())->setHeader('Accept', 'application/json')->setHeader('Content-Type', 'application/x-www-form-urlencoded')->sendHttpGet();
// Handle the flag to return json.
if ($raw_response) {
$body = Service::parseApiResposeBody($result);
// Note: This could throw ServiceExeption
return $body;
}
$arr = Service::parseJson($result);
return GetSMSResponse::fromArray($arr);
}
/**
* Sends a custom API request for converting speech to text.
*
* @param string $cntxt speech context.
* @param string $fname path to file that contains speech to convert.
* @param string $gfname path to file that contains grammar.
* @param string $dfname path to file that contains dictionary.
* @param string $xArg optional arguments.
* @param string $lang language used to set the Content-Language header.
*
* @return array API response as an array of key-value pairs.
* @throws ServiceException if API request was not successful.
*/
public function speechToTextCustom($cntxt, $fname, $gfname = null, $dfname = null, $xArg = null, $lang = 'en-US')
{
$endpoint = $this->getFqdn() . '/speech/v3/speechToTextCustom';
$mpart = new SpeechMultipartBody();
$req = new RESTFulRequest($endpoint);
$req->setHeader('X-SpeechContext', $cntxt)->setHeader('Accept', 'application/json')->setHeader('Content-Language', $lang)->setAuthorizationHeader($this->getToken());
if ($xArg != null) {
$req->setHeader('X-Arg', $xArg);
}
if ($dfname != null) {
$mpart->addXDictionaryPart($dfname);
}
if ($gfname != null) {
$mpart->addXGrammarPart($gfname);
}
$mpart->addFilePart($fname);
$result = $req->sendHttpMultipart($mpart);
return Service::parseJson($result);
}
/**
* Sends a request to the API for getting any SMS messages that were sent
* to the specified short code.
*
* @param string $shortCode gets messages sent to this short code
*
* @return GetSMSResponse API response
* @throws ServiceException if API request was not successful
*/
public function getMessages($shortCode)
{
$endpoint = $this->getFqdn() . '/sms/v3/messaging/inbox/' . urlencode($shortCode);
$req = new RESTFulRequest($endpoint);
$result = $req->setAuthorizationHeader($this->getToken())->setHeader('Accept', 'application/json')->setHeader('Content-Type', 'application/x-www-form-urlencoded')->sendHttpGet();
$arr = Service::parseJson($result);
return GetSMSResponse::fromArray($arr);
}
/**
* Sends a request to the API gateway for getting subscriber's personal
* contact card.
*
* @return Contact contact information for subscriber
* @throws ServiceException if request was not successful
*/
public function getMyInfo()
{
$endpoint = $this->getFqdn() . '/addressBook/v1/myInfo';
$req = new RESTFulRequest($endpoint);
$req->setAuthorizationHeader($this->getToken())->setHeader('Accept', 'application/json');
$result = $req->sendHttpGet();
$successCodes = array(200);
$arr = Service::parseJson($result, $successCodes);
return Contact::fromArray($arr['myInfo']);
}
/**
* Sends an API request for removing the notification from the api server,
* thereby causing any future calls to getNotificationInfo() to fail. Also,
* prevents the api from sending any further notifications.
*
* Unless this method is called, the api will keep sending the same
* notification id indefinitely.
*
* @param string $notificationId notification id
*
* @return array api response
* @throws ServiceException if api request was not successful
*/
public function deleteNotification($notificationId)
{
$urlPath = '/rest/3/Commerce/Payment/Notifications/' . $notificationId;
$url = $this->getFqdn() . $urlPath;
$req = new RESTFulRequest($url);
$req->setHttpMethod(RESTFulRequest::HTTP_METHOD_PUT);
$req->setHeader('Accept', 'application/json');
$req->addAuthorizationHeader($this->token);
$result = $req->sendRequest();
return $this->parseResult($result);
}
