GETTING STARTED

Details on official and community-supported libraries to use in your web and mobile apps, along with information on setting up your apps to send appygrams and traces.

Libraries

Appygram uses a simple HTTP API that is easy to connect into any application.

Depending on your implementation language, you may be able to bootstrap your integration with existing open-source libraries:

Developed and supported by the Appygram team:

appygram.rb - simple Ruby connector
appygram-rails (beta) - sends traces for uncaught exceptions in Rails apps

Developed and supported by third parties:

appygram-node - Node connector (by @wlaurance); sends traces for Express
appygram-Ti - Titanium module (by @wlaurance)

For more information, see the README and/or documentation for each connector.

If you create and share an open-source Appygram connector library, let us know so we can link it here.

Sending an Appygram

Send an HTTP POST to https://arecibo.appygram.com/appygrams containing the fields of the appygram. You can use standard URL-encoded form submission, or (with MIME type application/json) send a JSON-formatted object.

Every POST to the /appygrams endpoint is guaranteed to result in at least one row written to the database, and -- in the absence of misconfiguration -- at least one delivery to the recipient. It is meant for human-generated messages that prompt one-to-one response.

The only required field is:

api_key: A valid Appygram API key for your application

All other fields are optional:

name: Submitter's name
email: Submitter's contact email
phone: Submitter's telephone number
message: Body of the message
platform: Platform of the submitter's system
software: Software version

The following fields are both optional and treated specially:

summary: A shorter version of the message. The system will auto-populate it from the message if you do not supply it.
topic: A string matching one of the topic names in your configuration. A string which does not match ANY topic name will be considered to match ALL topic names.
app_json: A string containing a block of valid JSON code.

An HTTP 200 response indicates success.

Sending an Appygram Trace (beta)

Send an HTTP POST to https://arecibo.appygram.com/traces containing the fields of the trace. You can use standard URL-encoded form submission, or (with MIME type application/json) send a JSON-formatted object.

A trace supports all the same fields as an appygram, with one optional addition:

trace: a JSON-formatted string, structured as:

{
class: 'class name',
message: 'error message',
backtrace: [
  ['line','number'],
  ['line','number']
] }

Unlike appygrams, traces are meant for machine-generated events, such as uncaught exceptions or logged events, and are meant to be acted on in the aggregate as opposed to one-to-one. All posts to the /traces endpoint are analyzed and counted, but notifications are only sent, and rows written to the database, in unusual circumstances, e.g.:

A new, unique trace is seen for the first time
The arrival rate of duplicate traces suddenly increases
Other triggers that you may configure

An HTTP 200 response indicates success.

APPYGRAM MANAGEMENT

Documentation on features available on Appygram.com for viewing and managing your apps and appygrams.

Dashboard

After logging in to Appygram.com, you'll be redirected to your dashboard. From here, you'll be able to view a feed of all the recent activity for your apps, news from Appygram, and a list of all the apps you own, manage, and watch. Click the name of an app to access its activity feed, index of appygrams, settings, API keys, and more.

Appygrams

The Appygrams tab holds a list of all appygrams that were sent by the system within the data limits allowed by your plan. At a glance, you'll be able to see the time the appygram was sent, who sent it, a summary of the contents, the topic of that appygram, and a notice if any problems occurred when attempting to send or forward the appygram via notifications. Each column is sortable, and you can combine sorting with filtering to hunt down appygrams you're interested in seeing.

Filtering

Click the "Apply Filters" button to begin the filtering process, and enter data into any fields you want to filter on. The e-mail and message contains fields support wildcards, so you can use an asterisk help your search. For example, searching for "sm*es" will match words like "smiles", "smores", and "smiling faces." This is also useful on the e-mail field for doing searches like "*@mycompany.com"

Erroneous Appygrams

If there is a problem sending your appygram via a notiification to its destination, the Appygrams page will display an exclamation point denoting the error, which you can click to see more information. Most commonly, errors will occur when using webhooks if there are communication issues with that service, such as an incorrect password, a mis-typed key, or their server being down.

