Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit c005507

Browse files
Update Documentation
1 parent dcaf49b commit c005507

File tree

1 file changed

+139
-111
lines changed

1 file changed

+139
-111
lines changed

‎DOCUMENTATION.md

Lines changed: 139 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -132,202 +132,230 @@ $client = new MessageMediaWebhooksLib\MessageMediaWebhooksClient($basicAuthUserN
132132

133133
## <a name="list_of_controllers"></a>List of Controllers
134134

135-
* [APIController](#api_controller)
135+
* [WebhooksController](#webhooks_controller)
136136

137-
## <a name="api_controller"></a>![Class: ](https://apidocs.io/img/class.png ".APIController") APIController
137+
## <a name="webhooks_controller"></a>![Class: ](https://apidocs.io/img/class.png ".WebhooksController") WebhooksController
138138

139139
### Get singleton instance
140140

141-
The singleton instance of the ``` APIController ``` class can be accessed from the API Client.
141+
The singleton instance of the ``` WebhooksController ``` class can be accessed from the API Client.
142142

143143
```php
144-
$client = $client->getClient();
144+
$webhooks = $client->getWebhooks();
145145
```
146146

147-
### <a name="create"></a>![Method: ](https://apidocs.io/img/method.png ".APIController.create") create
148-
149-
> This will create a webhook for the specified `events`
150-
> ### Parameters
151-
> **list of supported parameters in `template` according to the message type :**
152-
> you must escape the json for the template parameter. see example .
153-
> | Data | parameter name | DR| MO | MO MMS | Comment |
154-
> |:--|--|--|--|--|--|
155-
> | **service type** | $type| ``OK`` |`OK`| `OK`| |
156-
> | **Message ID** | $mtId, $messageId| `OK` |`OK`| `OK`| |
157-
> | **Delivery report ID** |$drId, $reportId | `OK` || | |
158-
> | **Reply ID**| $moId, $replyId| |`OK`| `OK`||
159-
> | **Account ID** | $accountId| `OK` |`OK`| `OK`||
160-
> | **Message Timestamp** | $submittedTimestamp| `OK` |`OK`| `OK`||
161-
> | **Provider Timestamp** | $receivedTimestamp| `OK` |`OK`| `OK`||
162-
> | **Message status** | $status| `OK` ||||
163-
> | **Status code** | $statusCode| `OK` ||||
164-
> | **External metadata** | $metadata.get('key')| `OK` |`OK`| `OK`||
165-
> | **Source address**| $sourceAddress| `OK` |`OK`| `OK`||
166-
> | **Destination address**| $destinationAddress| |`OK`| `OK`||
167-
> | **Message content**| $mtContent, $messageContent| `OK` |`OK`| `OK`||
168-
> | **Reply Content**| $moContent, $replyContent| |`OK`| `OK`||
169-
> | **Retry Count**| $retryCount| `OK` |`OK`| `OK`||
170-
> **list of allowed `events` :**
171-
> you can combine all the events whatever the message type.(at least one Event set otherwise the webhook won't be created)
172-
> + **events for SMS**
173-
> + `RECEIVED_SMS`
174-
> + `OPT_OUT_SMS`
175-
> + **events for MMS**
176-
> + `RECEIVED_MMS`
177-
> + **events for DR**
178-
> + `ENROUTE_DR`
179-
> + `EXPIRED_DR`
180-
> + `REJECTED_DR`
181-
> + `FAILED_DR`
182-
> + `DELIVERED_DR`
183-
> + `SUBMITTED_DR`
184-
> a **Response 400 is returned when** :
185-
> <ul>
186-
> <li>the `url` is not valid </li>
187-
> <li>the `events` is null/empty </li>
188-
> <li>the `encoding` is null </li>
189-
> <li>the `method` is null </li>
190-
> <li>the `headers` has a `ContentType` attribute </li>
191-
> </ul>
147+
### <a name="create_webhook"></a>![Method: ](https://apidocs.io/img/method.png ".WebhooksController.createWebhook") createWebhook
148+
149+
> Create a webhook for one or more of the specified events.
150+
> A webhook would typically have the following structure:
151+
> ```
152+
> {
153+
> "url": "http://webhook.com",
154+
> "method": "POST",
155+
> "encoding": "JSON",
156+
> "headers": {
157+
> "Account": "DeveloperPortal7000"
158+
> },
159+
> "events": [
160+
> "RECEIVED_SMS"
161+
> ],
162+
> "template": "{\"id\":\"$mtId\",\"status\":\"$statusCode\"}"
163+
> }
164+
> ```
165+
> A valid webhook must consist of the following properties:
166+
> - ```url``` The configured URL which will trigger the webhook when a selected event occurs.
167+
> - ```method``` The methods to map CRUD (create, retrieve, update, delete) operations to HTTP requests.
168+
> - ```encoding``` The format in which the payload will be returned. You can choose from ```JSON```, ```FORM_ENCODED``` or ```XML```. This will automatically add the Content-Type header for you so you don't have to add it again in the `headers` property.
169+
> - ```headers``` HTTP header fields which provide required information about the request or response, or about the object sent in the message body. This should not include the `Content-Type` header.
170+
> - ```events``` Event or events that will trigger the webhook. Atleast one event should be present.
171+
> - ```template``` The structure of the payload that will be returned.
172+
> #### Types of Events
173+
> You can select all of the events (listed below) or combine them in whatever way you like but atleast one event must be used. Otherwise, the webhook won't be created.
174+
> A webhook will be triggered when any one or more of the events occur:
175+
> + **SMS**
176+
> + `RECEIVED_SMS` Receive an SMS
177+
> + `OPT_OUT_SMS` Opt-out occured
178+
> + **MMS**
179+
> + `RECEIVED_MMS` Receive an MMS
180+
> + **DR (Delivery Reports)**
181+
> + `ENROUTE_DR` Message is enroute
182+
> + `EXPIRED_DR` Message has expired
183+
> + `REJECTED_DR` Message is rejected
184+
> + `FAILED_DR` Message has failed
185+
> + `DELIVERED_DR` Message is delivered
186+
> + `SUBMITTED_DR` Message is submitted
187+
> #### Template Parameters
188+
> You can choose what to include in the data that will be sent as the payload via the Webhook.
189+
> Keep in my mind, you must escape the JSON in the template value (see example above).
190+
> The table illustrates a list of all the parameters that can be included in the template and which event types it can be applied to.
191+
> | Data | Parameter Name | Example | Event Type |
192+
> |:--|--|--|--|--|
193+
> | **Service Type** | $type| `SMS` | `DR` `MO` `MO MMS` |
194+
> | **Message ID** | $mtId, $messageId| `877c19ef-fa2e-4cec-827a-e1df9b5509f7` | `DR` `MO` `MO MMS`|
195+
> | **Delivery Report ID** |$drId, $reportId| `01e1fa0a-6e27-4945-9cdb-18644b4de043` | `DR` |
196+
> | **Reply ID**| $moId, $replyId| `a175e797-2b54-468b-9850-41a3eab32f74` | `MO` `MO MMS` |
197+
> | **Account ID** | $accountId| `DeveloperPortal7000` | `DR` `MO` `MO MMS` |
198+
> | **Message Timestamp** | $submittedTimestamp| `2016年12月07日T08:43:00.850Z` | `DR` `MO` `MO MMS` |
199+
> | **Provider Timestamp** | $receivedTimestamp| `2016年12月07日T08:44:00.850Z` | `DR` `MO` `MO MMS` |
200+
> | **Message Status** | $status| `enroute` | `DR` |
201+
> | **Status Code** | $statusCode| `200` | `DR` |
202+
> | **External Metadata** | $metadata.get('key')| `name` | `DR` `MO` `MO MMS` |
203+
> | **Source Address**| $sourceAddress| `+61491570156` | `DR` `MO` `MO MMS` |
204+
> | **Destination Address**| $destinationAddress| `+61491593156` | `MO` `MO MMS` |
205+
> | **Message Content**| $mtContent, $messageContent| `Hi Derp` | `DR` `MO` `MO MMS` |
206+
> | **Reply Content**| $moContent, $replyContent| `Hello Derpina` | `MO` `MO MMS` |
207+
> | **Retry Count**| $retryCount| `1` | `DR` `MO` `MO MMS` |
208+
> *Note: A 400 response will be returned if the `url` is invalid, the `events`, `encoding` or `method` is null or the `headers` has a Content-Type attribute.*
192209
193210
194211
```php
195-
function create(
196-
$contentType,
197-
$body)
212+
function createWebhook($body)
198213
```
199214
200215
#### Parameters
201216

202217
| Parameter | Tags | Description |
203218
|-----------|------|-------------|
204-
| contentType | ``` Required ``` | TODO: Add a parameter description |
205219
| body | ``` Required ``` | TODO: Add a parameter description |
206220

207221

208222

209223
#### Example Usage
210224

211225
```php
212-
$contentType = 'Content-Type';
213-
$body = new CreateRequest();
226+
$body = new CreateWebhookRequest();
214227

215-
$result = $client->create($contentType, $body);
228+
$result = $webhooks->createWebhook($body);
216229

217230
```
218231

219232
#### Errors
220233

221234
| Error Code | Error Description |
222235
|------------|-------------------|
223-
| 400 | TODO: Add an error description |
224-
225-
226-
227-
### <a name="delete_delete_and_update_webhook"></a>![Method: ](https://apidocs.io/img/method.png ".APIController.deleteDeleteAndUpdateWebhook") deleteDeleteAndUpdateWebhook
228-
229-
> This will delete the webhook wuth the give id.
230-
> a **Response 404 is returned when** :
231-
> <ul>
232-
> <li>there is no webhook with this `webhookId` </li>
233-
> </ul>
236+
| 400 | Unexpected error in API call. See HTTP response body for details. |
237+
| 409 | Unexpected error in API call. See HTTP response body for details. |
238+
239+
240+
241+
### <a name="retrieve_webhook"></a>![Method: ](https://apidocs.io/img/method.png ".WebhooksController.retrieveWebhook") retrieveWebhook
242+
243+
> Retrieve all the webhooks created for the connected account.
244+
> A successful request to the retrieve webhook endpoint will return a response body as follows:
245+
> ```
246+
> {
247+
> "page": 0,
248+
> "pageSize": 100,
249+
> "pageData": [
250+
> {
251+
> "url": "https://webhook.com",
252+
> "method": "POST",
253+
> "id": "8805c9d8-bef7-41c7-906a-69ede93aa024",
254+
> "encoding": "JSON",
255+
> "events": [
256+
> "RECEIVED_SMS"
257+
> ],
258+
> "headers": {},
259+
> "template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}"
260+
> }
261+
> ]
262+
> }
263+
> ```
264+
> *Note: Response 400 is returned when the `page` query parameter is not valid or the `pageSize` query parameter is not valid.*
234265
235266
236267
```php
237-
function deleteDeleteAndUpdateWebhook($webhookId)
268+
function retrieveWebhook(
269+
$page = null,
270+
$pageSize = null)
238271
```
239272
240273
#### Parameters
241274

242275
| Parameter | Tags | Description |
243276
|-----------|------|-------------|
244-
| webhookId | ``` Required ``` | TODO: Add a parameter description |
277+
| page | ``` Optional ``` | TODO: Add a parameter description |
278+
| pageSize | ``` Optional ``` | TODO: Add a parameter description |
245279

246280

247281

248282
#### Example Usage
249283

250284
```php
251-
$webhookId = a7f11bb0-f299-4861-a5ca-9b29d04bc5ad;
285+
$page = 79;
286+
$pageSize = 79;
252287

253-
$client->deleteDeleteAndUpdateWebhook($webhookId);
288+
$result = $webhooks->retrieveWebhook($page, $pageSize);
254289

255290
```
256291

257292
#### Errors
258293

259294
| Error Code | Error Description |
260295
|------------|-------------------|
261-
| 404 | TODO: Add an error description |
296+
| 400 | Unexpected error in API call. See HTTP response body for details. |
262297

263298

264299

265-
### <a name="retrieve"></a>![Method: ](https://apidocs.io/img/method.png ".APIController.retrieve") retrieve
300+
### <a name="delete_webhook"></a>![Method: ](https://apidocs.io/img/method.png ".WebhooksController.deleteWebhook") deleteWebhook
266301

267-
> This will retrieve all webhooks for the account we're connected with.
268-
> a **Response 400 is returned when** :
269-
> <ul>
270-
> <li>the `page` query parameter is not valid </li>
271-
> <li>the `pageSize` query parameter is not valid </li>
272-
> </ul>
302+
> Delete a webhook that was previously created for the connected account.
303+
> A webhook can be cancelled by appending the UUID of the webhook to the endpoint and submitting a DELETE request to the /webhooks/messages endpoint.
304+
> *Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.*
273305
274306

275307
```php
276-
function retrieve(
277-
$page = null,
278-
$pageSize = null)
308+
function deleteWebhook($webhookId)
279309
```
280310

281311
#### Parameters
282312

283313
| Parameter | Tags | Description |
284314
|-----------|------|-------------|
285-
| page | ``` Optional ``` | TODO: Add a parameter description |
286-
| pageSize | ``` Optional ``` | TODO: Add a parameter description |
315+
| webhookId | ``` Required ``` | TODO: Add a parameter description |
287316

288317

289318

290319
#### Example Usage
291320

292321
```php
293-
$page = '1';
294-
$pageSize = '10';
322+
$webhookId = a7f11bb0-f299-4861-a5ca-9b29d04bc5ad;
295323

296-
$result = $client->retrieve($page, $pageSize);
324+
$webhooks->deleteWebhook($webhookId);
297325

298326
```
299327

300328
#### Errors
301329

302330
| Error Code | Error Description |
303331
|------------|-------------------|
304-
| 400 | TODO: Add an error description |
332+
| 404 | TODO: Add an error description |
305333

306334

307335

308-
### <a name="update"></a>![Method: ](https://apidocs.io/img/method.png ".APIController.update") update
336+
### <a name="update_webhook"></a>![Method: ](https://apidocs.io/img/method.png ".WebhooksController.updateWebhook") updateWebhook
309337

310-
> This will update a webhook and returned the updated Webhook.
311-
> you can update all the attributes individually or together.
312-
> PS : the new value will override the previous one.
313-
> ### Parameters
314-
> + same parameters rules as create webhook apply
315-
> a **Response 404 is returned when** :
316-
> <ul>
317-
> <li>there is no webhook with this `webhookId` </li>
318-
> </ul>
319-
> a **Response 400 is returned when** :
320-
> <ul>
321-
> <li>all attributes are null </li>
322-
> <li>events array is empty </li>
323-
> <li>content-Type is set in the headers instead of using the `encoding` attribute </li>
324-
> </ul>
338+
> Update a webhook. You can update individual attributes or all of them by submitting a PATCH request to the /webhooks/messages endpoint (the same endpoint used above to delete a webhook)
339+
> A successful request to the retrieve webhook endpoint will return a response body as follows:
340+
> ```
341+
> {
342+
> "url": "https://webhook.com",
343+
> "method": "POST",
344+
> "id": "04442623-0961-464e-9cbc-ec50804e0413",
345+
> "encoding": "JSON",
346+
> "events": [
347+
> "RECEIVED_SMS"
348+
> ],
349+
> "headers": {},
350+
> "template": "{\"id\":\"$mtId\", \"status\":\"$statusCode\"}"
351+
> }
352+
> ```
353+
> *Note: Only pre-created webhooks can be deleted. If an invalid or non existent webhook ID parameter is specified in the request, then a HTTP 404 Not Found response will be returned.*
325354
326355
327356
```php
328-
function update(
357+
function updateWebhook(
329358
$webhookId,
330-
$contentType,
331359
$body)
332360
```
333361
@@ -336,26 +364,26 @@ function update(
336364
| Parameter | Tags | Description |
337365
|-----------|------|-------------|
338366
| webhookId | ``` Required ``` | TODO: Add a parameter description |
339-
| contentType | ``` Required ``` | TODO: Add a parameter description |
340367
| body | ``` Required ``` | TODO: Add a parameter description |
341368

342369

343370

344371
#### Example Usage
345372

346373
```php
347-
$webhookId = uniqid();
348-
$contentType = 'Content-Type';
349-
$body = new UpdateRequest();
374+
$webhookId = a7f11bb0-f299-4861-a5ca-9b29d04bc5ad;
375+
$bodyValue = " { \"url\": \"https://myurl.com\", \"method\": \"POST\", \"encoding\": \"FORM_ENCODED\", \"events\": [ \"ENROUTE_DR\" ], \"template\": \"{\\\"id\\\":\\\"$mtId\\\", \\\"status\\\":\\\"$statusCode\\\"}\" }";
376+
$body = APIHelper::deserialize($bodyValue);
350377

351-
$client->update($webhookId, $contentType, $body);
378+
$result = $webhooks->updateWebhook($webhookId, $body);
352379

353380
```
354381

355382
#### Errors
356383

357384
| Error Code | Error Description |
358385
|------------|-------------------|
386+
| 400 | Unexpected error in API call. See HTTP response body for details. |
359387
| 404 | TODO: Add an error description |
360388

361389

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /