diff --git a/applications/crossbar/doc/basics.md b/applications/crossbar/doc/basics.md index 56f98ef2b65..e44c8720c0d 100644 --- a/applications/crossbar/doc/basics.md +++ b/applications/crossbar/doc/basics.md @@ -1,340 +1,218 @@ -# API Basics +# A KAZOO API Primer -## Give it a REST +KAZOO’s REST API is big. We have tons of available endpoints, all that can be used to create, retrieve, update, or delete resources. That’s a lot of CRUD! -Crossbar is the REST API server, from which developers can build applications that configure Kazoo's myriad services and functionalities. +All of these endpoints work to provide you with a robust toolset for building applications, programmatically controlling your KAZOO accounts, or otherwise retrieving telephony data from KAZOO. This article lists information that you may find helpful in making your first API requests on the platform. -## Basic URI Structure +## Using the API -Requests Crossbar follows this structure: +--- -``` -/{VERSION}/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID} -``` - -Here the explanation: - -* `{VERSION}` - The version of the API you are calling. Currently the only support value is `v2`. -* `{ACCOUNT_ID}` - Most requests operate against a specific account and thus require the `account_id` to route the request properly -* `{RESOURCE_ID}` - When accessing a specific resource, like a device, user, or callflow, this is the `{RESOURCE_ID}` points to the specific instance you're accessing. - -### Resources - -There are two parts to how a request is routed in Crossbar: the REST endpoint and the resource ID. Let's break down a common URI and see how Crossbar figures out what is an endpoint and what is a resource ID. - -Given a URI of `/v2/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}`: - -1. First, strip the version off the URI: - * Version: `v2` - * URI Remaining: `/accounts/{ACCOUNT_ID}/devices/{DEVICE_ID}` -2. See if the next token is a REST endpoint module. It is, so track the module for later routing: - * Version: `v2` - * Modules: `{accounts: []}` - * URI Remaining: `/{ACCOUNT_ID}/devices/{DEVICE_ID}` -3. See if the next token is a REST endpoint module. It is not, so add the token to the last module's data: - * Version: `v2` - * Modules: `{accounts: [{ACCOUNT_ID}]}` - * URI Remaining: `/devices/{DEVICE_ID}` -4. Repeat parsing. devices is a REST endpoint: - * Version: `v2` - * Modules: `{accounts: [{ACCOUNT_ID}], devices: []}` - * Remaining URI: `/{DEVICE_ID}` -5. Repeat parsing. {DEVICE_ID} is an argument: - * Version: `v2` - * Modules: `{accounts: [{ACCOUNT_ID}], devices: [{DEVICE_ID}]}` - -So we have a request to account `{ACCOUNT_ID}` to do something with a device `{DEVICE_ID}`. - -## HTTP Verbs - -The HTTP verb will determine the class of actions to take against the resource. Generically speaking, the verbs map thusly: - -* `/v2/accounts/{ACCOUNT_ID}/resources` - * `GET`: Fetches a summary of configured resources - * `PUT`: Creates a new instance of the resource. - -* `/v2/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}` - * `GET`: Fetches the full representation of the resource - * `POST`: Updates the full representation of the resource - * `DELETE`: Deletes the resource +NOTE: The documentation assumes you own a KAZOO account, whether in one of our commercial environments or your own open source installation. Visit our website to learn about getting started. -### PATCH +KAZOO runs an API server that we call **Crossbar**. By default, Crossbar listens for incoming HTTP requests on port 8000. If you're experienced with making HTTP requests to an API, Crossbar should be pretty easy to get started with. Generally, the biggest hurdles for people getting started are that they have the incorrect server URL, the wrong account ID, or that they are not correctly formatting things such as their account ID when constructing auth tokens or hashes. -Some resources are supporting the `PATCH` verb, allowing partial updates instead of requiring the request to include the full version of the document. `/users/{USER_ID}`, for instance, supports `PATCH`: +## How Do I Authenticate Crossbar Requests? -```shell -curl -v -X PATCH \ - -H "Content-Type: application/json" \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - 'http://crossbar.server.com:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}' \ - -d '{"data":{"vm_to_email_enabled":true}}' -``` -This cURL request will patch the user's document and set `vm_to_email_enabled` to `true`. All normal validation will occur after patching the document; this also means clients can `PATCH` documents with their own data only. - -If a resource does not support `PATCH` yet, clients can expect to receive a `405 Method Not Allowed` error. +--- -### Tunneling the HTTP Verb +The most convenient way to make API requests with KAZOO across different interfaces like cURL, SDKs, or Postman, is by generating an access token. Once this is complete, authenticating requests is as easy as adding the `X-AUTH-TOKEN` HTTP header to your requests. Most KAZOO SDKs will allow you to create a persistent client that takes in an access token in order to instantiate. -Some clients do not support the full range of HTTP verbs, and are typically limited to `GET` and `POST`. To access the functionalities of `PUT` and `DELETE`, you can tunnel the verb in a `POST` in a couple of ways: +DID YOU KNOW?: You can obtain an access token by logging into your KAZOO’s MonsterUI portal. When you’re logged in, pressing the ‘**d**’ key will bring up debug fields. One of them is a valid access token for your account. It’s the one your MonsterUI is using to make requests to KAZOO! You can copy this to be used for your own API requests. -1. As part of the [request envelope](#request-envelope): `{"data":{...}, "verb":"PUT"}` -2. As a query string parameter: `/v2/accounts/{ACCOUNT_ID}/resources?verb=PUT` +You can also obtain an access token by making a request to the API using [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme), authenticated with your Account ID (which is the 32-character account identifier string, NOT your username) and password, to first get your API key. The format of this is `${accountId}:${password}`. -### Tunneling the Accept Header +Once you have an API key, you can use it to get the access token. For example, if you were to use cURL, you could do the following. -Some clients do not support the ability to set the [Accept header](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) in the request, meaning they will not necessarily receive the response in the format they wish. Clients can append `accept=text/html` to the request body or query string to indicate they'd like the response processed as if the Accept header was `text/html`. +--- -!!! note - `accept=csv` is retained for backwards-compatibility but it is encouraged to use a proper media type going forward. +Using the endpoint `/v2/accounts/{$ACCOUNT_ID}/api_key` and HTTP Basic Authorization: -## Request Envelope +**Request** -When issuing a `PUT`, `POST` or `PUT`, a request body is needed. When submitting a JSON (the most common body), Crossbar expects a request envelope with a few bits of metadata: - -* `data`: this top-level key will contain the object you wish to create/update -* `auth_token`: optionally put your auth token in the envelope -* `verb`: optionally tunnel a `PUT` or `DELETE` in a `POST` request - -**Sample Request Envelope:** - -```json -{ - "data": { - "foo": "bar" - }, - "auth_token": "{AUTH_TOKEN}", - "verb": "delete" -} +```bash +curl -v -X GET \ + --basic --user $ACCOUNT_ID:$PASSWORD \ + http://$SERVER:8000/v2/accounts/{ACCOUNT_ID}/api_key ``` -## Request Data - -When using `PATCH` to edit entities, if you want to remove a field from the entity, set it to `null`: +**Response** -```json +```jsx { - "data": { - "update":"this", - "exists": null - } + "data":{ + "api_key":"{API_KEY}" + }, + "revision":"{REQUEST_ID}", + "request_id":"{REQUEST_ID}", + "status":"success" } ``` -This request would set `update` to `this` and would remove `exists` from the entity. +--- -## Response Envelope +Once you’ve fetched your API key, you can then pass it as a request body to the `/v2/api_auth` endpoint. The response will include an auth token you can then use for future requests. -When receiving JSON responses, clients will receive the response in an envelope. The response includes some duplicated data from the HTTP Response headers, since some clients do not have access to those headers. +**Request** -* `data`: contains the results of the request, if any -* `auth_token`: contains the `auth_token` used on the request -* `status`: One of `success`, `error`, or `fatal` -* `message`: Optional message that should clarify what happened on the request -* `error`: Error code, if any -* `request_id`: ID of the request; usable for debugging the server-side processing of the request +```bash +curl -v -X PUT \ + -d '{"data": {"api_key":"{API_KEY}"} }' \ + http://$SERVER:8000/v2/api_auth +``` -**Sample Response Envelope:** +**Response** ```json { + "auth_token": "{AUTH_TOKEN}", "data": { - "the": "response", - "data": "is here" + "account_id": "{ACCOUNT_ID}", + "apps": [...], + "is_reseller": true, + "language": "en-US", + "owner_id": "{OWNER_ID}", + "reseller_id": "{RESELLER_ID}", }, - "auth_token": "{AUTH_TOKEN}", - "status": "success", - "request_id": "{REQUEST_ID}" + "request_id": "{REQUEST_ID}", + "revision": "{REVISION}", + "status": "success" } ``` -## Pagination - -All listing APIs will be paginated by default. +Make sure that you are constructing the data envelope correctly when sending the request. -Let's take a look at the CDRs API to see how to interpret pagination. +--- -### CDR Pagination +If you already have a valid auth token, there is no need to do the first request with HTTP basic authentication. You can just use the auth token for all requests like this: -We start with the typical CDR request for a listing of CDRs: - -```shell -curl -v \ +```bash +curl -v -X GET \ -H "X-Auth-Token: {AUTH_TOKEN}" \ - -H "Content-Type: application/json" \ - http://{SERVER_URL}:8000/v2/accounts/{ACCOUNT_ID}/cdrs -``` - -```json -{ - "auth_token": "{AUTH_TOKEN}", - "data": [ - {CDR_OBJECT}, - {CDR_OBJECT}, - ... - ], - "next_start_key": "g2wAAAACbgUAvn1W1A5tAAAACDk4MDE2ODAwag", - "page_size": 25, - "request_id": "{REQUEST_ID}", - "revision": "{REVISION}", - "start_key": "g2wAAAACbgUAb0ZX1A5oAWpq", - "status": "success" -} + http://$SERVER:8000/v2/accounts/{ACCOUNT_ID} ``` -The pagination response keys are `next_start_key`, `page_size`, and `start_key`. - -* `next_start_key`: used to get the next page of results from this API. Will not exist if this is the last page. -* `start_key`: used to get back to this page of results (or start pagination from this point) -* `page_size`: the number of results returned in this page - -Assuming no changes are made to the underlying documents, `start_key` will get you this page of results, and `next_start_key` will give you a pointer to the next page (imagine a linked-list). +--- -### Encoded Start Keys (Kazoo 4.2+ Only) +Once obtained, the auth token can be used to make API requests scoped to your account. Be aware that auth tokens only last a default of one hour. -As you can see from the response above, both the `start_key` and `next_start_key` are encoded as URL-safe Base64 strings of their Erlang term representation. A couple character substitutions (`_` for `/` and `_` for `+`) and one character removal (`=`) ensures a string that plays nice in URLs. +This is pretty much all you need to know to be authenticated to make requests! You can see all authentication APIs and associated payloads in the API reference. -In practice, the client should treat these keys as opaque and supply them as-is in future requests. +## An Example API Request -### Requesting next page +Now that we have an auth token, let’s make a request to fetch data from a KAZOO account. Let’s try sending a `GET` request a simple (but important) endpoint `/v2/accounts/{account_id}`. Don’t forget to include the authorization token as a header, with a key of `X-Auth-Token`. -Using the `next_start_key` value, let's request the next page of CDRs: +**Request** -```shell -curl -v \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - -H "Content-Type: application/json" \ - http://{SERVER_URL}:8000/v2/accounts/{ACCOUNT_ID}/cdrs?start_key=g2wAAAACbgUAb0ZX1A5oAWpq +```jsx +$ curl -x GET \ + -H "X-Auth-Token: {AUTH_TOKEN}" \ + 'http://{server}:8000/v2/accounts/{ACCOUNT_ID}' ``` -```json +**Response** + +```jsx { "auth_token": "{AUTH_TOKEN}", - "data": [ - {CDR_OBJECT}, - {CDR_OBJECT}, - ... - ], - "next_start_key": "g2wAAAACbgUAbyYO1A5tAAAACDYwMTIzYjdiag", - "page_size": 25, + "data": { + "billing_mode": "manual", + "call_restriction": {}, + "caller_id": {}, + "created": 63621662701, + "dial_plan": {}, + "enabled": true, + "id": "{ACCOUNT_ID}", + "is_reseller": false, + "language": "en-us", + "music_on_hold": {}, + "name": "child account", + "preflow": {}, + "realm": "aeac33.sip.2600hz.com", + "reseller_id": "undefined", + "ringtones": {}, + "superduper_admin": false, + "timezone": "America/Los_Angeles", + "wnm_allow_additions": false + }, "request_id": "{REQUEST_ID}", "revision": "{REVISION}", - "start_key": "g2wAAAACbgUAb0ZX1A5oAWpq", "status": "success" } ``` -Observe now that `start_key` is the requested `start_key` and `next_start_key` points to the start of the next page of results. - -!!! note - If `next_start_key` is missing from the response envelope, the response represents the last page of results. - -You can also choose to receive pages in bigger or smaller increments by specifying `page_size` on the request. Do take care, as the `next_start_key` will probably vary if you use the same `start_key` but differing `page_size` values. - -### Setting Page Size - -By default, API requests have a page size of 50 results. This value is customizable by system administrator in the `crossbar.maximum_range` system config setting. +As you can see, this account endpoint will contain configurations related to your account. You can get more information about this endpoint from the Accounts documentation section. -For individual API request, you can also include a `page_size` query string parameter. For example: `http://{SERVER}:8000/v2/{API_URL}?page_size=25`. +## KAZOO URI Structure -### Setting sorting order +When you make a request to KAZOO, the majority of requests you’ll want to make act upon a couple of important identifiers. -By default, Crossbar returns the results in descending order. To get results in ascending order either set `ascending=true` (Kazoo 4.2+ only) or `descending=false` in the request query string. +Let’s break down the following URI structure: -!!! note - The field used to sort the individual API results depends on the internal implementation of the API endpoint and is not controllable by the client. +`/{VERSION}/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}` -### Disabling Pagination +The components of this URI are: -If you want to disable pagination for a request, simply include `paginate=false` on the query string. +1. `{VERSION}` + - The version of the API endpoint, currently `v2` for all supported APIs found in this documentation. -#### Protecting from (un)intentional abuse +1. `/accounts/{ACCOUNT_ID}` + - This is your KAZOO account ID, a 32-character hex-encoded identifier. -Since pagination can be turned off by a client-supplied query string parameter, it is important that KAZOO still protect itself from overly large datasets being loaded. Examples seen include large CDR listings, call recording listings, and ledger listings. +1. `/{RESOURCE}/{RESOURCE_ID}` + - A resource, such as `devices`, `users`, `callflows`, et cetera. + - The ID of the resource, usually also hex-encoded identifier. -Therefore, during a non-paginated request, KAZOO monitors memory consumption of the handling server process and will abort the request if the processing is exceeding a high watermark setting (configured by the system operator). The client can expect to receive an HTTP "416 Range Not Satisfiable" error as a result of exceeding the limit. +## Helpful Information About KAZOO’s API -The memory limit threshold can be set by system administrators with +This section lists additional information that you may find helpful about navigating KAZOO’s numerous APIs. - sup kapps_config set_default crossbar request_memory_limit 10485760 +### HTTP Verbs -In this case, memory per-request (for listings) is constrained to 10MB. +It’s helpful to identify how the HTTP request verb defines what we want to *do* when we request a resource. There are a couple URI patterns that you’ll see throughout the API, with verb patterns that can be described generically like this: -## Chunked Response +- `/v2/accounts/{ACCOUNT_ID}/resources` + - Example: `/v2/accounts/{ACCOUNT_ID}/devices` + - `GET`: Fetches a summary of configured resources. A GET will return a collection of devices under the account. + - `PUT`: Creates a new instance of the resource. Sent with JSON, your request body will contain the necessary information about the resource you want to create. +- `/v2/accounts/{ACCOUNT_ID}/resources/{RESOURCE_ID}` + - Example: `/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}` + - `GET`: Fetches the full representation (all exposed fields) of a resource. + - `POST`: Updates the full representation of the resource. + - `DELETE`: Deletes the resource. -Starting with Kazoo 4.2, most of the summary API endpoints can send [chunked responses](https://en.wikipedia.org/wiki/Chunked_transfer_encoding). Some known APIs, which tend to have larger datasets, are chunked by default (e.g. `/cdrs/interaction` and `/ledgers/{LEDGER}`). +### The Request Envelope -The query string parameter `is_chunked` (boolean value) can be used to enable or disable chunking per-request. +When issuing a `PUT`, `POST` or `PUT`, a request body is needed. When submitting a JSON (the most commonly accepted format across endpoints), Crossbar expects a request envelope with a few bits of metadata: -To set the default chunk size, you can use `chunk_size` in the query string. Default value is `50`. +- `data`: This top-level key will contain the object you wish to create/update +- `auth_token`: Optionally, you can include your auth token in the envelope +- `verb`: Optionally tunnel a `PUT` or `DELETE` in a `POST` request -## Pretty Printing - -If needed, the JSON response to be pretty printed, the server can can do so. - -Include pretty printing inside the header. - -```shell -curl -v \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - -H "Content-Type: application/json" \ - -H "X-Pretty-Print:true" \ - http://{SERVER_URL}:8000/v2/accounts/{ACCOUNT_ID}/ -``` - -If the client cannot use headers the options can be included inside the URI. - -```shell -curl -v \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - -H "Content-Type: application/json" \ - http://{SERVER_URL}:8000/v2/accounts/{ACCOUNT_ID}?pretty_print=true -``` - -## Requesting a range of binary data - -It is useful to be able to get just a section of a file when streaming or -resuming a download. This can be accomplished with the range header, e.g.: - -```shell -curl -v \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - -H "Content-Type: application/json" \ - -H "Accept: audio/mpeg" \ - -H "Range: bytes={START_BYTE}-{END_BYTE}" \ - http://{SERVER_URL}:8000/v2/accounts/{ACCOUNT_ID}/vmboxes/{VMBOX_ID}/messages/{MESSAGE_ID}/raw -``` - -## Requesting data in CSV format - -In some cases (e.g. CDR) its possible to request data in CSV format You must define the Content-type in the header you can define the file name in the request header or URL (Optional) - -```shell -curl -v -X GET \ - -H "Accept: text/csv" \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - -H "X-File-Name: {FILE_NAME}" \ - http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs -``` - -or +**Sample Request Envelope:** -```shell -curl -v -X GET \ - -H "Accept: text/csv" \ - -H "X-Auth-Token: {AUTH_TOKEN}" \ - http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/cdrs?file_name={FILE_NAME} +```json +{ + "data": { + "foo": "bar" + }, + "auth_token": "{AUTH_TOKEN}", + "verb": "DELETE" +} ``` -## Timestamps - -KAZOO, unless explicitly stated, represents time in Gregorian seconds. +### Information About PATCH -Conversion with UNIX timestamps is straightforward: +Some resources support the `PATCH` verb, which allows partial updates instead of requiring the request to include the full version of the document. `/users/{USER_ID}`, for instance, supports `PATCH`: +```bash +curl -v -X PATCH \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: {AUTH_TOKEN}" \ + 'http://crossbar.server.com:8000/v2/accounts/{ACCOUNT_ID}/users/{USER_ID}' \ + -d '{"data":{"vm_to_email_enabled":true}}' ``` -UnixEpochInGregorian = 62167219200 -gregorian_to_unix($greg) -> $greg - 62167219200 +This cURL request will patch the user's document and set `vm_to_email_enabled` to `true`. All normal validation will occur after patching the document; this also means clients can PATCH documents with their own data only. -unix_to_gregorian($unix) -> $unix + 62167219200 -``` +If a resource does not support `PATCH` yet, clients can expect to receive a `405 Method Not Allowed` error. \ No newline at end of file diff --git a/doc/intro.md b/doc/intro.md new file mode 100644 index 00000000000..48d94289f7f --- /dev/null +++ b/doc/intro.md @@ -0,0 +1,29 @@ +# Intro and Background on KAZOO + +## What is KAZOO? + +KAZOO is an API-based platform that lets you use your existing phones, programming languages and IT skills to build voice, video and SMS services. We focus on building a simple, powerful communications platform and let you focus on marketing, servicing and integrating communications with your clients systems. + +KAZOO leverages several open source technologies such as FREESWITCH, Kamailio, RabbitMQ, and CouchDB in order to provide a robust set of telephony features. You as the developer can start here to learn how to use KAZOO to build your own communications applications on top of the existing core. + +## How do I Get Started? + +KAZOO is open-core, meaning that you are free to clone, modify, or otherwise utilize the [kazoo-core](https://www.github.com/2600hz/kazoo-core) source code. If you’re interested in building KAZOO from source, this [guide](https://github.com/2600hz/kazoo/blob/master/doc/installation.md) is an appropriate jump-off point. Otherwise, visit our [website](http://2600hz.com) to get in contact about scheduling a demo. + +We at 2600Hz also offer production-grade applications as well as KAZOO cluster hosting and management as services. Visit our [website](http://2600hz.com) for more information. All our guides will assume that you have a KAZOO environment to develop against, whether you’re an open source user or a 2600Hz customer. + +## What can I Build with KAZOO? + +The sky is truly the limit when it comes to building atop KAZOO: full telephony applications such as call center software, visibility dashboards, customized billing engines, and more are very much possible to create—in fact, many of these have been created by us at 2600Hz, our partners, or hobbyist developers with great ideas! + +As part of our developer documentation, we’ll walk through writing applications that leverage KAZOO in different ways. Given how robust the platform already is from a feature perspective, many people are now interested in how to leverage KAZOO’s Webhooks and Websockets functionality, integrations with different CRMs, and other concepts related to integrating KAZOO with other services. We’ll also talk about how to get started on some of these hot topics. + +## Basic API Information + +Almost all requests and responses to the KAZOO API are serialized using JSON, unless otherwise specified in the documentation. You may find, for example, an endpoint will respond with XML instead of JSON. + +The KAZOO API is built on widely-adopted architectures and specifications such as REST (for API consistency) or [JSON-Schema](http://json-schema.org/) (for data validation). You can use any HTTP client to interact with the API, whether via a programming language’s HTTP library, a HTTP GUI like Postman, or just plain old cURL in the terminal. There is very little overhead in order to get started making requests against your KAZOO account. + +## KAZOO Versioning and API Consistency + +Expect to encounter inconsistencies with official documentation material if you are using features or KAZOO versions that are outside of what we use in our own stable commercial environments. This means that, if you are for example running an older (or newer experimental) version of KAZOO, that this documentation may not be accurate for your given environment. We recommend using our [community forums](https://forums.2600hz.com/forums/) to ask questions. diff --git a/doc/mkdocs/commercial.yml b/doc/mkdocs/commercial.yml index ea8c1f55212..27bb76d1320 100644 --- a/doc/mkdocs/commercial.yml +++ b/doc/mkdocs/commercial.yml @@ -6,14 +6,13 @@ site_name: Kazoo API Reference site_description: 'REST API Reference for Kazoo Crossbar API' pages: -- 'index.md' +- 'doc/intro.md' - 'The Basics': - 'Quick Start': - 'applications/crossbar/doc/basics.md' - 'applications/crossbar/doc/api_authentication.md' - 'applications/crossbar/doc/sdks.md' - 'Common Tasks': -#BUILD Intro to accounts (what they are for, when to use them, encourage the user to do this last) - 'Account Management' : 'applications/crossbar/doc/accounts.md' # - 'Billing Users, Devices and DIDs' : 'tutorial/count_devices.md' # - 'Processing CDRs' : 'tutorial/count_devices.md' @@ -36,33 +35,16 @@ pages: - 'System Preparation': - 'Branding': - 'applications/crossbar/doc/whitelabeling.md' ## -# Email notifications? Macros? Templates? - 'Limits and Rating': - 'applications/crossbar/doc/allotments.md' ## - 'applications/crossbar/doc/limits.md' ## -#BUILD - 'Common Tasks': -#BUILD - 'applications/crossbar/doc/your_first_subaccount.md' -#BUILD - 'Billing Users, Devices and DIDs' : 'tutorial/count_devices.md' -#BUILD - 'Processing CDRs' : 'tutorial/count_devices.md' -#BUILD - 'Generating Stats' : 'tutorial/call_stats.md' -#BUILD - 'Bulk Provisioning' : 'tutorial/bulk_provision.md' -#BUILD - 'Building a User Portal' : 'tutorial/user_portal.md' -#BUILD - 'Event Notification' : 'tutorial/webhooks.md' -#BUILD - 'Streaming Live Activity' : 'tutorial/stream_events.md' -#BUILD - 'Controlling Calls' : 'tutorial/call_control.md' -#BUILD - 'Integrating Mobile Services' : 'tutorial/mobile_services.md' - - 'Configuration APIs': - 'Users and Devices': - 'applications/crossbar/doc/devices.md' - 'applications/crossbar/doc/users.md' -#BUILD - 'Basic Phone Number Setup': -#BUILD - 'Buying a Number': 'applications/crossbar/doc/phone_numbers_buy.md' -#BUILD - 'Routing a Number to a Callflow': 'applications/crossbar/doc/callflows_basic.md' # (Basic callflow) - - 'Features': - 'Conference Bridges': - 'Configuring Conference Rooms': 'applications/crossbar/doc/conference.md' @@ -157,9 +139,6 @@ pages: - 'applications/crossbar/doc/notifications.md' - -#### STARTS "STILL NEEDS SORTING" SECTION - please pair with configuration APIs as applicable, in the right section - - 'Advanced API Usage': - 'Global API Features': - 'applications/crossbar/doc/filters.md' @@ -289,11 +268,12 @@ pages: # - 'applications/crossbar/doc/about.md' # - 'applications/crossbar/doc/acls.md' ## -#- 'Articles': +- 'Articles': # - 'Introduction to Storage Plans - S3': 'doc/blog/storage.md' # - 'Bypass Media Mode': 'doc/blog/bypass_media.md' # - 'Introduction to Rating and Limits': 'doc/reference/routing.md' # - 'Call Recording': 'doc/user_guides/call_recording.md' + - 'A First App: Voicemail Example": '/doc/user_guides/first_app_forward_voicemail.md' ############ Doc Status Key ################# # | ## : Incomplete diff --git a/doc/user_guides/first_app_forward_voicemail.md b/doc/user_guides/first_app_forward_voicemail.md new file mode 100644 index 00000000000..60afd84a280 --- /dev/null +++ b/doc/user_guides/first_app_forward_voicemail.md @@ -0,0 +1,303 @@ +# A First App: Let’s Forward Voicemail + +One of the things that we at 2600Hz pride ourselves on is the fact that KAZOO's open core means everyone, including us, uses the same APIs to develop applications. One of our longtime engineers, James Aimonetti, had this to say once about building on KAZOO versus other platforms: + +> KAZOO offers the [open core](https://en.wikipedia.org/wiki/Open_core) model, so the majority of typical APIs are built into the open source project. Some of the MonsterUI applications are closed [source], true, but the APIs they build on are open for you to build on as well. Nothing in KAZOO checks whether it’s MonsterUI making the API call vs another client. So anything you might see demoed [by 2600Hz] is possible. + +With that in mind, let’s walk through an example application that allows us to view, save to local disk, or delete voicemails from an account, with just the click of a couple buttons. We’re going to keep the code as simple as possible, and then get into more complex tasks in the future. + + +NOTE: Be warned that deleting voicemails is a permanent action. Only delete test voicemails! Saving VMs is non-destructive, but we still recommend only using test voicemails for this guide. + + +## Prerequisites + +--- + +This guide assumes that you have: + +1. A KAZOO account +2. A created user +3. A registered device that can make outbound calls +4. An auth token (see [API Basics](../../applications/crossbar/basics.md) for how to get one) + +If you need help with any of the prerequisites, you can check out our [Community](https://forums.2600hz.com/forums) for guides and discussions about troubleshooting issues. + +## Skeleton Code + +Provided is an HTML file to render the SMS that we receive from the KAZOO API, and also giving us clickable buttons that allow the user to forward a voicemail to the inputted address or delete the voicemail. The file calls a script, `api.js`, that we will define in the below section. + +**index.html** + +```html + +