diff --git a/README.md b/README.md index ece123b..d7a8746 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,15 @@ -# v2-messaging -Beta docs for Bandwidth v2 Messaging API +# Bandwidth v2 Messaging Preview + +## Quick Start +1. [Setup Application](application.md) +2. [Send Text Message](methods/createSingle.md) +3. Receive [Sent Event](events/outSent.md) then [Delivered Event](events/msgDelivered.md) + +### About +In the V2 version of the Messaging API, messages are sent asynchronously. Message validation will happen after the server returns `202`. API clients should listen for HTTP callback events if they need to track message state after the inital `POST` request. + +The request body for HTTP callbacks regarding message state changes will follow the same format as the response body for a `POST` or `GET` on a message. + +Callbacks will be sent to the Callback URL for the Application associated with the `from` number on the outgoing message. + +If there is a need to identify individual messages, or correlate them with an ID in your application, the `tag` field can be set to any string. The custom `tag` will be included in all callbacks for this message. diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..c1ec067 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,22 @@ +# Summary + +## Overview +* [Get Started](README.md) +* [Setup Application](application.md) + +## Send Messages +* [Single Message](methods/createSingle.md) +* [Group Message](methods/createGroup.md) + +## Message Events +* [Standard Event](events/receiveSingle.md) +* [Incoming Group Message](events/incomingGroup.md) +* [Message Sent](events/outSent.md) +* [Message Delivered](events/msgDelivered.md) +* [Group Message Rejected](events/groupReject.md) + +## Api Error Response +* [400 - Bad Request](errors/badRequest.md) +* [401 - Unauthorized](errors/unauth.md) +* [403 - Forbidden](errors/forbidden.md) +* [429 - Too Many Requests](errors/tooManyReq.md) \ No newline at end of file diff --git a/application.md b/application.md new file mode 100644 index 0000000..b91ee3f --- /dev/null +++ b/application.md @@ -0,0 +1,43 @@ +# Setup The Bandwidth Application + +In order to recieve delivery notifications and message state, each phone number needs to be assigned to a [Bandwidth Application](http://dev.bandwidth.com/ap-docs/methods/applications/applications.html). + +> Follow the [tutorial](http://dev.bandwidth.com/howto/incomingCallandMessaging.html) on how to create an application and order phone numbers + +## Validate callback Url +Make sure that the callback url is configured correctly for your application. + +### Using the UI +Log into the Bandwidth service and navigate to the `My Apps` Tab. + +Either find or create the application and validate the `Messaging Callback` value is configured correctly. + +![Visual](images/visual_app_url.png) + +### Using the API + +Check your application status by making a GET request to your application id. + +GET`https://api.catapult.inetwork.com/v1/users/{userId}/applications/{applicationId}` + +Incoming messages and outbound message states updates are sent to the url specified as the `incomingMessageUrl` + +```bash +curl -v -X GET https://api.catapult.inetwork.com/v1/users/{user-id}/applications/{applicationId} + -u {token}:{secret} \ + -H "Content-type: application/json" \ + ``` + +```http +Status: 200 OK +Content-Type: application/json + + { + "id": "{applicationId}", + "name": "MyFirstApp", + "incomingCallUrl": "http://example.com/calls.php", + "incomingMessageUrl": "http://example.com/messages.php", + "autoAnswer": true, + "messageApiVersion": "V2" +} +``` diff --git a/book.json b/book.json new file mode 100644 index 0000000..6205691 --- /dev/null +++ b/book.json @@ -0,0 +1,63 @@ +{ + "plugins": [ + "theme-bandwidth", + "header", + "sharing", + "custom-favicon", + "toggle-chapters", + "customJquery@git+https://github.com/dtolb/gitbook-plugin-customJquery.git", + "-fontsettings", + "bandwidth-fonts", + "-highlight", + "bandwidth-highlight" + ], + "pluginsConfig": { + "theme-bandwidth": { + "languages": [ + { + "lang": "js", + "name": "Js", + "default": true + }, + { + "lang": "csharp", + "name": "C#" + }, + { + "lang": "ruby", + "name": "ruby" + + }, + { + "lang": "shell", + "name": "cURL" + }, + { + "lang": "bash", + "name": "cURL" + } + ] + }, + "customJquery": { + "js": "js/custom.js" + }, + "layout": { + "headerPath" : "layouts/header.html" + }, + "favicon": "images/favicon.ico", + "sharing": { + "facebook": false, + "twitter": false, + "google": false, + "weibo": false, + "instapaper": false, + "vk": false, + "all": [] + }, + "fontsettings": { + "theme": "white", + "family": "sans", + "size": 2 + } + } +} \ No newline at end of file diff --git a/errors/badRequest.md b/errors/badRequest.md new file mode 100644 index 0000000..228e720 --- /dev/null +++ b/errors/badRequest.md @@ -0,0 +1,43 @@ +{% method %} +# Bad Request Error - 400 + +### Parameters +| Parameter | Type | Description | +|:------------------------|:---------|:-------------------------------------------------| +| type | `string` | The Type of error. | +| description | `string` | A detailed description of why the error occurred | +| fieldErrors | `array` | List of errors in fields | +| fieldErrors.fieldName | `string` | Name of field with error | +| fieldErrors.description | `string` | Description of the error | + +{% common %} + +### Bad Request +{% sample lang='http' %} + + +```http +Status: 400 Bad Request +Content-Type: application/json; charset=utf-8 + +{ + "type": "request-validation", + "description": "Your request could not be accepted", + "fieldErrors": [ + { + "fieldName": "from", + "description": "'from' must contain exactly one telephone number" + }, + { + "fieldName": "text", + "description": "'text' is required unless media is included" + }, + { + "fieldName": "to", + "description": "'to' must contain at least one telephone number" + } + ] +} +``` + +{% endmethod %} \ No newline at end of file diff --git a/errors/forbidden.md b/errors/forbidden.md new file mode 100644 index 0000000..7c31f03 --- /dev/null +++ b/errors/forbidden.md @@ -0,0 +1,32 @@ +{% method %} +# Forbidden Error - 403 + +### Parameters +| Parameter | Type | Description | +|:----------|:---------|:------------------------| +| timestamp | `string` | The time of the error | +| status | `int` | The http status code | +| error | `string` | Error Type | +| message | `string` | Error Message | +| path | `string` | Relative path for error | + +{% common %} + +### Forbidden +{% sample lang='http' %} + + +```http +Status: 403 Forbidden +Content-Type: application/json; charset=utf-8 + +{ + "timestamp": "2017-01-11T18:25:27.047+0000", + "status": 403, + "error": "Forbidden", + "message": "Access is denied", + "path": "/v2/users/u-abc123/messages" +} +``` + +{% endmethod %} \ No newline at end of file diff --git a/errors/tooManyReq.md b/errors/tooManyReq.md new file mode 100644 index 0000000..01f71e3 --- /dev/null +++ b/errors/tooManyReq.md @@ -0,0 +1,28 @@ +{% method %} +# Too Many Requests Error - 429 + +### Parameters +| Parameter | Type | Description | +|:------------------------|:---------|:-------------------------------------------------| +| type | `string` | The Type of error. | +| description | `string` | A detailed description of why the error occurred | +| fieldErrors | `array` | List of errors in fields | +| fieldErrors.fieldName | `string` | Name of field with error | +| fieldErrors.description | `string` | Description of the error | + +{% common %} + +### Too Many Requests +{% sample lang='http' %} + +```http +Status: 429 Too Many Requests +Content-Type: application/json; charset=utf-8 + +{ + "type": "rate-limit-exceeded", + "description": "You can send 1 messages per 1 seconds, calculated as the average over 10 seconds. Your rate is: 1.1" +} +``` + +{% endmethod %} \ No newline at end of file diff --git a/errors/unauth.md b/errors/unauth.md new file mode 100644 index 0000000..fc1bc0b --- /dev/null +++ b/errors/unauth.md @@ -0,0 +1,32 @@ +{% method %} +# Unauthorized Error - 401 + +### Parameters +| Parameter | Type | Description | +|:----------|:---------|:------------------------| +| timestamp | `string` | The time of the error | +| status | `int` | The http status code | +| error | `string` | Error Type | +| message | `string` | Error Message | +| path | `string` | Relative path for error | + +{% common %} + +### Unauthorized +{% sample lang='http' %} + + +```http +Status: 401 Unauthorized +Content-Type: application/json; charset=utf-8 + +{ + "timestamp": "2017-01-11T18:15:23.348+0000", + "status": 401, + "error": "Unauthorized", + "message": "Unauthorized", + "path": "/v2/users/u-abc123/messages" +} +``` + +{% endmethod %} \ No newline at end of file diff --git a/events/groupReject.md b/events/groupReject.md new file mode 100644 index 0000000..9228b78 --- /dev/null +++ b/events/groupReject.md @@ -0,0 +1,58 @@ +{% method %} +# Group Message Rejected Event +In order to receive text messages events, you need to ensure you have [setup your application](../application.md) to send callbacks to your server's URL. + +### Parameters +| Parameter | Type | Description | +|:------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `string` | The Event type | +| time | `array` | The time of the event described in the receipt | +| description | `string` | A detailed description of the event described by the receipt | +| to | `array` | The destination number for an outbound group message receipt | +| message | `string` | Any string, it will be included in the callback events of the message. | +| message.id | `string` | The unique ID of this message | +| message.owner | `string` | The phone number this particular message is associated with.
For an outbound message, this is always the `from` number.
For an inbound message, this will be (one of) the `to` number(s).
For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. | +| message.time | `string` | The time stamp of when message was created | +| message.direction | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number | +| message.to | `array` | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array. | +| message.from | `string` | The phone number the message was sent from | +| message.text | `string` | The text content of the message | +| message.media | `array` | A list of URLs to include as media attachments as part of the message | +| message.tag | `string` | An custom String that you can use to track this particular message | + +{% common %} +### Group Message Rejected + +{% sample lang='http' %} + +```http +POST /your_url HTTP/1.1 +Content-Type: application/json; charset=utf-8 +User-Agent: BandwidthAPI/v2 + +[ + { + "type": "message-rejected-forbidden-country", + "time": "2016-09-14T18:20:16Z", + "description": "Not allowed to send to the country of the destination number", + "to": "+12345678903", + "message": { + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + "+12345678903" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "owner": "+12345678901", + "direction": "out" + } + } +] +``` + +{% endmethod %} \ No newline at end of file diff --git a/events/incomingGroup.md b/events/incomingGroup.md new file mode 100644 index 0000000..e3f88ab --- /dev/null +++ b/events/incomingGroup.md @@ -0,0 +1,58 @@ +{% method %} +# Incoming Group Message Event +In order to receive text messages events, you need to ensure you have [setup your application](../application.md) to send callbacks to your server's URL. + +### Parameters +| Parameter | Type | Description | +|:------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `string` | The Event type | +| time | `array` | The time of the event described in the receipt | +| description | `string` | A detailed description of the event described by the receipt | +| to | `array` | The destination number for an outbound group message receipt | +| message | `string` | Any string, it will be included in the callback events of the message. | +| message.id | `string` | The unique ID of this message | +| message.owner | `string` | The phone number this particular message is associated with.
For an outbound message, this is always the `from` number.
For an inbound message, this will be (one of) the `to` number(s).
For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. | +| message.time | `string` | The time stamp of when message was created | +| message.direction | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number | +| message.to | `array` | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array. | +| message.from | `string` | The phone number the message was sent from | +| message.text | `string` | The text content of the message | +| message.media | `array` | A list of URLs to include as media attachments as part of the message | +| message.tag | `string` | An custom String that you can use to track this particular message | + +{% common %} +### Incoming group message + +{% sample lang='http' %} + +```http +POST /your_url HTTP/1.1 +Content-Type: application/json; charset=utf-8 +User-Agent: BandwidthAPI/v2 + +[ + { + "type": "message-received", + "time": "2016-09-14T18:20:16Z", + "description": "Incoming message received", + "to": "+12345678902", + "message": { + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + "+12345678903" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "owner": "+12345678902", + "direction": "in" + } + } +] +``` + +{% endmethod %} diff --git a/events/msgDelivered.md b/events/msgDelivered.md new file mode 100644 index 0000000..c9b653d --- /dev/null +++ b/events/msgDelivered.md @@ -0,0 +1,58 @@ +{% method %} +# Message Delivered to Carrier Event +In order to receive text messages events, you need to ensure you have [setup your application](../application.md) to send callbacks to your server's URL. + + + +### Parameters +| Parameter | Type | Description | +|:------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `string` | The Event type | +| time | `array` | The time of the event described in the receipt | +| description | `string` | A detailed description of the event described by the receipt | +| to | `array` | The destination number for an outbound group message receipt | +| message | `string` | Any string, it will be included in the callback events of the message. | +| message.id | `string` | The unique ID of this message | +| message.owner | `string` | The phone number this particular message is associated with.
For an outbound message, this is always the `from` number.
For an inbound message, this will be (one of) the `to` number(s).
For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. | +| message.time | `string` | The time stamp of when message was created | +| message.direction | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number | +| message.to | `array` | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array. | +| message.from | `string` | The phone number the message was sent from | +| message.text | `string` | The text content of the message | +| message.media | `array` | A list of URLs to include as media attachments as part of the message | +| message.tag | `string` | An custom String that you can use to track this particular message | + +{% common %} +### Message delivered to carrier + +{% sample lang='http' %} + +```http +POST /your_url HTTP/1.1 +Content-Type: application/json; charset=utf-8 +User-Agent: BandwidthAPI/v2 + +[ + { + "type": "message-delivered", + "time": "2016-09-14T18:20:16Z", + "description": "Message delivered to carrier", + "message": { + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + "+12345678903" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "owner": "+12345678902", + "direction": "in" + } + } +] +``` + +{% endmethod %} \ No newline at end of file diff --git a/events/outSent.md b/events/outSent.md new file mode 100644 index 0000000..223454b --- /dev/null +++ b/events/outSent.md @@ -0,0 +1,57 @@ +{% method %} +# Outgoing Message Sent Event +In order to receive text messages events, you need to ensure you have [setup your application](../application.md) to send callbacks to your server's URL. + +### Parameters +| Parameter | Type | Description | +|:------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `string` | The Event type | +| time | `array` | The time of the event described in the receipt | +| description | `string` | A detailed description of the event described by the receipt | +| to | `array` | The destination number for an outbound group message receipt | +| message | `string` | Any string, it will be included in the callback events of the message. | +| message.id | `string` | The unique ID of this message | +| message.owner | `string` | The phone number this particular message is associated with.
For an outbound message, this is always the `from` number.
For an inbound message, this will be (one of) the `to` number(s).
For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. | +| message.time | `string` | The time stamp of when message was created | +| message.direction | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number | +| message.to | `array` | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array. | +| message.from | `string` | The phone number the message was sent from | +| message.text | `string` | The text content of the message | +| message.media | `array` | A list of URLs to include as media attachments as part of the message | +| message.tag | `string` | An custom String that you can use to track this particular message | + +{% common %} +### Outgoing message sent notification + +{% sample lang='http' %} + +```http +POST /your_url HTTP/1.1 +Content-Type: application/json; charset=utf-8 +User-Agent: BandwidthAPI/v2 + +[ + { + "type": "message-sent", + "time": "2016-09-14T18:20:16Z", + "description": "Outgoing message sent", + "message": { + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + "+12345678903" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "owner": "+12345678902", + "direction": "in" + } + } +] +``` + +{% endmethod %} \ No newline at end of file diff --git a/events/receiveSingle.md b/events/receiveSingle.md new file mode 100644 index 0000000..ae81dfa --- /dev/null +++ b/events/receiveSingle.md @@ -0,0 +1,56 @@ +{% method %} +# Incoming Text Message Event +In order to receive text messages events, you need to ensure you have [setup your application](../application.md) to send callbacks to your server's URL. + +### Parameters +| Parameter | Type | Description | +|:------------------|:---------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| type | `string` | The Event type | +| time | `array` | The time of the event described in the receipt | +| description | `string` | A detailed description of the event described by the receipt | +| to | `array` | The destination number for an outbound group message receipt | +| message | `string` | Any string, it will be included in the callback events of the message. | +| message.id | `string` | The unique ID of this message | +| message.owner | `string` | The phone number this particular message is associated with.
For an outbound message, this is always the `from` number.
For an inbound message, this will be (one of) the `to` number(s).
For instance, if this is an inbound group message, the `owner` field will be set to the `to` number that this particular copy of the group message belongs to. | +| message.time | `string` | The time stamp of when message was created | +| message.direction | `string` | Whether the message was sent from Bandwidth, or received by a Bandwidth number | +| message.to | `array` | The phone number (or numbers) the message the message is sent to. On a POST, this can be a String, or an array of one or more numbers. In all other places, this will be an array. | +| message.from | `string` | The phone number the message was sent from | +| message.text | `string` | The text content of the message | +| message.media | `array` | A list of URLs to include as media attachments as part of the message | +| message.tag | `string` | An custom String that you can use to track this particular message | + +{% common %} +### Incoming text message + +{% sample lang='http' %} + +```http +POST /your_url HTTP/1.1 +Content-Type: application/json; charset=utf-8 +User-Agent: BandwidthAPI/v2 + +[ + { + "type": "message-received", + "time": "2016-09-14T18:20:16Z", + "description": "Incoming message received", + "message": { + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "owner": "+12345678902", + "direction": "in" + } + } +] +``` + +{% endmethod %} diff --git a/images/favicon.ico b/images/favicon.ico new file mode 100644 index 0000000..02c9994 Binary files /dev/null and b/images/favicon.ico differ diff --git a/images/headerLogo.png b/images/headerLogo.png new file mode 100644 index 0000000..7956222 Binary files /dev/null and b/images/headerLogo.png differ diff --git a/images/logo.png b/images/logo.png new file mode 100644 index 0000000..01c8d79 Binary files /dev/null and b/images/logo.png differ diff --git a/images/mobileLogo.png b/images/mobileLogo.png new file mode 100644 index 0000000..29f398c Binary files /dev/null and b/images/mobileLogo.png differ diff --git a/images/navbar.png b/images/navbar.png new file mode 100644 index 0000000..df38e90 Binary files /dev/null and b/images/navbar.png differ diff --git a/images/visual_app_url.png b/images/visual_app_url.png new file mode 100644 index 0000000..0965f9a9 Binary files /dev/null and b/images/visual_app_url.png differ diff --git a/js/custom.js b/js/custom.js new file mode 100644 index 0000000..9aacfc3 --- /dev/null +++ b/js/custom.js @@ -0,0 +1,29 @@ +module.exports = function ($) { + $('li.chapter').each(function (i, elem) { + var li = $(elem); + if (li.text().indexOf('GET') > 0) { + var newTxt = li.children().first().html().replace("GET", "GET "); + li.children().first().html(newTxt); + } + else if (li.text().indexOf('POST') > 0) { + var newTxt = li.children().first().html().replace("POST", "POST"); + li.children().first().html(newTxt); + } + else if (li.text().indexOf('DELETE') > 0) { + var newTxt = li.children().first().html().replace("DELETE", "DEL "); + li.children().first().html(newTxt); + } + else if (li.text().indexOf('PUT') > 0) { + var newTxt = li.children().first().html().replace("PUT", "PUT "); + li.children().first().html(newTxt); + } + }); + var title = $('title').text(); + + if(title.indexOf(' · GitBook') > 0) { + var newTitle = title.replace(' · GitBook', ''); + $('title').text(newTitle); + } + + return $.html(); +} diff --git a/layouts/footer.html b/layouts/footer.html new file mode 100644 index 0000000..06c0ac3 --- /dev/null +++ b/layouts/footer.html @@ -0,0 +1,10 @@ + + + + +Untitled Document + + + + + diff --git a/layouts/header.html b/layouts/header.html new file mode 100644 index 0000000..baf031e --- /dev/null +++ b/layouts/header.html @@ -0,0 +1,10 @@ + +
+ +