Resend

If an appygram isn't sent due to error, or if you just want to send your appygram out again, you can use the resend button to do this. Resend will process all of your notifications for the selected topic again, so all targeted recipients will receive your appygram again.

Topics & Notifications

The Edit tab will allow you to set up topics and notifications for your App, which is how appygrams get processed and sent to other people or web services. At the bottom of the page are buttons for you to rename and delete your app.

Topics

Topics can be thought of as mailing lists or interest groups. You'll want to set up a topic based on what types of information you'll be receiving through appygram, and, more importantly, who specifically should be notified when that information is received . Each topic can have one or more notifications associated with it.

Notifications

Notifications allow you to configure what message you want to send to a particular user or service. You can format your message any way you see fit, then send that information from the appygram out. There are two types of notifications you can use to send messages out.

Mailer

Mailers allows you send formatted e-mail messages to a given recipient. For paid plans, you can send to up to 10 addresses, whereas the free plan allow to you send this message to your own e-mail.

Webhook

Webhooks, in their most generic form, allow you to talk to any web service and send over your appygram. Like mailers, you can specify a customized message format for your webhook to send to your web service of choice.

Using Preset templates

Many Appygram users will use the same set of web services, so our presets define a number of web services that you can select to auto-fill most of the information needed for you -- you just fill in the blanks.

Liquid Template Language

The content of the messages sent with webhooks can be formatted using Liquid's template engine. Liquid defines markup that allows you to do advanced formatting for your content. The variables allowed are defined on the configuration page.

API Keys

Create and use APIs in your web site, mobile application, or web service to send over appygrams. While most users may only need one key, there are many cases where having multiple keys is useful. For mobile apps, for example, it's useful to have a separate key for both Android and iOS builds.

Active vs Inactive

Deactivating keys allows you to keep your API key in-tact while prevent incoming appygrams. You can do this manually if you suspect your key has been compromised, or if you want to stop receiving notifications for a period of time. If Appygram detects that you or someone else is abusing your App by sending an alarming number of appygrams in a short period of time, that API key will be deactivated automatically. You can turn it back on once the problem is resolved.

Testing API Keys

Clicking "try it out" will generate a form that you can use to send a test appygram through the system. This appygram will notify all services based on the topic you select, and let you know if there were any errors. You can use this to check all your connections and notifications before deploying your API Key to your applications.

Team

A paid Appygram plan allows you to have an unlimited number of watchers and/or managers for your App. You can invite both new and existing users to collaborate on your App, and change or remove their membership role for your app at anytime.

Watchers

Watchers are allowed to view incoming appygrams for your App. They can not make any configuration changes, such as editing your app or adding other team members.

Managers

Managers can do everything the App owner can do, with the exception of deleting the App.

ACCOUNT MANAGEMENT

Access Account Management, including User Profile, Plan, and Invoices, via the "Hi, (user name)" link in the nav.

User Profile

At any time, a user may update their name, e-mail address, and password on the main screen in Account Management. All changes must be confirmed by entering the current password. The e-mail address is used for logging on to Appygram.com, as well as for default e-mail routings for appygrams. A user on the "Freegan" plan may only forward appygrams to this e-mail address.

Avatars are pulled from Gravatar, and are displayed in the dashboard and individual app streams.

My Plan

My Plan details the user's current Appygram plan, including listing the number of apps that come with the plan and the number used. My Plan also includes links to change plans, add extra apps to a plan, and cancel.

Changing Plans

A user may upgrade or downgrade their plan at any time by clicking the Change link. Logged in users may also click the "Plans & Pricing" link in the main nav to reach the same screen. Plan changes go into effect immediately.

Buying Extra Apps

Each paid plan comes with a certain number of apps. A user has the option to purchase additional single apps if they don't wish to upgrade to the next paid plan.

Cancel Account

A user may cancel their account at any time. Upon cancellation, the user's account and all their apps and appygrams will be deleted. This action can not be undone.

Billing & Invoices

At any time a user may download their invoices (PDF), as well as update their billing information on file.