From 211d2959f76cb87f618a42243dbc199166cae001 Mon Sep 17 00:00:00 2001 From: Ben Mostafa Date: Mon, 20 Nov 2017 23:32:55 +1100 Subject: [PATCH] First commit of Messages PHP SDK --- Jenkinsfile | 10 + LICENSE | 54 +- README.md | 1272 +++++++++-------- appveyor.yml | 37 + circle.yml | 5 + composer.json | 7 +- phpunit.xml | 38 +- src/APIException.php | 6 +- src/APIHelper.php | 6 +- src/Configuration.php | 18 +- src/Controllers/BaseController.php | 16 +- src/Controllers/DeliveryReportsController.php | 40 +- src/Controllers/MessagesController.php | 86 +- src/Controllers/RepliesController.php | 188 +-- src/Http/HttpCallBack.php | 6 +- src/Http/HttpContext.php | 6 +- src/Http/HttpMethod.php | 6 +- src/Http/HttpRequest.php | 6 +- src/Http/HttpResponse.php | 6 +- src/MessageMediaMessagesClient.php | 51 + src/Models/CancelScheduledMessageRequest.php | 6 +- src/Models/CheckDeliveryReportsResponse.php | 6 +- src/Models/CheckRepliesResponse.php | 6 +- ...onfirmDeliveryReportsAsReceivedRequest.php | 6 +- ...firmDeliveryReportsAsReceivedRequest11.php | 6 +- .../ConfirmRepliesAsReceivedRequest.php | 6 +- .../ConfirmRepliesAsReceivedRequest8.php | 6 +- src/Models/SendMessagesRequest.php | 6 +- src/Models/SendMessagesResponse.php | 6 +- .../DeliveryReportsControllerTest.php | 20 +- tests/Controllers/MessagesControllerTest.php | 204 +-- tests/Controllers/RepliesControllerTest.php | 132 +- tests/HttpCallBackCatcher.php | 16 +- tests/TestHelper.php | 8 +- tests/bootstrap.php | 4 +- 35 files changed, 1166 insertions(+), 1136 deletions(-) create mode 100644 Jenkinsfile create mode 100644 appveyor.yml create mode 100644 circle.yml create mode 100644 src/MessageMediaMessagesClient.php diff --git a/Jenkinsfile b/Jenkinsfile new file mode 100644 index 0000000..7ab8026 --- /dev/null +++ b/Jenkinsfile @@ -0,0 +1,10 @@ +node { + stage 'Checkout' + checkout scm + + stage 'Prepare' + bat 'composer install --no-interaction --prefer-dist' + + stage 'Test' + bat 'vendor/bin/phpunit.bat' +} \ No newline at end of file diff --git a/LICENSE b/LICENSE index 7d6f5bc..252a1c6 100644 --- a/LICENSE +++ b/LICENSE @@ -1,28 +1,28 @@ -License: -======== -The MIT License (MIT) -http://opensource.org/licenses/MIT - -Copyright (c) 2014 - 2016 APIMATIC Limited - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - -Trade Mark: -========== +License: +======== +The MIT License (MIT) +http://opensource.org/licenses/MIT + +Copyright (c) 2014 - 2016 APIMATIC Limited + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +Trade Mark: +========== APIMATIC is a trade mark for APIMATIC Limited \ No newline at end of file diff --git a/README.md b/README.md index d88fa9a..91c7fb8 100644 --- a/README.md +++ b/README.md @@ -1,637 +1,647 @@ # Getting started -TODO: Add a description - -## How to Build - -The generated code has dependencies over external libraries like UniRest. These dependencies are defined in the ```composer.json``` file that comes with the SDK. -To resolve these dependencies, we use the Composer package manager which requires PHP greater than 5.3.2 installed in your system. -Visit [https://getcomposer.org/download/](https://getcomposer.org/download/) to download the installer file for Composer and run it in your system. -Open command prompt and type ```composer --version```. This should display the current version of the Composer installed if the installation was successful. - -* Using command line, navigate to the directory containing the generated files (including ```composer.json```) for the SDK. -* Run the command ```composer install```. This should install all the required dependencies and create the ```vendor``` directory in your project directory. - -![Building SDK - Step 1](https://apidocs.io/illustration/php?step=installDependencies&workspaceFolder=Messages-PHP) - -### [For Windows Users Only] Configuring CURL Certificate Path in php.ini - -CURL used to include a list of accepted CAs, but no longer bundles ANY CA certs. So by default it will reject all SSL certificates as unverifiable. You will have to get your CA's cert and point curl at it. The steps are as follows: - -1. Download the certificate bundle (.pem file) from [https://curl.haxx.se/docs/caextract.html](https://curl.haxx.se/docs/caextract.html) on to your system. -2. Add curl.cainfo = "PATH_TO/cacert.pem" to your php.ini file located in your php installation. “PATH_TO” must be an absolute path containing the .pem file. - -```ini -[curl] -; A default value for the CURLOPT_CAINFO option. This is required to be an -; absolute path. -;curl.cainfo = -``` - -## How to Use - -The following section explains how to use the Messages library in a new project. - -### 1. Open Project in an IDE - -Open an IDE for PHP like PhpStorm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE. - -![Open project in PHPStorm - Step 1](https://apidocs.io/illustration/php?step=openIDE&workspaceFolder=Messages-PHP) - -Click on ```Open``` in PhpStorm to browse to your generated SDK directory and then click ```OK```. - -![Open project in PHPStorm - Step 2](https://apidocs.io/illustration/php?step=openProject0&workspaceFolder=Messages-PHP) - -### 2. Add a new Test Project - -Create a new directory by right clicking on the solution name as shown below: - -![Add a new project in PHPStorm - Step 1](https://apidocs.io/illustration/php?step=createDirectory&workspaceFolder=Messages-PHP) - -Name the directory as "test" - -![Add a new project in PHPStorm - Step 2](https://apidocs.io/illustration/php?step=nameDirectory&workspaceFolder=Messages-PHP) - -Add a PHP file to this project - -![Add a new project in PHPStorm - Step 3](https://apidocs.io/illustration/php?step=createFile&workspaceFolder=Messages-PHP) - -Name it "testSDK" - -![Add a new project in PHPStorm - Step 4](https://apidocs.io/illustration/php?step=nameFile&workspaceFolder=Messages-PHP) - -Depending on your project setup, you might need to include composer's autoloader in your PHP code to enable auto loading of classes. - -```PHP -require_once "../vendor/autoload.php"; -``` - -It is important that the path inside require_once correctly points to the file ```autoload.php``` inside the vendor directory created during dependency installations. - -![Add a new project in PHPStorm - Step 4](https://apidocs.io/illustration/php?step=projectFiles&workspaceFolder=Messages-PHP) - -After this you can add code to initialize the client library and acquire the instance of a Controller class. Sample code to initialize the client library and using controller methods is given in the subsequent sections. - -### 3. Run the Test Project - -To run your project you must set the Interpreter for your project. Interpreter is the PHP engine installed on your computer. - -Open ```Settings``` from ```File``` menu. - -![Run Test Project - Step 1](https://apidocs.io/illustration/php?step=openSettings&workspaceFolder=Messages-PHP) - -Select ```PHP``` from within ```Languages & Frameworks``` - -![Run Test Project - Step 2](https://apidocs.io/illustration/php?step=setInterpreter0&workspaceFolder=Messages-PHP) - -Browse for Interpreters near the ```Interpreter``` option and choose your interpreter. - -![Run Test Project - Step 3](https://apidocs.io/illustration/php?step=setInterpreter1&workspaceFolder=Messages-PHP) - -Once the interpreter is selected, click ```OK``` - -![Run Test Project - Step 4](https://apidocs.io/illustration/php?step=setInterpreter2&workspaceFolder=Messages-PHP) - -To run your project, right click on your PHP file inside your Test project and click on ```Run``` - -![Run Test Project - Step 5](https://apidocs.io/illustration/php?step=runProject&workspaceFolder=Messages-PHP) - -## How to Test - -Unit tests in this SDK can be run using PHPUnit. - -1. First install the dependencies using composer including the `require-dev` dependencies. -2. Run `vendor\bin\phpunit --verbose` from commandline to execute tests. If you have - installed PHPUnit globally, run tests using `phpunit --verbose` instead. - -You can change the PHPUnit test configuration in the `phpunit.xml` file. - -## Initialization - -### - -API client can be initialized as following. - -```php - -$client = new MessagesLib\MessagesClient(); -``` - - +The MessageMedia Messages API provides a number of endpoints for building powerful two-way messaging applications. + +## How to Build + +The generated code has dependencies over external libraries like UniRest. These dependencies are defined in the ```composer.json``` file that comes with the SDK. +To resolve these dependencies, we use the Composer package manager which requires PHP greater than 5.3.2 installed in your system. +Visit [https://getcomposer.org/download/](https://getcomposer.org/download/) to download the installer file for Composer and run it in your system. +Open command prompt and type ```composer --version```. This should display the current version of the Composer installed if the installation was successful. + +* Using command line, navigate to the directory containing the generated files (including ```composer.json```) for the SDK. +* Run the command ```composer install```. This should install all the required dependencies and create the ```vendor``` directory in your project directory. + +![Building SDK - Step 1](https://apidocs.io/illustration/php?step=installDependencies&workspaceFolder=MessageMediaMessages-PHP) + +### [For Windows Users Only] Configuring CURL Certificate Path in php.ini + +CURL used to include a list of accepted CAs, but no longer bundles ANY CA certs. So by default it will reject all SSL certificates as unverifiable. You will have to get your CA's cert and point curl at it. The steps are as follows: + +1. Download the certificate bundle (.pem file) from [https://curl.haxx.se/docs/caextract.html](https://curl.haxx.se/docs/caextract.html) on to your system. +2. Add curl.cainfo = "PATH_TO/cacert.pem" to your php.ini file located in your php installation. “PATH_TO” must be an absolute path containing the .pem file. + +```ini +[curl] +; A default value for the CURLOPT_CAINFO option. This is required to be an +; absolute path. +;curl.cainfo = +``` + +## How to Use + +The following section explains how to use the MessageMediaMessages library in a new project. + +### 1. Open Project in an IDE + +Open an IDE for PHP like PhpStorm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE. + +![Open project in PHPStorm - Step 1](https://apidocs.io/illustration/php?step=openIDE&workspaceFolder=MessageMediaMessages-PHP) + +Click on ```Open``` in PhpStorm to browse to your generated SDK directory and then click ```OK```. + +![Open project in PHPStorm - Step 2](https://apidocs.io/illustration/php?step=openProject0&workspaceFolder=MessageMediaMessages-PHP) + +### 2. Add a new Test Project + +Create a new directory by right clicking on the solution name as shown below: + +![Add a new project in PHPStorm - Step 1](https://apidocs.io/illustration/php?step=createDirectory&workspaceFolder=MessageMediaMessages-PHP) + +Name the directory as "test" + +![Add a new project in PHPStorm - Step 2](https://apidocs.io/illustration/php?step=nameDirectory&workspaceFolder=MessageMediaMessages-PHP) + +Add a PHP file to this project + +![Add a new project in PHPStorm - Step 3](https://apidocs.io/illustration/php?step=createFile&workspaceFolder=MessageMediaMessages-PHP) + +Name it "testSDK" + +![Add a new project in PHPStorm - Step 4](https://apidocs.io/illustration/php?step=nameFile&workspaceFolder=MessageMediaMessages-PHP) + +Depending on your project setup, you might need to include composer's autoloader in your PHP code to enable auto loading of classes. + +```PHP +require_once "../vendor/autoload.php"; +``` + +It is important that the path inside require_once correctly points to the file ```autoload.php``` inside the vendor directory created during dependency installations. + +![Add a new project in PHPStorm - Step 4](https://apidocs.io/illustration/php?step=projectFiles&workspaceFolder=MessageMediaMessages-PHP) + +After this you can add code to initialize the client library and acquire the instance of a Controller class. Sample code to initialize the client library and using controller methods is given in the subsequent sections. + +### 3. Run the Test Project + +To run your project you must set the Interpreter for your project. Interpreter is the PHP engine installed on your computer. + +Open ```Settings``` from ```File``` menu. + +![Run Test Project - Step 1](https://apidocs.io/illustration/php?step=openSettings&workspaceFolder=MessageMediaMessages-PHP) + +Select ```PHP``` from within ```Languages & Frameworks``` + +![Run Test Project - Step 2](https://apidocs.io/illustration/php?step=setInterpreter0&workspaceFolder=MessageMediaMessages-PHP) + +Browse for Interpreters near the ```Interpreter``` option and choose your interpreter. + +![Run Test Project - Step 3](https://apidocs.io/illustration/php?step=setInterpreter1&workspaceFolder=MessageMediaMessages-PHP) + +Once the interpreter is selected, click ```OK``` + +![Run Test Project - Step 4](https://apidocs.io/illustration/php?step=setInterpreter2&workspaceFolder=MessageMediaMessages-PHP) + +To run your project, right click on your PHP file inside your Test project and click on ```Run``` + +![Run Test Project - Step 5](https://apidocs.io/illustration/php?step=runProject&workspaceFolder=MessageMediaMessages-PHP) + +## How to Test + +Unit tests in this SDK can be run using PHPUnit. + +1. First install the dependencies using composer including the `require-dev` dependencies. +2. Run `vendor\bin\phpunit --verbose` from commandline to execute tests. If you have + installed PHPUnit globally, run tests using `phpunit --verbose` instead. + +You can change the PHPUnit test configuration in the `phpunit.xml` file. + +## Initialization + +### Authentication +In order to setup authentication and initialization of the API client, you need the following information. + +| Parameter | Description | +|-----------|-------------| +| basicAuthUserName | The username to use with basic authentication | +| basicAuthPassword | The password to use with basic authentication | + + + +API client can be initialized as following. + +```php +$basicAuthUserName = 'basicAuthUserName'; // The username to use with basic authentication +$basicAuthPassword = 'basicAuthPassword'; // The password to use with basic authentication + +$client = new MessageMediaMessagesLib\MessageMediaMessagesClient($basicAuthUserName, $basicAuthPassword); +``` + + # Class Reference - -## List of Controllers - -* [MessagesController](#messages_controller) -* [DeliveryReportsController](#delivery_reports_controller) -* [RepliesController](#replies_controller) - -## ![Class: ](https://apidocs.io/img/class.png ".MessagesController") MessagesController - -### Get singleton instance - -The singleton instance of the ``` MessagesController ``` class can be accessed from the API Client. - -```php -$messages = $client->getMessages(); -``` - -### ![Method: ](https://apidocs.io/img/method.png ".MessagesController.updateCancelScheduledMessage") updateCancelScheduledMessage - -> Cancel a scheduled message that has not yet been delivered. -> A scheduled messages can be cancelled by updating the status of a message from ```scheduled``` -> to ```cancelled```. This is done by submitting a PUT request to the messages endpoint using -> the message ID as a parameter (the same endpoint used above to retrieve the status of a message). -> The body of the request simply needs to contain a ```status``` property with the value set -> to ```cancelled```. -> ```json -> { -> "status": "cancelled" -> } -> ``` -> *Note: Only messages with a status of scheduled can be cancelled. If an invalid or non existent -> message ID parameter is specified in the request, then a HTTP 404 Not Found response will be -> returned* - - -```php -function updateCancelScheduledMessage( - $messageId, - $body) -``` - -#### Parameters - -| Parameter | Tags | Description | -|-----------|------|-------------| -| messageId | ``` Required ``` | TODO: Add a parameter description | -| body | ``` Required ``` | TODO: Add a parameter description | - - - -#### Example Usage - -```php -$messageId = 'messageId'; -$body = new CancelScheduledMessageRequest(); - -$result = $messages->updateCancelScheduledMessage($messageId, $body); - -``` - -#### Errors - -| Error Code | Error Description | -|------------|-------------------| -| 400 | TODO: Add an error description | -| 404 | TODO: Add an error description | - - - -### ![Method: ](https://apidocs.io/img/method.png ".MessagesController.getMessageStatus") getMessageStatus - -> Retrieve the current status of a message using the message ID returned in the send messages end point. -> A successful request to the get message status endpoint will return a response body as follows: -> ```json -> { -> "format": "SMS", -> "content": "My first message!", -> "metadata": { -> "key1": "value1", -> "key2": "value2" -> }, -> "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", -> "callback_url": "https://my.callback.url.com", -> "delivery_report": true, -> "destination_number": "+61401760575", -> "scheduled": "2016-11-03T11:49:02.807Z", -> "source_number": "+61491570157", -> "source_number_type": "INTERNATIONAL" -> "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", -> "status": "enroute" -> } -> ``` -> The status property of the response indicates the current status of the message. See the Delivery -> Reports section of this documenation for more information on message statues. -> *Note: If an invalid or non existent message ID parameter is specified in the request, then -> a HTTP 404 Not Found response will be returned* - - -```php -function getMessageStatus($messageId) -``` - -#### Parameters - -| Parameter | Tags | Description | -|-----------|------|-------------| -| messageId | ``` Required ``` | TODO: Add a parameter description | - - - -#### Example Usage - -```php -$messageId = 'messageId'; - -$result = $messages->getMessageStatus($messageId); - -``` - -#### Errors - -| Error Code | Error Description | -|------------|-------------------| -| 404 | TODO: Add an error description | - - - -### ![Method: ](https://apidocs.io/img/method.png ".MessagesController.createSendMessages") createSendMessages - -> Submit one or more (up to 100 per request) SMS or text to voice messages for delivery. -> The most basic message has the following structure: -> ```json -> { -> "messages": [ -> { -> "content": "My first message!", -> "destination_number": "+61491570156" -> } -> ] -> } -> ``` -> More advanced delivery features can be specified by setting the following properties in a message: -> - ```callback_url``` A URL can be included with each message to which webhooks will be pushed to -> via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as -> it is processed (if the delivery report property of the request is set to ```true```) and when replies -> are received. Specifying a callback URL is optional. -> - ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters long. -> Message content is required. -> - ```delivery_report``` Delivery reports can be be requested with each message. If delivery reports are requested, a webhook -> will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) -> specified for the account every time the status of the message changes as it is processed. The -> current status of the message can also be retrieved via the Delivery Reports endpoint of the -> Messages API. Delivery reports are optional and by default will not be requested. -> - ```destination_number``` The destination number the message should be delivered to. This should be specified in E.164 -> international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. -> A destination number is required. -> - ```format``` The format specifies which format the message will be sent as, ```SMS``` (text message) -> or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the -> message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used. -> - ```source_number``` A source number may be specified for the message, this will be the number that -> the message appears from on the handset. By default this feature is _not_ available and will be ignored -> in the request. Please contact for more information. Specifying a source -> number is optional and a by default a source number will be assigned to the message. -> - ```source_number_type``` If a source number is specified, the type of source number may also be -> specified. This is recommended when using a source address type that is not an internationally -> formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Speciying a -> source number type is only valid when a the ```source_number``` parameter is specified and is optional. -> If a source number is specified and no source number type is specified, the source number type will be -> inferred from the source number, however this may be inaccurate. -> - ```scheduled``` A message can be scheduled for delivery in the future by setting the scheduled property. -> The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be -> provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. -> - ```message_expiry_timestamp``` A message expiry timestamp can be provided to specify the latest time -> at which the message should be delivered. If the message cannot be delivered before the specified -> message expiry timestamp elapses, the message will be discarded. Specifying a message expiry -> timestamp is optional. -> - ```metadata``` Metadata can be included with the message which will then be included with any delivery -> reports or replies matched to the message. This can be used to create powerful two-way messaging -> applications without having to store persitant data in the application. Up to 10 key / value metada data -> pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to -> 256 characters long. Specifiying metadata for a message is optional. -> The response body of a successful POST request to the messages endpoint will include a ```messages``` -> property which contains a list of all messages submitted. The list of messages submitted will -> reflect the list of messages included in the request, but each message will also contain two new -> properties, ```message_id``` and ```status```. The returned message ID will be a 36 character UUID -> which can be used to check the status of the message via the Get Message Status endpoint. The status -> of the message which reflect the status of the message at submission time which will always be -> ```queued```. See the Delivery Reports section of this documenation for more information on message -> statues. -> *Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. -> If any messages in the request are invalid, no messages will be sent.* - - -```php -function createSendMessages($body) -``` - -#### Parameters - -| Parameter | Tags | Description | -|-----------|------|-------------| -| body | ``` Required ``` | TODO: Add a parameter description | - - - -#### Example Usage - -```php -$bodyValue = "{ \"messages\": [ { \"callback_url\": \"https://my.callback.url.com\", \"content\": \"My first message\", \"destination_number\": \"+61491570156\", \"delivery_report\": true, \"format\": \"SMS\", \"message_expiry_timestamp\": \"2016-11-03T11:49:02.807Z\", \"metadata\": { \"key1\": \"value1\", \"key2\": \"value2\" }, \"scheduled\": \"2016-11-03T11:49:02.807Z\", \"source_number\": \"+61491570157\", \"source_number_type\": \"INTERNATIONAL\" }, { \"callback_url\": \"https://my.callback.url.com\", \"content\": \"My second message\", \"destination_number\": \"+61491570158\", \"delivery_report\": true, \"format\": \"SMS\", \"message_expiry_timestamp\": \"2016-11-03T11:49:02.807Z\", \"metadata\": { \"key1\": \"value1\", \"key2\": \"value2\" }, \"scheduled\": \"2016-11-03T11:49:02.807Z\", \"source_number\": \"+61491570159\", \"source_number_type\": \"INTERNATIONAL\" } ]}"; -$body = APIHelper::deserialize($bodyValue); - -$result = $messages->createSendMessages($body); - -``` - -#### Errors - -| Error Code | Error Description | -|------------|-------------------| -| 400 | TODO: Add an error description | - - - + +## List of Controllers + +* [MessagesController](#messages_controller) +* [DeliveryReportsController](#delivery_reports_controller) +* [RepliesController](#replies_controller) + +## ![Class: ](https://apidocs.io/img/class.png ".MessagesController") MessagesController + +### Get singleton instance + +The singleton instance of the ``` MessagesController ``` class can be accessed from the API Client. + +```php +$messages = $client->getMessages(); +``` + +### ![Method: ](https://apidocs.io/img/method.png ".MessagesController.updateCancelScheduledMessage") updateCancelScheduledMessage + +> Cancel a scheduled message that has not yet been delivered. +> A scheduled message can be cancelled by updating the status of a message from ```scheduled``` +> to ```cancelled```. This is done by submitting a PUT request to the messages endpoint using +> the message ID as a parameter (the same endpoint used above to retrieve the status of a message). +> The body of the request simply needs to contain a ```status``` property with the value set +> to ```cancelled```. +> ```json +> { +> "status": "cancelled" +> } +> ``` +> *Note: Only messages with a status of scheduled can be cancelled. If an invalid or non existent +> message ID parameter is specified in the request, then a HTTP 404 Not Found response will be +> returned* + + +```php +function updateCancelScheduledMessage( + $messageId, + $body) +``` + +#### Parameters + +| Parameter | Tags | Description | +|-----------|------|-------------| +| messageId | ``` Required ``` | TODO: Add a parameter description | +| body | ``` Required ``` | TODO: Add a parameter description | + + + +#### Example Usage + +```php +$messageId = 'messageId'; +$body = new CancelScheduledMessageRequest(); + +$result = $messages->updateCancelScheduledMessage($messageId, $body); + +``` + +#### Errors + +| Error Code | Error Description | +|------------|-------------------| +| 400 | TODO: Add an error description | +| 404 | TODO: Add an error description | + + + +### ![Method: ](https://apidocs.io/img/method.png ".MessagesController.getMessageStatus") getMessageStatus + +> Retrieve the current status of a message using the message ID returned in the send messages end point. +> A successful request to the get message status endpoint will return a response body as follows: +> ```json +> { +> "format": "SMS", +> "content": "My first message!", +> "metadata": { +> "key1": "value1", +> "key2": "value2" +> }, +> "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", +> "callback_url": "https://my.callback.url.com", +> "delivery_report": true, +> "destination_number": "+61401760575", +> "scheduled": "2016-11-03T11:49:02.807Z", +> "source_number": "+61491570157", +> "source_number_type": "INTERNATIONAL" +> "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", +> "status": "enroute" +> } +> ``` +> The status property of the response indicates the current status of the message. See the Delivery +> Reports section of this documentation for more information on message statues. +> *Note: If an invalid or non existent message ID parameter is specified in the request, then +> a HTTP 404 Not Found response will be returned* + + +```php +function getMessageStatus($messageId) +``` + +#### Parameters + +| Parameter | Tags | Description | +|-----------|------|-------------| +| messageId | ``` Required ``` | TODO: Add a parameter description | + + + +#### Example Usage + +```php +$messageId = 'messageId'; + +$result = $messages->getMessageStatus($messageId); + +``` + +#### Errors + +| Error Code | Error Description | +|------------|-------------------| +| 404 | TODO: Add an error description | + + + +### ![Method: ](https://apidocs.io/img/method.png ".MessagesController.createSendMessages") createSendMessages + +> Submit one or more (up to 100 per request) SMS or text to voice messages for delivery. +> The most basic message has the following structure: +> ```json +> { +> "messages": [ +> { +> "content": "My first message!", +> "destination_number": "+61491570156" +> } +> ] +> } +> ``` +> More advanced delivery features can be specified by setting the following properties in a message: +> - ```callback_url``` A URL can be included with each message to which Webhooks will be pushed to +> via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as +> it is processed (if the delivery report property of the request is set to ```true```) and when replies +> are received. Specifying a callback URL is optional. +> - ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters long. +> Message content is required. +> - ```delivery_report``` Delivery reports can be requested with each message. If delivery reports are requested, a webhook +> will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) +> specified for the account every time the status of the message changes as it is processed. The +> current status of the message can also be retrieved via the Delivery Reports endpoint of the +> Messages API. Delivery reports are optional and by default will not be requested. +> - ```destination_number``` The destination number the message should be delivered to. This should be specified in E.164 +> international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. +> A destination number is required. +> - ```format``` The format specifies which format the message will be sent as, ```SMS``` (text message) +> or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the +> message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used. +> - ```source_number``` A source number may be specified for the message, this will be the number that +> the message appears from on the handset. By default this feature is _not_ available and will be ignored +> in the request. Please contact for more information. Specifying a source +> number is optional and a by default a source number will be assigned to the message. +> - ```source_number_type``` If a source number is specified, the type of source number may also be +> specified. This is recommended when using a source address type that is not an internationally +> formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Specifying a +> source number type is only valid when the ```source_number``` parameter is specified and is optional. +> If a source number is specified and no source number type is specified, the source number type will be +> inferred from the source number, however this may be inaccurate. +> - ```scheduled``` A message can be scheduled for delivery in the future by setting the scheduled property. +> The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be +> provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. +> - ```message_expiry_timestamp``` A message expiry timestamp can be provided to specify the latest time +> at which the message should be delivered. If the message cannot be delivered before the specified +> message expiry timestamp elapses, the message will be discarded. Specifying a message expiry +> timestamp is optional. +> - ```metadata``` Metadata can be included with the message which will then be included with any delivery +> reports or replies matched to the message. This can be used to create powerful two-way messaging +> applications without having to store persistent data in the application. Up to 10 key / value metadata data +> pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to +> 256 characters long. Specifying metadata for a message is optional. +> The response body of a successful POST request to the messages endpoint will include a ```messages``` +> property which contains a list of all messages submitted. The list of messages submitted will +> reflect the list of messages included in the request, but each message will also contain two new +> properties, ```message_id``` and ```status```. The returned message ID will be a 36 character UUID +> which can be used to check the status of the message via the Get Message Status endpoint. The status +> of the message which reflect the status of the message at submission time which will always be +> ```queued```. See the Delivery Reports section of this documentation for more information on message +> statues. +> *Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. +> If any messages in the request are invalid, no messages will be sent.* + + +```php +function createSendMessages($body) +``` + +#### Parameters + +| Parameter | Tags | Description | +|-----------|------|-------------| +| body | ``` Required ``` | TODO: Add a parameter description | + + + +#### Example Usage + +```php +$bodyValue = "{ \"messages\": [ { \"callback_url\": \"https://my.callback.url.com\", \"content\": \"My first message\", \"destination_number\": \"+61491570156\", \"delivery_report\": true, \"format\": \"SMS\", \"message_expiry_timestamp\": \"2016-11-03T11:49:02.807Z\", \"metadata\": { \"key1\": \"value1\", \"key2\": \"value2\" }, \"scheduled\": \"2016-11-03T11:49:02.807Z\", \"source_number\": \"+61491570157\", \"source_number_type\": \"INTERNATIONAL\" }, { \"callback_url\": \"https://my.callback.url.com\", \"content\": \"My second message\", \"destination_number\": \"+61491570158\", \"delivery_report\": true, \"format\": \"SMS\", \"message_expiry_timestamp\": \"2016-11-03T11:49:02.807Z\", \"metadata\": { \"key1\": \"value1\", \"key2\": \"value2\" }, \"scheduled\": \"2016-11-03T11:49:02.807Z\", \"source_number\": \"+61491570159\", \"source_number_type\": \"INTERNATIONAL\" } ]}"; +$body = APIHelper::deserialize($bodyValue); + +$result = $messages->createSendMessages($body); + +``` + +#### Errors + +| Error Code | Error Description | +|------------|-------------------| +| 400 | TODO: Add an error description | + + + [Back to List of Controllers](#list_of_controllers) - -## ![Class: ](https://apidocs.io/img/class.png ".DeliveryReportsController") DeliveryReportsController - -### Get singleton instance - -The singleton instance of the ``` DeliveryReportsController ``` class can be accessed from the API Client. - -```php -$deliveryReports = $client->getDeliveryReports(); -``` - -### ![Method: ](https://apidocs.io/img/method.png ".DeliveryReportsController.getCheckDeliveryReports") getCheckDeliveryReports - -> Check for any delivery reports that have been received. -> Delivery reports are a notification of the change in status of a message as it is being processed. -> Each request to the check delivery reports endpoint will return any delivery reports received that -> have not yet been confirmed using the confirm delivery reports endpoint. A response from the check -> delivery reports endpoint will have the following structure: -> ```json -> { -> "delivery_reports": [ -> { -> "callback_url": "https://my.callback.url.com", -> "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043", -> "source_number": "+61491570157", -> "date_received": "2017-05-20T06:30:37.642Z", -> "status": "enroute", -> "delay": 0, -> "submitted_date": "2017-05-20T06:30:37.639Z", -> "original_text": "My first message!", -> "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba", -> "vendor_account_id": { -> "vendor_id": "MessageMedia", -> "account_id": "MyAccount" -> }, -> "metadata": { -> "key1": "value1", -> "key2": "value2" -> } -> }, -> { -> "callback_url": "https://my.callback.url.com", -> "delivery_report_id": "0edf9022-7ccc-43e6-acab-480e93e98c1b", -> "source_number": "+61491570158", -> "date_received": "2017-05-21T01:46:42.579Z", -> "status": "enroute", -> "delay": 0, -> "submitted_date": "2017-05-21T01:46:42.574Z", -> "original_text": "My second message!", -> "message_id": "fbb3b3f5-b702-4d8b-ab44-65b2ee39a281", -> "vendor_account_id": { -> "vendor_id": "MessageMedia", -> "account_id": "MyAccount" -> }, -> "metadata": { -> "key1": "value1", -> "key2": "value2" -> } -> } -> ] -> } -> ``` -> Each delivery report will contain details about the message, including any metadata specified -> and the new status of the message (as each delivery report indicates a change in status of a -> message) and the timestamp at which the status changed. Every delivery report will have a -> unique delivery report ID for use with the confirm delivery reports endpoint. -> *Note: The source number and destination number properties in a delivery report are the inverse of -> those specified in the message that the delivery report relates to. The source number of the -> delivery report is the destination number of the original message.* -> Subsequent requests to the check delivery reports endpoint will return the same delivery reports -> and a maximum of 100 delivery reports will be returned in each request. Applications should use the -> confirm delivery reports endpoint in the following pattern so that delivery reports that have been -> processed are no longer returned in subsequent check delivery reports requests. -> 1. Call check delivery reports endpoint -> 2. Process each delivery report -> 3. Confirm all processed delivery reports using the confirm delivery reports endpoint -> *Note: It is recommended to use the webhooks feature to receive reply messages rather than -> polling the check delivery reports endpoint.* - - -```php -function getCheckDeliveryReports() -``` - -#### Example Usage - -```php - -$result = $deliveryReports->getCheckDeliveryReports(); - -``` - - -### ![Method: ](https://apidocs.io/img/method.png ".DeliveryReportsController.createConfirmDeliveryReportsAsReceived") createConfirmDeliveryReportsAsReceived - -> Mark a delivery report as confirmed so it is no longer return in check delivery reports requests. -> The confirm delivery reports endpoint is intended to be used in conjunction with the check delivery -> reports endpoint to allow for robust processing of delivery reports. Once one or more delivery -> reports have been processed, they can then be confirmed using the confirm delivery reports endpoint so they -> are no longer returned in subsequent check delivery reports requests. -> The confirm delivery reports endpoint takes a list of delivery report IDs as follows: -> ```json -> { -> "delivery_report_ids": [ -> "011dcead-6988-4ad6-a1c7-6b6c68ea628d", -> "3487b3fa-6586-4979-a233-2d1b095c7718", -> "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" -> ] -> } -> ``` -> Up to 100 delivery reports can be confirmed in a single confirm delivery reports request. - - -```php -function createConfirmDeliveryReportsAsReceived($body) -``` - -#### Parameters - -| Parameter | Tags | Description | -|-----------|------|-------------| -| body | ``` Required ``` | TODO: Add a parameter description | - - - -#### Example Usage - -```php -$bodyValue = "{ \"delivery_report_ids\": [ \"011dcead-6988-4ad6-a1c7-6b6c68ea628d\", \"3487b3fa-6586-4979-a233-2d1b095c7718\", \"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\" ]}"; -$body = APIHelper::deserialize($bodyValue); - -$result = $deliveryReports->createConfirmDeliveryReportsAsReceived($body); - -``` - -#### Errors - -| Error Code | Error Description | -|------------|-------------------| -| 400 | TODO: Add an error description | - - - + +## ![Class: ](https://apidocs.io/img/class.png ".DeliveryReportsController") DeliveryReportsController + +### Get singleton instance + +The singleton instance of the ``` DeliveryReportsController ``` class can be accessed from the API Client. + +```php +$deliveryReports = $client->getDeliveryReports(); +``` + +### ![Method: ](https://apidocs.io/img/method.png ".DeliveryReportsController.getCheckDeliveryReports") getCheckDeliveryReports + +> Check for any delivery reports that have been received. +> Delivery reports are a notification of the change in status of a message as it is being processed. +> Each request to the check delivery reports endpoint will return any delivery reports received that +> have not yet been confirmed using the confirm delivery reports endpoint. A response from the check +> delivery reports endpoint will have the following structure: +> ```json +> { +> "delivery_reports": [ +> { +> "callback_url": "https://my.callback.url.com", +> "delivery_report_id": "01e1fa0a-6e27-4945-9cdb-18644b4de043", +> "source_number": "+61491570157", +> "date_received": "2017-05-20T06:30:37.642Z", +> "status": "enroute", +> "delay": 0, +> "submitted_date": "2017-05-20T06:30:37.639Z", +> "original_text": "My first message!", +> "message_id": "d781dcab-d9d8-4fb2-9e03-872f07ae94ba", +> "vendor_account_id": { +> "vendor_id": "MessageMedia", +> "account_id": "MyAccount" +> }, +> "metadata": { +> "key1": "value1", +> "key2": "value2" +> } +> }, +> { +> "callback_url": "https://my.callback.url.com", +> "delivery_report_id": "0edf9022-7ccc-43e6-acab-480e93e98c1b", +> "source_number": "+61491570158", +> "date_received": "2017-05-21T01:46:42.579Z", +> "status": "enroute", +> "delay": 0, +> "submitted_date": "2017-05-21T01:46:42.574Z", +> "original_text": "My second message!", +> "message_id": "fbb3b3f5-b702-4d8b-ab44-65b2ee39a281", +> "vendor_account_id": { +> "vendor_id": "MessageMedia", +> "account_id": "MyAccount" +> }, +> "metadata": { +> "key1": "value1", +> "key2": "value2" +> } +> } +> ] +> } +> ``` +> Each delivery report will contain details about the message, including any metadata specified +> and the new status of the message (as each delivery report indicates a change in status of a +> message) and the timestamp at which the status changed. Every delivery report will have a +> unique delivery report ID for use with the confirm delivery reports endpoint. +> *Note: The source number and destination number properties in a delivery report are the inverse of +> those specified in the message that the delivery report relates to. The source number of the +> delivery report is the destination number of the original message.* +> Subsequent requests to the check delivery reports endpoint will return the same delivery reports +> and a maximum of 100 delivery reports will be returned in each request. Applications should use the +> confirm delivery reports endpoint in the following pattern so that delivery reports that have been +> processed are no longer returned in subsequent check delivery reports requests. +> 1. Call check delivery reports endpoint +> 2. Process each delivery report +> 3. Confirm all processed delivery reports using the confirm delivery reports endpoint +> *Note: It is recommended to use the Webhooks feature to receive reply messages rather than +> polling the check delivery reports endpoint.* + + +```php +function getCheckDeliveryReports() +``` + +#### Example Usage + +```php + +$result = $deliveryReports->getCheckDeliveryReports(); + +``` + + +### ![Method: ](https://apidocs.io/img/method.png ".DeliveryReportsController.createConfirmDeliveryReportsAsReceived") createConfirmDeliveryReportsAsReceived + +> Mark a delivery report as confirmed so it is no longer return in check delivery reports requests. +> The confirm delivery reports endpoint is intended to be used in conjunction with the check delivery +> reports endpoint to allow for robust processing of delivery reports. Once one or more delivery +> reports have been processed, they can then be confirmed using the confirm delivery reports endpoint so they +> are no longer returned in subsequent check delivery reports requests. +> The confirm delivery reports endpoint takes a list of delivery report IDs as follows: +> ```json +> { +> "delivery_report_ids": [ +> "011dcead-6988-4ad6-a1c7-6b6c68ea628d", +> "3487b3fa-6586-4979-a233-2d1b095c7718", +> "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" +> ] +> } +> ``` +> Up to 100 delivery reports can be confirmed in a single confirm delivery reports request. + + +```php +function createConfirmDeliveryReportsAsReceived($body) +``` + +#### Parameters + +| Parameter | Tags | Description | +|-----------|------|-------------| +| body | ``` Required ``` | TODO: Add a parameter description | + + + +#### Example Usage + +```php +$bodyValue = "{ \"delivery_report_ids\": [ \"011dcead-6988-4ad6-a1c7-6b6c68ea628d\", \"3487b3fa-6586-4979-a233-2d1b095c7718\", \"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\" ]}"; +$body = APIHelper::deserialize($bodyValue); + +$result = $deliveryReports->createConfirmDeliveryReportsAsReceived($body); + +``` + +#### Errors + +| Error Code | Error Description | +|------------|-------------------| +| 400 | TODO: Add an error description | + + + [Back to List of Controllers](#list_of_controllers) - -## ![Class: ](https://apidocs.io/img/class.png ".RepliesController") RepliesController - -### Get singleton instance - -The singleton instance of the ``` RepliesController ``` class can be accessed from the API Client. - -```php -$replies = $client->getReplies(); -``` - -### ![Method: ](https://apidocs.io/img/method.png ".RepliesController.getCheckReplies") getCheckReplies - -> Check for any replies that have been received. -> Replies are messages that have been sent from a handset in response to a message sent by an -> application or messages that have been sent from a handset to a inbound number associated with -> an account, known as a dedicated inbound number (contact for more -> information on dedicated inbound numbers). -> Each request to the check replies endpoint will return any replies received that have not yet -> been connfirmed using the confirm replies endpoint. A response from the check replies endpoint -> will have the following structure: -> ```json -> { -> "replies": [ -> { -> "metadata": { -> "key1": "value1", -> "key2": "value2" -> }, -> "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", -> "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74", -> "date_received": "2016-12-07T08:43:00.850Z", -> "callback_url": "https://my.callback.url.com", -> "destination_number": "+61491570156", -> "source_number": "+61491570157", -> "vendor_account_id": { -> "vendor_id": "MessageMedia", -> "account_id": "MyAccount" -> }, -> "content": "My first reply!" -> }, -> { -> "metadata": { -> "key1": "value1", -> "key2": "value2" -> }, -> "message_id": "8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4", -> "reply_id": "3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f", -> "date_received": "2016-12-07T08:43:00.850Z", -> "callback_url": "https://my.callback.url.com", -> "destination_number": "+61491570157", -> "source_number": "+61491570158", -> "vendor_account_id": { -> "vendor_id": "MessageMedia", -> "account_id": "MyAccount" -> }, -> "content": "My second reply!" -> } -> ] -> } -> ``` -> Each reply will contain details about the reply message, as well as details of the message the reply was sent -> in response to, including any metadata specified. Every reply will have a reply ID to be used with the -> confirm replies endpoint. -> *Note: The source number and destination number properties in a reply are the inverse of those -> specified in the message the reply is in respons to. The source number of the reply message is the -> same as the destination number of the original message, and the destination number of the reply -> message is the same as the source number of the original message. If a source number -> wasn't specified in the original message, then the destination number property will not be present -> in the reply message.* -> Subseqent requests to the check replies endpoint will return the same reply messages and a maximum -> of 100 replies will be returned in each request. Applications should use the confirm replies endpoint -> in the following pattern so that replies that have been processed are no longer returned in -> subseqent check replies requests. -> 1. Call check replies endpoint -> 2. Process each reply message -> 3. Confirm all processed reply messages using the confirm replies endpoint -> *Note: It is recommended to use the webhooks feature to receieve reply messages rather than polling -> the check replies endpoint.* - - -```php -function getCheckReplies() -``` - -#### Example Usage - -```php - -$result = $replies->getCheckReplies(); - -``` - - -### ![Method: ](https://apidocs.io/img/method.png ".RepliesController.createConfirmRepliesAsReceived") createConfirmRepliesAsReceived - -> Mark a reply message as confirmed so it is no longer returned in check replies requests. -> The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint -> to allow for robust processing of reply messages. Once one or more reply messages have been processed -> they can then be confirmed using the confirm replies endpoint so they are no longer returned in -> subsequent check replies requests. -> The confirm replies endpoint takes a list of reply IDs as follows: -> ```json -> { -> "reply_ids": [ -> "011dcead-6988-4ad6-a1c7-6b6c68ea628d", -> "3487b3fa-6586-4979-a233-2d1b095c7718", -> "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" -> ] -> } -> ``` -> Up to 100 replies can be confirmed in a single confirm replies request. - - -```php -function createConfirmRepliesAsReceived($body) -``` - -#### Parameters - -| Parameter | Tags | Description | -|-----------|------|-------------| -| body | ``` Required ``` | TODO: Add a parameter description | - - - -#### Example Usage - -```php -$bodyValue = "{ \"reply_ids\": [ \"011dcead-6988-4ad6-a1c7-6b6c68ea628d\", \"3487b3fa-6586-4979-a233-2d1b095c7718\", \"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\" ]}"; -$body = APIHelper::deserialize($bodyValue); - -$result = $replies->createConfirmRepliesAsReceived($body); - -``` - -#### Errors - -| Error Code | Error Description | -|------------|-------------------| -| 400 | TODO: Add an error description | - - - + +## ![Class: ](https://apidocs.io/img/class.png ".RepliesController") RepliesController + +### Get singleton instance + +The singleton instance of the ``` RepliesController ``` class can be accessed from the API Client. + +```php +$replies = $client->getReplies(); +``` + +### ![Method: ](https://apidocs.io/img/method.png ".RepliesController.createConfirmRepliesAsReceived") createConfirmRepliesAsReceived + +> Mark a reply message as confirmed so it is no longer returned in check replies requests. +> The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint +> to allow for robust processing of reply messages. Once one or more reply messages have been processed +> they can then be confirmed using the confirm replies endpoint so they are no longer returned in +> subsequent check replies requests. +> The confirm replies endpoint takes a list of reply IDs as follows: +> ```json +> { +> "reply_ids": [ +> "011dcead-6988-4ad6-a1c7-6b6c68ea628d", +> "3487b3fa-6586-4979-a233-2d1b095c7718", +> "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" +> ] +> } +> ``` +> Up to 100 replies can be confirmed in a single confirm replies request. + + +```php +function createConfirmRepliesAsReceived($body) +``` + +#### Parameters + +| Parameter | Tags | Description | +|-----------|------|-------------| +| body | ``` Required ``` | TODO: Add a parameter description | + + + +#### Example Usage + +```php +$bodyValue = "{ \"reply_ids\": [ \"011dcead-6988-4ad6-a1c7-6b6c68ea628d\", \"3487b3fa-6586-4979-a233-2d1b095c7718\", \"ba28e94b-c83d-4759-98e7-ff9c7edb87a1\" ]}"; +$body = APIHelper::deserialize($bodyValue); + +$result = $replies->createConfirmRepliesAsReceived($body); + +``` + +#### Errors + +| Error Code | Error Description | +|------------|-------------------| +| 400 | TODO: Add an error description | + + + +### ![Method: ](https://apidocs.io/img/method.png ".RepliesController.getCheckReplies") getCheckReplies + +> Check for any replies that have been received. +> Replies are messages that have been sent from a handset in response to a message sent by an +> application or messages that have been sent from a handset to a inbound number associated with +> an account, known as a dedicated inbound number (contact for more +> information on dedicated inbound numbers). +> Each request to the check replies endpoint will return any replies received that have not yet +> been confirmed using the confirm replies endpoint. A response from the check replies endpoint +> will have the following structure: +> ```json +> { +> "replies": [ +> { +> "metadata": { +> "key1": "value1", +> "key2": "value2" +> }, +> "message_id": "877c19ef-fa2e-4cec-827a-e1df9b5509f7", +> "reply_id": "a175e797-2b54-468b-9850-41a3eab32f74", +> "date_received": "2016-12-07T08:43:00.850Z", +> "callback_url": "https://my.callback.url.com", +> "destination_number": "+61491570156", +> "source_number": "+61491570157", +> "vendor_account_id": { +> "vendor_id": "MessageMedia", +> "account_id": "MyAccount" +> }, +> "content": "My first reply!" +> }, +> { +> "metadata": { +> "key1": "value1", +> "key2": "value2" +> }, +> "message_id": "8f2f5927-2e16-4f1c-bd43-47dbe2a77ae4", +> "reply_id": "3d8d53d8-01d3-45dd-8cfa-4dfc81600f7f", +> "date_received": "2016-12-07T08:43:00.850Z", +> "callback_url": "https://my.callback.url.com", +> "destination_number": "+61491570157", +> "source_number": "+61491570158", +> "vendor_account_id": { +> "vendor_id": "MessageMedia", +> "account_id": "MyAccount" +> }, +> "content": "My second reply!" +> } +> ] +> } +> ``` +> Each reply will contain details about the reply message, as well as details of the message the reply was sent +> in response to, including any metadata specified. Every reply will have a reply ID to be used with the +> confirm replies endpoint. +> *Note: The source number and destination number properties in a reply are the inverse of those +> specified in the message the reply is in response to. The source number of the reply message is the +> same as the destination number of the original message, and the destination number of the reply +> message is the same as the source number of the original message. If a source number +> wasn't specified in the original message, then the destination number property will not be present +> in the reply message.* +> Subsequent requests to the check replies endpoint will return the same reply messages and a maximum +> of 100 replies will be returned in each request. Applications should use the confirm replies endpoint +> in the following pattern so that replies that have been processed are no longer returned in +> subsequent check replies requests. +> 1. Call check replies endpoint +> 2. Process each reply message +> 3. Confirm all processed reply messages using the confirm replies endpoint +> *Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling +> the check replies endpoint.* + + +```php +function getCheckReplies() +``` + +#### Example Usage + +```php + +$result = $replies->getCheckReplies(); + +``` + + [Back to List of Controllers](#list_of_controllers) - - - + + + diff --git a/appveyor.yml b/appveyor.yml new file mode 100644 index 0000000..b6df2f8 --- /dev/null +++ b/appveyor.yml @@ -0,0 +1,37 @@ +# Appveyor should automatically run the tests. +# For configuration options, visit: https://www.appveyor.com/docs/running-tests +# Appveyor should automatically run the tests. +# For configuration options, visit: https://www.appveyor.com/docs/running-tests +build: false +shallow_clone: true +clone_folder: c:\projects\composer + +cache: + - c:\tools\php -> appveyor.yml + +init: + - SET PATH=C:\Program Files\OpenSSL;c:\tools\php;%PATH% + - SET COMPOSER_NO_INTERACTION=1 + - SET PHP=1 + - SET ANSICON=121x90 (121x90) + +install: + - IF EXIST c:\tools\php (SET PHP=0) + - IF %PHP%==1 cinst -y OpenSSL.Light + - IF %PHP%==1 cinst -y php + - cd c:\tools\php + - IF %PHP%==1 copy php.ini-production php.ini /Y + - IF %PHP%==1 echo date.timezone="UTC" >> php.ini + - IF %PHP%==1 echo extension_dir=ext >> php.ini + - IF %PHP%==1 echo extension=php_openssl.dll >> php.ini + - IF %PHP%==1 echo extension=php_mbstring.dll >> php.ini + - IF %PHP%==1 echo extension=php_fileinfo.dll >> php.ini + - IF %PHP%==1 echo extension=php_curl.dll >> php.ini + - IF %PHP%==1 echo @php %%~dp0composer.phar %%* > composer.bat + - appveyor DownloadFile https://getcomposer.org/composer.phar + - cd c:\projects\composer + - composer install --prefer-dist --no-progress + +test_script: + - cd c:\projects\composer + - vendor/bin/phpunit.bat diff --git a/circle.yml b/circle.yml new file mode 100644 index 0000000..d53347d --- /dev/null +++ b/circle.yml @@ -0,0 +1,5 @@ +# Circle CI should automatically run the tests. +# For configuration options, visit: https://circleci.com/docs/configuration/ +machine: + php: + version: 5.6.22 \ No newline at end of file diff --git a/composer.json b/composer.json index af08700..d94ffe1 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,8 @@ { - "name": "apimatic/messages", + "name": "messagemedia/messages", "type": "library", - "description": "TODO: Add a description", + "description": "The MessageMedia Messages API provides a number of endpoints for building powerful two-way messaging applications.", + "version": "1.0.0", "keywords": ["Messages","API","SDK"], "homepage": "https://apimatic.io", "license": "MIT", @@ -28,7 +29,7 @@ }, "autoload": { "psr-4": { - "MessagesLib\\": "src/" + "MessageMediaMessagesLib\\": "src/" } } } \ No newline at end of file diff --git a/phpunit.xml b/phpunit.xml index f43c52b..2782d19 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -1,20 +1,20 @@ - - - - - ./tests - - + + + + + ./tests + + \ No newline at end of file diff --git a/src/APIException.php b/src/APIException.php index 28c0fe9..386a531 100644 --- a/src/APIException.php +++ b/src/APIException.php @@ -1,11 +1,11 @@ 'APIMATIC 2.0', + 'user-agent' => 'messagemedia-messages', 'Accept' => 'application/json' ); + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + //call on-before Http callback $_httpRequest = new HttpRequest(HttpMethod::GET, $_headers, $_queryUrl); if ($this->getHttpCallBack() != null) { @@ -151,7 +154,7 @@ public function getCheckDeliveryReports() $mapper = $this->getJsonMapper(); - return $mapper->mapClass($response->body, 'MessagesLib\\Models\\CheckDeliveryReportsResponse'); + return $mapper->mapClass($response->body, 'MessageMediaMessagesLib\\Models\\CheckDeliveryReportsResponse'); } /** @@ -192,11 +195,14 @@ public function createConfirmDeliveryReportsAsReceived( //prepare headers $_headers = array ( - 'user-agent' => 'APIMATIC 2.0', + 'user-agent' => 'messagemedia-messages', 'Accept' => 'application/json', 'content-type' => 'application/json; charset=utf-8' ); + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + //call on-before Http callback $_httpRequest = new HttpRequest(HttpMethod::POST, $_headers, $_queryUrl); if ($this->getHttpCallBack() != null) { diff --git a/src/Controllers/MessagesController.php b/src/Controllers/MessagesController.php index 4fd6c01..b3dd2ae 100644 --- a/src/Controllers/MessagesController.php +++ b/src/Controllers/MessagesController.php @@ -1,21 +1,21 @@ 'APIMATIC 2.0', + 'user-agent' => 'messagemedia-messages', 'Accept' => 'application/json', 'content-type' => 'application/json; charset=utf-8' ); + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + //call on-before Http callback $_httpRequest = new HttpRequest(HttpMethod::PUT, $_headers, $_queryUrl); if ($this->getHttpCallBack() != null) { @@ -144,7 +147,7 @@ public function updateCancelScheduledMessage( * } * ``` * The status property of the response indicates the current status of the message. See the Delivery - * Reports section of this documenation for more information on message statues. + * Reports section of this documentation for more information on message statues. * *Note: If an invalid or non existent message ID parameter is specified in the request, then * a HTTP 404 Not Found response will be returned* * @@ -172,10 +175,13 @@ public function getMessageStatus( //prepare headers $_headers = array ( - 'user-agent' => 'APIMATIC 2.0', + 'user-agent' => 'messagemedia-messages', 'Accept' => 'application/json' ); + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + //call on-before Http callback $_httpRequest = new HttpRequest(HttpMethod::GET, $_headers, $_queryUrl); if ($this->getHttpCallBack() != null) { @@ -218,7 +224,7 @@ public function getMessageStatus( * } * ``` * More advanced delivery features can be specified by setting the following properties in a message: - * - ```callback_url``` A URL can be included with each message to which webhooks will be pushed to + * - ```callback_url``` A URL can be included with each message to which Webhooks will be pushed to * via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as * it is processed (if the delivery report property of the request is set to ```true```) and when * replies @@ -226,9 +232,10 @@ public function getMessageStatus( * - ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters * long. * Message content is required. - * - ```delivery_report``` Delivery reports can be be requested with each message. If delivery reports - * are requested, a webhook - * will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) + * - ```delivery_report``` Delivery reports can be requested with each message. If delivery reports are + * requested, a webhook + * will be submitted to the ```callback_url``` property specified for the message (or to the + * webhooks) * specified for the account every time the status of the message changes as it is processed. The * current status of the message can also be retrieved via the Delivery Reports endpoint of the * Messages API. Delivery reports are optional and by default will not be requested. @@ -240,26 +247,28 @@ public function getMessageStatus( * message) * or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read * out the - * message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will - * be used. + * message using a computer generated voice. Specifying a format is optional, by default ```SMS``` + * will be used. * - ```source_number``` A source number may be specified for the message, this will be the number * that * the message appears from on the handset. By default this feature is _not_ available and will be * ignored - * in the request. Please contact for more information. Specifying a source + * in the request. Please contact for more information. Specifying a + * source * number is optional and a by default a source number will be assigned to the message. * - ```source_number_type``` If a source number is specified, the type of source number may also be * specified. This is recommended when using a source address type that is not an internationally * formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. - * Speciying a - * source number type is only valid when a the ```source_number``` parameter is specified and is + * Specifying a + * source number type is only valid when the ```source_number``` parameter is specified and is * optional. - * If a source number is specified and no source number type is specified, the source number type will - * be + * If a source number is specified and no source number type is specified, the source number type + * will be * inferred from the source number, however this may be inaccurate. * - ```scheduled``` A message can be scheduled for delivery in the future by setting the scheduled * property. - * The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be + * The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must + * be * provided in UTC and is optional. If no scheduled property is set, the message will be delivered * immediately. * - ```message_expiry_timestamp``` A message expiry timestamp can be provided to specify the latest @@ -270,10 +279,11 @@ public function getMessageStatus( * - ```metadata``` Metadata can be included with the message which will then be included with any * delivery * reports or replies matched to the message. This can be used to create powerful two-way messaging - * applications without having to store persitant data in the application. Up to 10 key / value metada - * data - * pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to - * 256 characters long. Specifiying metadata for a message is optional. + * applications without having to store persistent data in the application. Up to 10 key / value + * metadata data + * pairs can be specified in a message. Each key can be up to 100 characters long, and each value up + * to + * 256 characters long. Specifying metadata for a message is optional. * The response body of a successful POST request to the messages endpoint will include a * ```messages``` * property which contains a list of all messages submitted. The list of messages submitted will @@ -282,7 +292,8 @@ public function getMessageStatus( * which can be used to check the status of the message via the Get Message Status endpoint. The * status * of the message which reflect the status of the message at submission time which will always be - * ```queued```. See the Delivery Reports section of this documenation for more information on message + * ```queued```. See the Delivery Reports section of this documentation for more information on + * message * statues. * *Note: when sending multiple messages in a request, all messages must be valid for the request to be * successful. @@ -307,11 +318,14 @@ public function createSendMessages( //prepare headers $_headers = array ( - 'user-agent' => 'APIMATIC 2.0', + 'user-agent' => 'messagemedia-messages', 'Accept' => 'application/json', 'content-type' => 'application/json; charset=utf-8' ); + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + //call on-before Http callback $_httpRequest = new HttpRequest(HttpMethod::POST, $_headers, $_queryUrl); if ($this->getHttpCallBack() != null) { @@ -339,6 +353,6 @@ public function createSendMessages( $mapper = $this->getJsonMapper(); - return $mapper->mapClass($response->body, 'MessagesLib\\Models\\SendMessagesResponse'); + return $mapper->mapClass($response->body, 'MessageMediaMessagesLib\\Models\\SendMessagesResponse'); } } diff --git a/src/Controllers/RepliesController.php b/src/Controllers/RepliesController.php index f442f65..0e472c6 100644 --- a/src/Controllers/RepliesController.php +++ b/src/Controllers/RepliesController.php @@ -1,21 +1,21 @@ 'messagemedia-messages', + 'Accept' => 'application/json', + 'content-type' => 'application/json; charset=utf-8' + ); + + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + + //call on-before Http callback + $_httpRequest = new HttpRequest(HttpMethod::POST, $_headers, $_queryUrl); + if ($this->getHttpCallBack() != null) { + $this->getHttpCallBack()->callOnBeforeRequest($_httpRequest); + } + + //and invoke the API call request to fetch the response + $response = Request::post($_queryUrl, $_headers, Request\Body::Json($body)); + + $_httpResponse = new HttpResponse($response->code, $response->headers, $response->raw_body); + $_httpContext = new HttpContext($_httpRequest, $_httpResponse); + + //call on-after Http callback + if ($this->getHttpCallBack() != null) { + $this->getHttpCallBack()->callOnAfterRequest($_httpContext); + } + + //Error handling using HTTP status codes + if ($response->code == 400) { + throw new APIException('', $_httpContext); + } + + //handle errors defined at the API level + $this->validateResponse($_httpResponse, $_httpContext); + + return $response->body; + } + /** * Check for any replies that have been received. * Replies are messages that have been sent from a handset in response to a message sent by an @@ -48,7 +122,7 @@ public static function getInstance() * an account, known as a dedicated inbound number (contact for more * information on dedicated inbound numbers). * Each request to the check replies endpoint will return any replies received that have not yet - * been connfirmed using the confirm replies endpoint. A response from the check replies endpoint + * been confirmed using the confirm replies endpoint. A response from the check replies endpoint * will have the following structure: * ```json * { @@ -96,20 +170,20 @@ public static function getInstance() * the * confirm replies endpoint. * *Note: The source number and destination number properties in a reply are the inverse of those - * specified in the message the reply is in respons to. The source number of the reply message is the + * specified in the message the reply is in response to. The source number of the reply message is the * same as the destination number of the original message, and the destination number of the reply * message is the same as the source number of the original message. If a source number * wasn't specified in the original message, then the destination number property will not be present * in the reply message.* - * Subseqent requests to the check replies endpoint will return the same reply messages and a maximum + * Subsequent requests to the check replies endpoint will return the same reply messages and a maximum * of 100 replies will be returned in each request. Applications should use the confirm replies * endpoint * in the following pattern so that replies that have been processed are no longer returned in - * subseqent check replies requests. + * subsequent check replies requests. * 1. Call check replies endpoint * 2. Process each reply message * 3. Confirm all processed reply messages using the confirm replies endpoint - * *Note: It is recommended to use the webhooks feature to receieve reply messages rather than polling + * *Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling * the check replies endpoint.* * * @return mixed response from the API call @@ -129,10 +203,13 @@ public function getCheckReplies() //prepare headers $_headers = array ( - 'user-agent' => 'APIMATIC 2.0', + 'user-agent' => 'messagemedia-messages', 'Accept' => 'application/json' ); + //set HTTP basic auth parameters + Request::auth(Configuration::$basicAuthUserName, Configuration::$basicAuthPassword); + //call on-before Http callback $_httpRequest = new HttpRequest(HttpMethod::GET, $_headers, $_queryUrl); if ($this->getHttpCallBack() != null) { @@ -155,77 +232,6 @@ public function getCheckReplies() $mapper = $this->getJsonMapper(); - return $mapper->mapClass($response->body, 'MessagesLib\\Models\\CheckRepliesResponse'); - } - - /** - * Mark a reply message as confirmed so it is no longer returned in check replies requests. - * The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint - * to allow for robust processing of reply messages. Once one or more reply messages have been - * processed - * they can then be confirmed using the confirm replies endpoint so they are no longer returned in - * subsequent check replies requests. - * The confirm replies endpoint takes a list of reply IDs as follows: - * ```json - * { - * "reply_ids": [ - * "011dcead-6988-4ad6-a1c7-6b6c68ea628d", - * "3487b3fa-6586-4979-a233-2d1b095c7718", - * "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" - * ] - * } - * ``` - * Up to 100 replies can be confirmed in a single confirm replies request. - * - * @param Models\ConfirmRepliesAsReceivedRequest $body TODO: type description here - * @return mixed response from the API call - * @throws APIException Thrown if API call fails - */ - public function createConfirmRepliesAsReceived( - $body - ) { - - //the base uri for api requests - $_queryBuilder = Configuration::$BASEURI; - - //prepare query string for API call - $_queryBuilder = $_queryBuilder.'/v1/replies/confirmed'; - - //validate and preprocess url - $_queryUrl = APIHelper::cleanUrl($_queryBuilder); - - //prepare headers - $_headers = array ( - 'user-agent' => 'APIMATIC 2.0', - 'Accept' => 'application/json', - 'content-type' => 'application/json; charset=utf-8' - ); - - //call on-before Http callback - $_httpRequest = new HttpRequest(HttpMethod::POST, $_headers, $_queryUrl); - if ($this->getHttpCallBack() != null) { - $this->getHttpCallBack()->callOnBeforeRequest($_httpRequest); - } - - //and invoke the API call request to fetch the response - $response = Request::post($_queryUrl, $_headers, Request\Body::Json($body)); - - $_httpResponse = new HttpResponse($response->code, $response->headers, $response->raw_body); - $_httpContext = new HttpContext($_httpRequest, $_httpResponse); - - //call on-after Http callback - if ($this->getHttpCallBack() != null) { - $this->getHttpCallBack()->callOnAfterRequest($_httpContext); - } - - //Error handling using HTTP status codes - if ($response->code == 400) { - throw new APIException('', $_httpContext); - } - - //handle errors defined at the API level - $this->validateResponse($_httpResponse, $_httpContext); - - return $response->body; + return $mapper->mapClass($response->body, 'MessageMediaMessagesLib\\Models\\CheckRepliesResponse'); } } diff --git a/src/Http/HttpCallBack.php b/src/Http/HttpCallBack.php index 96e3ecb..efa7470 100644 --- a/src/Http/HttpCallBack.php +++ b/src/Http/HttpCallBack.php @@ -1,11 +1,11 @@ getDeliveryReports(); } @@ -105,7 +105,7 @@ protected function setUp() 1. Call check delivery reports endpoint 2. Process each delivery report 3. Confirm all processed delivery reports using the confirm delivery reports endpoint -*Note: It is recommended to use the webhooks feature to receive reply messages rather than +*Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check delivery reports endpoint.* */ public function testCheckDeliveryReports1() diff --git a/tests/Controllers/MessagesControllerTest.php b/tests/Controllers/MessagesControllerTest.php index 5a35aad..833c88c 100644 --- a/tests/Controllers/MessagesControllerTest.php +++ b/tests/Controllers/MessagesControllerTest.php @@ -1,21 +1,21 @@ getMessages(); } @@ -55,52 +55,52 @@ protected function setUp() } ``` More advanced delivery features can be specified by setting the following properties in a message: -- ```callback_url``` A URL can be included with each message to which webhooks will be pushed to -via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as -it is processed (if the delivery report property of the request is set to ```true```) and when replies -are received. Specifying a callback URL is optional. +- ```callback_url``` A URL can be included with each message to which Webhooks will be pushed to + via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as + it is processed (if the delivery report property of the request is set to ```true```) and when replies + are received. Specifying a callback URL is optional. - ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters long. -Message content is required. -- ```delivery_report``` Delivery reports can be be requested with each message. If delivery reports are requested, a webhook -will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) -specified for the account every time the status of the message changes as it is processed. The -current status of the message can also be retrieved via the Delivery Reports endpoint of the -Messages API. Delivery reports are optional and by default will not be requested. + Message content is required. +- ```delivery_report``` Delivery reports can be requested with each message. If delivery reports are requested, a webhook + will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) + specified for the account every time the status of the message changes as it is processed. The + current status of the message can also be retrieved via the Delivery Reports endpoint of the + Messages API. Delivery reports are optional and by default will not be requested. - ```destination_number``` The destination number the message should be delivered to. This should be specified in E.164 -international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. -A destination number is required. + international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. + A destination number is required. - ```format``` The format specifies which format the message will be sent as, ```SMS``` (text message) -or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the -message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used. + or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the + message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used. - ```source_number``` A source number may be specified for the message, this will be the number that -the message appears from on the handset. By default this feature is _not_ available and will be ignored -in the request. Please contact for more information. Specifying a source -number is optional and a by default a source number will be assigned to the message. + the message appears from on the handset. By default this feature is _not_ available and will be ignored + in the request. Please contact for more information. Specifying a source + number is optional and a by default a source number will be assigned to the message. - ```source_number_type``` If a source number is specified, the type of source number may also be -specified. This is recommended when using a source address type that is not an internationally -formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Speciying a -source number type is only valid when a the ```source_number``` parameter is specified and is optional. -If a source number is specified and no source number type is specified, the source number type will be -inferred from the source number, however this may be inaccurate. + specified. This is recommended when using a source address type that is not an internationally + formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Specifying a + source number type is only valid when the ```source_number``` parameter is specified and is optional. + If a source number is specified and no source number type is specified, the source number type will be + inferred from the source number, however this may be inaccurate. - ```scheduled``` A message can be scheduled for delivery in the future by setting the scheduled property. -The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be -provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. + The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be + provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. - ```message_expiry_timestamp``` A message expiry timestamp can be provided to specify the latest time -at which the message should be delivered. If the message cannot be delivered before the specified -message expiry timestamp elapses, the message will be discarded. Specifying a message expiry -timestamp is optional. + at which the message should be delivered. If the message cannot be delivered before the specified + message expiry timestamp elapses, the message will be discarded. Specifying a message expiry + timestamp is optional. - ```metadata``` Metadata can be included with the message which will then be included with any delivery -reports or replies matched to the message. This can be used to create powerful two-way messaging -applications without having to store persitant data in the application. Up to 10 key / value metada data -pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to -256 characters long. Specifiying metadata for a message is optional. + reports or replies matched to the message. This can be used to create powerful two-way messaging + applications without having to store persistent data in the application. Up to 10 key / value metadata data + pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to + 256 characters long. Specifying metadata for a message is optional. The response body of a successful POST request to the messages endpoint will include a ```messages``` property which contains a list of all messages submitted. The list of messages submitted will reflect the list of messages included in the request, but each message will also contain two new properties, ```message_id``` and ```status```. The returned message ID will be a 36 character UUID which can be used to check the status of the message via the Get Message Status endpoint. The status of the message which reflect the status of the message at submission time which will always be -```queued```. See the Delivery Reports section of this documenation for more information on message +```queued```. See the Delivery Reports section of this documentation for more information on message statues. *Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. If any messages in the request are invalid, no messages will be sent.* @@ -162,126 +162,4 @@ public function testSendMessages1() "Response body does not match exactly" ); } - - /** - * Submit one or more (up to 100 per request) SMS or text to voice messages for delivery. -The most basic message has the following structure: -```json -{ - "messages": [ - { - "content": "My first message!", - "destination_number": "+61491570156" - } - ] -} -``` -More advanced delivery features can be specified by setting the following properties in a message: -- ```callback_url``` A URL can be included with each message to which webhooks will be pushed to -via a HTTP POST request. Webhooks will be sent if and when the status of the message changes as -it is processed (if the delivery report property of the request is set to ```true```) and when replies -are received. Specifying a callback URL is optional. -- ```content``` The content of the message. This can be a Unicode string, up to 5,000 characters long. -Message content is required. -- ```delivery_report``` Delivery reports can be be requested with each message. If delivery reports are requested, a webhook -will be submitted to the ```callback_url``` property specified for the message (or to the webhooks) -specified for the account every time the status of the message changes as it is processed. The -current status of the message can also be retrieved via the Delivery Reports endpoint of the -Messages API. Delivery reports are optional and by default will not be requested. -- ```destination_number``` The destination number the message should be delivered to. This should be specified in E.164 -international format. For information on E.164, please refer to http://en.wikipedia.org/wiki/E.164. -A destination number is required. -- ```format``` The format specifies which format the message will be sent as, ```SMS``` (text message) -or ```TTS``` (text to speech). With ```TTS``` format, we will call the destination number and read out the -message using a computer generated voice. Specifying a format is optional, by default ```SMS``` will be used. -- ```source_number``` A source number may be specified for the message, this will be the number that -the message appears from on the handset. By default this feature is _not_ available and will be ignored -in the request. Please contact for more information. Specifying a source -number is optional and a by default a source number will be assigned to the message. -- ```source_number_type``` If a source number is specified, the type of source number may also be -specified. This is recommended when using a source address type that is not an internationally -formatted number, available options are ```INTERNATIONAL```, ```ALPHANUMERIC``` or ```SHORTCODE```. Speciying a -source number type is only valid when a the ```source_number``` parameter is specified and is optional. -If a source number is specified and no source number type is specified, the source number type will be -inferred from the source number, however this may be inaccurate. -- ```scheduled``` A message can be scheduled for delivery in the future by setting the scheduled property. -The scheduled property expects a date time specified in ISO 8601 format. The scheduled time must be -provided in UTC and is optional. If no scheduled property is set, the message will be delivered immediately. -- ```message_expiry_timestamp``` A message expiry timestamp can be provided to specify the latest time -at which the message should be delivered. If the message cannot be delivered before the specified -message expiry timestamp elapses, the message will be discarded. Specifying a message expiry -timestamp is optional. -- ```metadata``` Metadata can be included with the message which will then be included with any delivery -reports or replies matched to the message. This can be used to create powerful two-way messaging -applications without having to store persitant data in the application. Up to 10 key / value metada data -pairs can be specified in a message. Each key can be up to 100 characters long, and each value up to -256 characters long. Specifiying metadata for a message is optional. -The response body of a successful POST request to the messages endpoint will include a ```messages``` -property which contains a list of all messages submitted. The list of messages submitted will -reflect the list of messages included in the request, but each message will also contain two new -properties, ```message_id``` and ```status```. The returned message ID will be a 36 character UUID -which can be used to check the status of the message via the Get Message Status endpoint. The status -of the message which reflect the status of the message at submission time which will always be -```queued```. See the Delivery Reports section of this documenation for more information on message -statues. -*Note: when sending multiple messages in a request, all messages must be valid for the request to be successful. -If any messages in the request are invalid, no messages will be sent.* - */ - public function testSendMessages2() - { - // Parameters for the API call - $body = APIHelper::deserialize( - '{ "messages": [ { "callback_url": "https://my.callback.url.com", "co' . - 'ntent": "My first message", "destination_number": "+61491570156", "delivery_re' . - 'port": true, "format": "SMS", "message_expiry_timestamp": "2016-11-03T11:49:02' . - '.807Z", "metadata": { "key1": "value1", "key2": "value2" ' . - ' }, "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+614915' . - '70157", "source_number_type": "INTERNATIONAL" }, { "callback_url' . - '": "https://my.callback.url.com", "content": "My second message", "destination' . - '_number": "+61491570158", "delivery_report": true, "format": "SMS", ' . - ' "message_expiry_timestamp": "2016-11-03T11:49:02.807Z", "metadata": { "ke' . - 'y1": "value1", "key2": "value2" }, "scheduled": "2016-11-03T11:' . - '49:02.807Z", "source_number": "+61491570159", "source_number_type": "INTERNATI' . - 'ONAL" } ]}', - new Models\SendMessagesRequest() - ); - - // Set callback and perform API call - $result = null; - self::$controller->setHttpCallBack($this->httpResponse); - try { - $result = self::$controller->createSendMessages($body); - } catch (APIException $e) { - } - - // Test response code - $this->assertEquals( - 202, - $this->httpResponse->getResponse()->getStatusCode(), - "Status is not 202" - ); - - // Test headers - $headers = []; - $headers['Content-Type'] = null ; - - $this->assertTrue( - TestHelper::areHeadersProperSubsetOf($headers, $this->httpResponse->getResponse()->getHeaders(), true), - "Headers do not match" - ); - - // Test whether the captured response is as we expected - $this->assertNotNull($result, "Result does not exist"); - - $this->assertEquals( - '{ "messages": [ { "message_id": "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a", "callback_url"' . - ': "https://my.url.com", "status": "delivered", "content": "My first message", "destin' . - 'ation_number": "+61491570156", "delivery_report": true, "format": "SMS", "message_exp' . - 'iry_timestamp": "2016-11-03T11:49:02.807Z", "metadata": { "key1": "value1", "key2' . - '": "value2" }, "scheduled": "2016-11-03T11:49:02.807Z", "source_number": "+6149157015' . - '7", "source_number_type": "INTERNATIONAL" } ]}', - $this->httpResponse->getResponse()->getRawBody(), - "Response body does not match exactly" - ); - } } diff --git a/tests/Controllers/RepliesControllerTest.php b/tests/Controllers/RepliesControllerTest.php index 85b912d..db82a61 100644 --- a/tests/Controllers/RepliesControllerTest.php +++ b/tests/Controllers/RepliesControllerTest.php @@ -1,21 +1,21 @@ getReplies(); } @@ -41,6 +41,58 @@ protected function setUp() $this->httpResponse = new HttpCallBackCatcher(); } + /** + * Mark a reply message as confirmed so it is no longer returned in check replies requests. +The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint +to allow for robust processing of reply messages. Once one or more reply messages have been processed +they can then be confirmed using the confirm replies endpoint so they are no longer returned in +subsequent check replies requests. +The confirm replies endpoint takes a list of reply IDs as follows: +```json +{ + "reply_ids": [ + "011dcead-6988-4ad6-a1c7-6b6c68ea628d", + "3487b3fa-6586-4979-a233-2d1b095c7718", + "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" + ] +} +``` +Up to 100 replies can be confirmed in a single confirm replies request. + */ + public function testConfirmRepliesAsReceived1() + { + // Parameters for the API call + $body = APIHelper::deserialize( + '{ "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2' . + 'd1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ]}', + new Models\ConfirmRepliesAsReceivedRequest() + ); + + // Set callback and perform API call + $result = null; + self::$controller->setHttpCallBack($this->httpResponse); + try { + $result = self::$controller->createConfirmRepliesAsReceived($body); + } catch (APIException $e) { + } + + // Test response code + $this->assertEquals( + 202, + $this->httpResponse->getResponse()->getStatusCode(), + "Status is not 202" + ); + + // Test headers + $headers = []; + $headers['Content-Type'] = null ; + + $this->assertTrue( + TestHelper::areHeadersProperSubsetOf($headers, $this->httpResponse->getResponse()->getHeaders(), true), + "Headers do not match" + ); + } + /** * Check for any replies that have been received. Replies are messages that have been sent from a handset in response to a message sent by an @@ -48,7 +100,7 @@ protected function setUp() an account, known as a dedicated inbound number (contact for more information on dedicated inbound numbers). Each request to the check replies endpoint will return any replies received that have not yet -been connfirmed using the confirm replies endpoint. A response from the check replies endpoint +been confirmed using the confirm replies endpoint. A response from the check replies endpoint will have the following structure: ```json { @@ -94,19 +146,19 @@ protected function setUp() in response to, including any metadata specified. Every reply will have a reply ID to be used with the confirm replies endpoint. *Note: The source number and destination number properties in a reply are the inverse of those -specified in the message the reply is in respons to. The source number of the reply message is the +specified in the message the reply is in response to. The source number of the reply message is the same as the destination number of the original message, and the destination number of the reply message is the same as the source number of the original message. If a source number wasn't specified in the original message, then the destination number property will not be present in the reply message.* -Subseqent requests to the check replies endpoint will return the same reply messages and a maximum +Subsequent requests to the check replies endpoint will return the same reply messages and a maximum of 100 replies will be returned in each request. Applications should use the confirm replies endpoint in the following pattern so that replies that have been processed are no longer returned in -subseqent check replies requests. +subsequent check replies requests. 1. Call check replies endpoint 2. Process each reply message 3. Confirm all processed reply messages using the confirm replies endpoint -*Note: It is recommended to use the webhooks feature to receieve reply messages rather than polling +*Note: It is recommended to use the Webhooks feature to receive reply messages rather than polling the check replies endpoint.* */ public function testCheckReplies1() @@ -155,56 +207,4 @@ public function testCheckReplies1() "Response body does not match exactly" ); } - - /** - * Mark a reply message as confirmed so it is no longer returned in check replies requests. -The confirm replies endpoint is intended to be used in conjunction with the check replies endpoint -to allow for robust processing of reply messages. Once one or more reply messages have been processed -they can then be confirmed using the confirm replies endpoint so they are no longer returned in -subsequent check replies requests. -The confirm replies endpoint takes a list of reply IDs as follows: -```json -{ - "reply_ids": [ - "011dcead-6988-4ad6-a1c7-6b6c68ea628d", - "3487b3fa-6586-4979-a233-2d1b095c7718", - "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" - ] -} -``` -Up to 100 replies can be confirmed in a single confirm replies request. - */ - public function testConfirmRepliesAsReceived1() - { - // Parameters for the API call - $body = APIHelper::deserialize( - '{ "reply_ids": [ "011dcead-6988-4ad6-a1c7-6b6c68ea628d", "3487b3fa-6586-4979-a233-2' . - 'd1b095c7718", "ba28e94b-c83d-4759-98e7-ff9c7edb87a1" ]}', - new Models\ConfirmRepliesAsReceivedRequest() - ); - - // Set callback and perform API call - $result = null; - self::$controller->setHttpCallBack($this->httpResponse); - try { - $result = self::$controller->createConfirmRepliesAsReceived($body); - } catch (APIException $e) { - } - - // Test response code - $this->assertEquals( - 202, - $this->httpResponse->getResponse()->getStatusCode(), - "Status is not 202" - ); - - // Test headers - $headers = []; - $headers['Content-Type'] = null ; - - $this->assertTrue( - TestHelper::areHeadersProperSubsetOf($headers, $this->httpResponse->getResponse()->getHeaders(), true), - "Headers do not match" - ); - } } diff --git a/tests/HttpCallBackCatcher.php b/tests/HttpCallBackCatcher.php index 4fe9aae..c31b437 100644 --- a/tests/HttpCallBackCatcher.php +++ b/tests/HttpCallBackCatcher.php @@ -1,13 +1,13 @@