v2 Messaging Preview

+ +
diff --git a/methods/createGroup.md b/methods/createGroup.md new file mode 100644 index 0000000..a41b221 --- /dev/null +++ b/methods/createGroup.md @@ -0,0 +1,228 @@ +{% method %} + +## Send or Create a Group Message + +Send at least one text message or picture message + +### Request URL + +POST`https://api.catapult.inetwork.com/v2/users/{userId}/messages` + +### Supported Parameters +| Parameter | Type | Description | Mandatory | +|:----------|:---------|:---------------------------------------------------------------------------------------------------------|:----------| +| from | `string` | One of your telephone numbers the message should come from (must be in E.164 format, like +19195551212). | Yes | +| to | `array` | The phone number the message should be sent to (must be in E.164 format, like +19195551212). | Yes | +| text | `string` | The contents of the text message (must be 2048 characters or less). | Yes | +| media | `array` | A list of URLs to include as media attachments as part of the message. | No | +| tag | `string` | Any string, it will be included in the callback events of the message. | No | + +{% common %} +### Example: Send or create a group message + +{% sample lang='http' %} + +```http +POST https://api.catapult.inetwork.com/v2/users/{userId}/messages HTTP/1.1 +Content-Type: application/json; charset=utf-8 +Authorization: Basic dc123 + +{ + "to" :[ + "+12345678902", + "+12345678903" + ], + "from":"+12345678901", + "text":"Hey, check this out!", + "tag" :"test message" +} + +``` + +{% sample lang='bash' %} + +```bash +curl --request POST \ + --url https://api.catapult.inetwork.com/v2/users/{{userId}}/messages \ + --user {token}:{secret} \ + --header 'content-type: application/json' \ + --data ' + { + "to" :[ + "+12345678902", + "+12345678903" + ], + "from":"+12345678901", + "text":"Hey, check this out!", + "tag" :"test message" + } + ' +``` + +{% sample lang='js' %} + +```js +var request = require("request"); + +var options = { method: 'POST', + url: 'https://api.catapult.inetwork.com/v2/users/{{userId}}/messages', + headers: { 'content-type': 'application/json' }, + auth: { + user: '{{token}}', + pass: '{{secret}}' + }, + body: + { to: [ '+12345678902', '+12345678903'], + from: '+12345678901', + text: 'Hey, check this out!', + tag: 'test message' }, + json: true }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); + // { id: '1486146872688aih2vr2rpxi7n2ll', + // owner: '+12345678901', + // time: '2017-02-03T18:34:32.688Z', + // direction: 'out', + // to: [ '+12345678902', '+12345678903' ], + // from: '+12345678901', + // text: 'Hey, check this out!', + // tag: 'test message' } +}); +``` + +{% common %} + +> The above command returns a JSON Response structured like this: + +```http +Status: 202 Accepted +Content-Type: application/json; charset=utf-8 + +{ + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + "+12345678903" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "tag": "test message", + "owner": "+12345678901", + "direction": "out" +} +``` + +### Example: Send Picture to a group message thread +{% sample lang='http' %} + +```http +POST https://api.catapult.inetwork.com/v2/users/{userId}/messages HTTP/1.1 +Content-Type: application/json; charset=utf-8 +Authorization: Basic dc123 + +{ + "to" :[ + "+12345678902", + "+12345678903" + ], + "from":"+12345678901", + "text":"Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "tag" :"test message" +} + +``` + +{% sample lang='bash' %} + +```bash +curl --request POST \ + --url https://api.catapult.inetwork.com/v2/users/{{userId}}/messages \ + --user {token}:{secret} \ + --header 'content-type: application/json' \ + --data ' + { + "to" :[ + "+12345678902", + "+12345678903" + ], + "from":"+12345678901", + "text":"Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "tag" :"test message" + } + ' +``` + +{% sample lang='js' %} + +```js +var request = require("request"); + +var options = { method: 'POST', + url: 'https://api.catapult.inetwork.com/v2/users/{{userId}}/messages', + headers: { 'content-type': 'application/json' }, + auth: { + user: '{{token}}', + pass: '{{secret}}' + }, + body: + { to: [ '+12345678902', '+12345678903'], + from: '+12345678901', + text: 'Hey, check this out!', + media: [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + tag: 'test message' }, + json: true }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); + // { id: '1486146872688aih2vr2rpxi7n2ll', + // owner: '+12345678901', + // time: '2017-02-03T18:34:32.688Z', + // direction: 'out', + // to: [ '+12345678902', '+12345678903'], + // from: '+12345678901', + // text: 'Hey, check this out!', + // media: ['https://s3.amazonaws.com/bw-v2-api/demo.jpg'], + // tag: 'test message' } +}); +``` + +{% common %} + +> The above command returns a JSON Response structured like this: + +```http +Status: 202 Accepted +Content-Type: application/json; charset=utf-8 + +{ + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + "+12345678903" + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "tag": "test message", + "owner": "+12345678901", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "direction": "out" +} +``` +{% endmethod %} \ No newline at end of file diff --git a/methods/createSingle.md b/methods/createSingle.md new file mode 100644 index 0000000..abcd8f0 --- /dev/null +++ b/methods/createSingle.md @@ -0,0 +1,325 @@ +{% method %} + +## Send SMS or MMS Text Message to Single Phone Number + +Send at least one text message or picture message. + +### Request URL + +POST`https://api.catapult.inetwork.com/v2/users/{userId}/messages` + +### Supported Parameters +| Parameter | Type | Description | Mandatory | +|:----------|:---------|:---------------------------------------------------------------------------------------------------------|:----------| +| from | `string` | One of your telephone numbers the message should come from (must be in E.164 format, like +19195551212). | Yes | +| to | `array` | The phone number the message should be sent to (must be in E.164 format, like +19195551212). | Yes | +| text | `string` | The contents of the text message (must be 2048 characters or less). | Yes | +| media | `array` | A list of URLs to include as media attachments as part of the message. | No | +| tag | `string` | Any string, it will be included in the callback events of the message. | No | + +{% common %} +### Example: Send A Single Text Message + +{% sample lang='http' %} + +```http +POST https://api.catapult.inetwork.com/v2/users/{userId}/messages HTTP/1.1 +Content-Type: application/json; charset=utf-8 +Authorization: Basic dc123 + +{ + "to" :["+12345678902"], + "from":"+12345678901", + "text":"Hey, check this out!", + "tag" :"test message" +} + +``` + +{% sample lang='bash' %} + +```bash +curl --request POST \ + --url https://api.catapult.inetwork.com/v2/users/{{userId}}/messages \ + --user {token}:{secret} \ + --header 'content-type: application/json' \ + --data ' + { + "to" :["+12345678902"], + "from":"+12345678901", + "text":"Hey, check this out!", + "tag" :"test message" + } + ' +``` + +{% sample lang='js' %} + +```js +var request = require("request"); + +var options = { method: 'POST', + url: 'https://api.catapult.inetwork.com/v2/users/{{userId}}/messages', + headers: { 'content-type': 'application/json' }, + auth: { + user: '{{token}}', + pass: '{{secret}}' + }, + body: + { to: [ '+12345678902'], + from: '+12345678901', + text: 'Hey, check this out!', + tag: 'test message' }, + json: true }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); + // { id: '1486146872688aih2vr2rpxi7n2ll', + // owner: '+12345678901', + // time: '2017-02-03T18:34:32.688Z', + // direction: 'out', + // to: [ '+12345678902' ], + // from: '+12345678901', + // text: 'Hey, check this out!', + // tag: 'test message' } +}); +``` + +{% common %} + +> The above command returns a JSON Response structured like this: + +```http +Status: 202 Accepted +Content-Type: application/json; charset=utf-8 + +{ + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "tag": "test message", + "owner": "+12345678901", + "direction": "out" +} +``` + +### Example: Send Picture Message +{% sample lang='http' %} + +```http +POST https://api.catapult.inetwork.com/v2/users/{userId}/messages HTTP/1.1 +Content-Type: application/json; charset=utf-8 +Authorization: Basic dc123 + +{ + "to" :["+12345678902"], + "from":"+12345678901", + "text":"Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "tag" :"test message" +} + +``` + +{% sample lang='bash' %} + +```bash +curl --request POST \ + --url https://api.catapult.inetwork.com/v2/users/{{userId}}/messages \ + --user {token}:{secret} \ + --header 'content-type: application/json' \ + --data ' + { + "to" :["+12345678902"], + "from":"+12345678901", + "text":"Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "tag" :"test message" + } + ' +``` + +{% sample lang='js' %} + +```js +var request = require("request"); + +var options = { method: 'POST', + url: 'https://api.catapult.inetwork.com/v2/users/{{userId}}/messages', + headers: { 'content-type': 'application/json' }, + auth: { + user: '{{token}}', + pass: '{{secret}}' + }, + body: + { to: [ '+12345678902'], + from: '+12345678901', + text: 'Hey, check this out!', + media: [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + tag: 'test message' }, + json: true }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); + // { id: '1486146872688aih2vr2rpxi7n2ll', + // owner: '+12345678901', + // time: '2017-02-03T18:34:32.688Z', + // direction: 'out', + // to: [ '+12345678902' ], + // from: '+12345678901', + // text: 'Hey, check this out!', + // media: ['https://s3.amazonaws.com/bw-v2-api/demo.jpg'], + // tag: 'test message' } +}); +``` + +{% common %} + +> The above command returns a JSON Response structured like this: + +```http +Status: 202 Accepted +Content-Type: application/json; charset=utf-8 + +{ + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "tag": "test message", + "owner": "+12345678901", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg" + ], + "direction": "out" +} +``` + +### Example: Send Multiple Pictures in a Message +{% sample lang='http' %} + +```http +POST https://api.catapult.inetwork.com/v2/users/{userId}/messages HTTP/1.1 +Content-Type: application/json; charset=utf-8 +Authorization: Basic dc123 + +{ + "to" :["+12345678902"], + "from":"+12345678901", + "text":"Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg", + "https://s3.amazonaws.com/bw-v2-api/demo2.jpg" + ], + "tag" :"test message" +} + +``` + +{% sample lang='bash' %} + +```bash +curl --request POST \ + --url https://api.catapult.inetwork.com/v2/users/{{userId}}/messages \ + --user {token}:{secret} \ + --header 'content-type: application/json' \ + --data ' + { + "to" :["+12345678902"], + "from":"+12345678901", + "text":"Hey, check this out!", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg", + "https://s3.amazonaws.com/bw-v2-api/demo2.jpg" + ], + "tag" :"test message" + } + ' +``` + +{% sample lang='js' %} + +```js +var request = require("request"); + +var options = { method: 'POST', + url: 'https://api.catapult.inetwork.com/v2/users/{{userId}}/messages', + headers: { 'content-type': 'application/json' }, + auth: { + user: '{{token}}', + pass: '{{secret}}' + }, + body: + { to: [ '+12345678902'], + from: '+12345678901', + text: 'Hey, check this out!', + media: [ + 'https://s3.amazonaws.com/bw-v2-api/demo.jpg', + 'https://s3.amazonaws.com/bw-v2-api/demo2.jpg' + ], + tag: 'test message' }, + json: true }; + +request(options, function (error, response, body) { + if (error) throw new Error(error); + + console.log(body); + // { id: '1486146872688aih2vr2rpxi7n2ll', + // owner: '+12345678901', + // time: '2017-02-03T18:34:32.688Z', + // direction: 'out', + // to: [ '+12345678902' ], + // from: '+12345678901', + // text: 'Hey, check this out!', + // media: [ + // 'https://s3.amazonaws.com/bw-v2-api/demo.jpg', + // 'https://s3.amazonaws.com/bw-v2-api/demo2.jpg' + // ], + // tag: 'test message' } +}); +``` + +{% common %} + +> The above command returns a JSON Response structured like this: + +```http +Status: 202 Accepted +Content-Type: application/json; charset=utf-8 + +{ + "id": "14762070468292kw2fuqty55yp2b2", + "time": "2016-09-14T18:20:16Z", + "to": [ + "+12345678902", + ], + "from": "+12345678901", + "text": "Hey, check this out!", + "tag": "test message", + "owner": "+12345678901", + "media": [ + "https://s3.amazonaws.com/bw-v2-api/demo.jpg", + "https://s3.amazonaws.com/bw-v2-api/demo2.jpg" + ], + "direction": "out" +} +``` + +{% endmethod %} \ No newline at end of file diff --git a/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.eot b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.eot new file mode 100644 index 0000000..756ec91 Binary files /dev/null and b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.eot differ diff --git a/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.svg b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.svg new file mode 100644 index 0000000..8a02375 --- /dev/null +++ b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.svg @@ -0,0 +1,1505 @@ + + + + + +Created by FontForge 20120731 at Mon Dec 5 09:47:19 2016 + By icons8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.ttf b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.ttf new file mode 100644 index 0000000..04bc0ee Binary files /dev/null and b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.ttf differ diff --git a/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.woff b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.woff new file mode 100644 index 0000000..f12ed87 Binary files /dev/null and b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.woff differ diff --git a/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.woff2 b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.woff2 new file mode 100644 index 0000000..1f10f49 Binary files /dev/null and b/styles/Bandwidth_7bcc72c72262137bb073a9172959118d.woff2 differ diff --git a/styles/website.css b/styles/website.css new file mode 100644 index 0000000..b013f2b --- /dev/null +++ b/styles/website.css @@ -0,0 +1,111 @@ +@charset "UTF-8"; +/* CSS Document */ + +.page-inner{ + margin-top: 0px; + top: 50px; +} +a[aria-label="Change Layout"]{ + display: none !important; +} +.book-summary{ + background-color: #f3f3f3; +} +.book-body, .book-summary{ + height: calc(100% - 70px); + position: fixed; + bottom: 0; + top: inherit; +} +.book-header{ + border-top: 1px solid rgba(0,0,0,.07); + top: 70px; +} +.book-header h1 a, .book-header h1 a:hover { + border-bottom: none; +} +.book-header .btn.lang-switcher.active { + background-color: #272B2D; + color: #00bcec; +} +.book-header .btn.lang-switcher { + text-transform: uppercase; + background-color: #272B2D; + color: #8e8e8e; + float: left; + line-height: 70px; + padding-bottom: 70px; + font-weight: bold; + -webkit-transition: all 0.3s; + -moz-transition: all 0.3s; + transition: all 0.3s; +} +.book-header .btn.lang-switcher:hover{ + color: #fff; +} +.api-method-example h3{ + margin-top: 0px; +} +.page-inner section{ + font-size: 1em !important; +} +.api-method-code { + color: #EEE; + background-color: #272B2D !important; + min-height: 100vh; + padding: 0px 30px 15px !important; +} +.api-method-code pre { + color: #EEE; + background-color: #272B2D; + border-radius: 3px; +} +.book-summary ul.summary li.active>a { + color: #00bcec; +} +.summary li:last-child{ + display: none; +} +.markdown-section h1 { + padding-top: 0px; + margin-top: 0px; +} +.markdown-section h2 { + font-size: 1.5em; + font-weight: 900; + text-transform: uppercase; + margin-top: 0px; + line-height: initial; +} +.book.color-theme-3 .book-header .btn.lang-switcher.active { + background-color: #186469; + background-color: #2D3134; + color: #fff; +} +.book-summary ul.summary li a, .book-summary ul.summary li span { + padding: 5px 15px; +} +.book-summary ul.summary li.header { + padding: 15px 15px 0px 15px; + font-size: .85em; + text-transform: uppercase; + color: #5f5f5f; + font-weight: 700; +} +.book-summary ul.summary li.header:first-child { + padding-top: 5px; +} +.book-header h1{ + display: none; +} +.pull-right{ + display: none; +} +.font-settings{ + display: none; +} +.chapter span{ + text-transform: uppercase; + color: #939da3 !important; + padding-top: 20px !important; +}