Skip to content

Commit

Permalink
init commit
Browse files Browse the repository at this point in the history
  • Loading branch information
Dan Tolbert committed Feb 3, 2017
1 parent e827bc2 commit 2b8ce98
Show file tree
Hide file tree
Showing 30 changed files with 2,783 additions and 2 deletions.
17 changes: 15 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
22 changes: 22 additions & 0 deletions SUMMARY.md
View file
Original file line number Diff line number Diff line change
@@ -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)
43 changes: 43 additions & 0 deletions application.md
View file
Original file line number Diff line number Diff line change
@@ -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 <code class="get">GET</code> request to your application id.

<code class="get">GET</code>`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"
}
```
63 changes: 63 additions & 0 deletions book.json
View file
Original file line number Diff line number Diff line change
@@ -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
}
}
}
43 changes: 43 additions & 0 deletions errors/badRequest.md
View file
Original file line number Diff line number Diff line change
@@ -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 %}
32 changes: 32 additions & 0 deletions errors/forbidden.md
View file
Original file line number Diff line number Diff line change
@@ -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 %}
28 changes: 28 additions & 0 deletions errors/tooManyReq.md
View file
Original file line number Diff line number Diff line change
@@ -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 %}
32 changes: 32 additions & 0 deletions errors/unauth.md
View file
Original file line number Diff line number Diff line change
@@ -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 %}
58 changes: 58 additions & 0 deletions events/groupReject.md
View file
Original file line number Diff line number Diff line change
@@ -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.<br> For an outbound message, this is always the `from` number.<br> For an inbound message, this will be (one of) the `to` number(s).<br>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 %}
Loading

0 comments on commit 2b8ce98

Please sign in to comment.