{"_id":"56d1f33a00a2a70b00b365b3","__v":39,"category":{"_id":"56d1f33900a2a70b00b36593","__v":2,"project":"5526c95cf69851170038b48f","version":"56d1f33700a2a70b00b3658e","pages":["56d1f33a00a2a70b00b365aa","56d1f33a00a2a70b00b365ab","56d1f33a00a2a70b00b365ac","56d1f33a00a2a70b00b365ad","56d1f33a00a2a70b00b365ae","56d1f33a00a2a70b00b365af","56d1f33a00a2a70b00b365b0","56d1f33a00a2a70b00b365b1","56d1f33a00a2a70b00b365b2","56d1f33a00a2a70b00b365b3","56d1f33a00a2a70b00b365b4","56d1f33a00a2a70b00b365b5","56d1f33a00a2a70b00b365b6","56d1f33a00a2a70b00b365b7","56d1f33a00a2a70b00b365b8","56d1f33a00a2a70b00b365b9","56d1f33a00a2a70b00b365ba","56d1f33a00a2a70b00b365bb","56d1f33a00a2a70b00b365bc","56d1f33a00a2a70b00b365bd","56d1f33a00a2a70b00b365be","56d1f33a00a2a70b00b365bf","56d1f33a00a2a70b00b365c0","56d31b848161a00b00dc458a"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-10T15:00:49.659Z","from_sync":false,"order":3,"slug":"ionic-push","title":"Ionic Push"},"version":{"_id":"56d1f33700a2a70b00b3658e","project":"5526c95cf69851170038b48f","__v":2,"createdAt":"2016-02-27T19:04:23.946Z","releaseDate":"2016-02-27T19:04:23.946Z","categories":["56d1f33900a2a70b00b3658f","56d1f33900a2a70b00b36590","56d1f33900a2a70b00b36591","56d1f33900a2a70b00b36592","56d1f33900a2a70b00b36593","56d1f33900a2a70b00b36594","56d1f33900a2a70b00b36595","56d1f33900a2a70b00b36596","56d1f33900a2a70b00b36597","56d1f33900a2a70b00b36598","56d1f33900a2a70b00b36599","56d1f33900a2a70b00b3659a","571f9497ada30c34003b7cee"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"beta","version_clean":"2.0.0-beta","version":"2.0.0-beta"},"parentDoc":null,"project":"5526c95cf69851170038b48f","user":"5526ca4cf69851170038b496","updates":["5609b0ca851e1d1900683c4f","563a16c6daf1c00d00136d49","565e07d59c95180d00e22a22","570e1733132c6d2b0000aafd","575325d376b3b70e0007f329","576d633fb76bb30e0076293e","57b616541d223f0e00a9c723"],"next":{"pages":[],"description":""},"createdAt":"2015-04-10T15:38:37.042Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Contents\"\n}\n[/block]\n## General\n\n* [Notifications vs. Messages](doc:push-sending-push#section-notifications-vs-messages)\n\n## Requests\n\n* [Basic API usage](doc:push-sending-push#section-basic-api-usage)\n* [Sending via user ID's](push-sending-push#section-sending-a-push-to-ionic-user-id-s)\n* [Scheduling a push for later delivery](doc:push-sending-push#section-scheduling-a-push-for-later-delivery)\n* [Adding custom data to notifications](push-sending-push#section-adding-custom-data-to-your-notifications)\n* [Customizing notification appearance](push-sending-push#section-customizing-your-notification-appearance)\n* [PhoneGap Push Plugin Options](push-sending-push#section-phonegap-push-plugin-options)\n* [Templating push content](doc:push-sending-push#section-templating-your-push-content)\n* [Setting delivery priority](push-sending-push#section-setting-your-notification-s-priority)\n* [Setting notification time to live](push-sending-push#section-giving-your-notifications-a-ttl-time-to-live-)\n* [Delaying notifications to idle devices](push-sending-push#section-delaying-notifications-to-idle-devices)\n* [Sending background notifications](push-sending-push#section-sending-background-notifications)\n* [Checking the status of a notification](doc:push-sending-push#section-checking-the-status-of-a-push)\n\n## Responses\n\n* [Notification State](push-sending-push#section-notification-state)\n* [Notification Status](push-sending-push#section-notification-status)\n* [Message Status](push-sending-push#section-message-status)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"\"\n}\n[/block]\nAssuming you have registered some devices and uploaded the relevant credentials to a [security profile](doc:security-profiles), you're ready to start sending some push notifications! There are two main ways of accomplishing this; through the REST API and using the [ionic.io](https://apps.ionic.io/) dashboard.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/iDeg3xM9Qfa2DBH3mFPu_send-push-diagram.png\",\n        \"send-push-diagram.png\",\n        \"2075\",\n        \"772\",\n        \"#4181b1\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"General\"\n}\n[/block]\n## Notifications vs. Messages\n\nIonic.io push is composed of two main concepts, **Notifications** and **Messages**.  We define them like so:\n\n* **Notifications**: The individual push notifications you create and send via the API or the ionic.io dashboard.  These may have any number of recipients (via user ID's, device tokens, or queries).\n* **Messages**: A recipient of a notification.  For instance, a push you send to 10 device tokens will be comprised of 10 messages.  These track their delivery status independently, giving you granular detail on their delivery.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Requests\"\n}\n[/block]\n## Basic API usage\n\nIonic.io has an API endpoint which you can use to send push notifications from your backend server (or with a **curl** for testing).\n\nYou can send a push notification by making a **POST** to \n\n`https://api.ionic.io/push/notifications`\n\nwith the following headers.\n\n```javascript\nContent-Type: application/json\nAuthorization: Bearer <your-authentication-token>\n```\n\n(If you're unsure what to put for the authentication token, check out [the docs](doc:api-getting-started) here)\n\nThe POST data should be a JSON object of the following format as well:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"tokens\\\": [\\\"your\\\", \\\"device\\\", \\\"tokens\\\"],\\n  \\\"profile\\\": \\\"my-security-profile\\\",\\n  \\\"notification\\\": {\\n    \\\"title\\\": \\\"Hi\\\",\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"android\\\": {\\n      \\\"title\\\": \\\"Hey\\\",\\n      \\\"message\\\": \\\"Hello Android!\\\"\\n    },\\n    \\\"ios\\\": {\\n      \\\"title\\\": \\\"Howdy\\\",\\n      \\\"message\\\": \\\"Hello iOS!\\\"\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nLet's take a look at the individual parts of that.\n\n* `\"tokens\"`: An array of the device tokens you wish to receive this notification.\n* `\"profile\"`: The name of the [security profile](doc:security-profiles) which contains the push credentials you wish to use for this notification.\n* `\"notification\"`: The actual notification object.  As you can see, a default `title` and `message` text are specified, and can be overwritten for each platform individually.\n\nHere's an Angular example, sending the above notification:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Define relevant info\\nvar jwt = 'your-authorization-token';\\nvar tokens = ['your', 'target', 'tokens'];\\nvar profile = 'your-security-profile-name';\\n\\n// Build the request object\\nvar req = {\\n  method: 'POST',\\n  url: 'https://api.ionic.io/push/notifications',\\n  headers: {\\n    'Content-Type': 'application/json',\\n    'Authorization': 'Bearer ' + jwt\\n  },\\n  data: {\\n    \\\"tokens\\\": tokens,\\n    \\\"profile\\\": profile,\\n    \\\"notification\\\": {\\n      \\\"title\\\": \\\"Hi\\\",\\n      \\\"message\\\": \\\"Hello world!\\\",\\n      \\\"android\\\": {\\n        \\\"title\\\": \\\"Hey\\\",\\n        \\\"message\\\": \\\"Hello Android!\\\"\\n      },\\n      \\\"ios\\\": {\\n        \\\"title\\\": \\\"Howdy\\\",\\n        \\\"message\\\": \\\"Hello iOS!\\\"\\n      }\\n    }\\n  }\\n};\\n\\n// Make the API call\\n$http(req).success(function(resp){\\n  // Handle success\\n  console.log(\\\"Ionic Push: Push success\\\", resp);\\n}).error(function(error){\\n  // Handle error \\n  console.log(\\\"Ionic Push: Push error\\\", error);\\n});\",\n      \"language\": \"javascript\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nAnd here's an example response you could get from the server:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"meta\\\": {\\n    \\\"request_id\\\": \\\"your-request-id\\\",\\n    \\\"version\\\": \\\"2.0.0-beta.0\\\",\\n    \\\"status\\\": 201\\n  },\\n  \\\"data\\\": {\\n    \\\"uuid\\\": \\\"your-notification-uuid\\\",\\n    \\\"app_id\\\": \\\"your-app-id\\\",\\n    \\\"state\\\": \\\"enqueued\\\",\\n    \\\"created\\\": \\\"2016-02-29T16:24:41.927954+00:00\\\",\\n    \\\"config\\\": {\\n      \\\"tokens\\\": [\\\"your\\\", \\\"device\\\", \\\"tokens\\\"],\\n      \\\"profile\\\": \\\"your-security-profile\\\",\\n      \\\"notification\\\": {\\n        \\\"message\\\": \\\"Hello world!\\\",\\n        \\\"ios\\\": {\\n          \\\"message\\\": \\\"Hello iOS!\\\",\\n          \\\"badge\\\": 5,\\n          \\\"title\\\": \\\"test\\\"\\n        },\\n        \\\"title\\\": \\\"Tester\\\"\\n      }\\n    },\\n    \\\"status\\\": \\\"open\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n**Note:** You can use the `uuid` field to [check the status of a notification](doc:push-sending-push#section-checking-the-status-of-a-push).\n\n## Sending a push to Ionic User ID's\n\nIf you would prefer to use registered Ionic User ID's, rather than sending a list of the device tokens you want to target, you may replace the `tokens` field with a `user_ids` field, as below (Make sure you've [set them up](doc:push-usage#section-integrating-with-ionic-user) first):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"user_ids\\\": [\\\"Your\\\", \\\"user\\\", \\\"ids\\\"],\\n  \\\"notification\\\": {\\n    \\\"message\\\":\\\"Hello World!\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIf you want to send notifications using the ids from the Oauth providers of your users or your own custom external_ids that you've assigned them, you may specify them with a `providername_ids` field, as seen below (Make sure you've [set them up](doc:social-providers) first):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"facebook_ids\\\": [\\\"Your\\\", \\\"facebook\\\", \\\"ids\\\"],\\n  \\\"linkedin_ids\\\": [\\\"Your\\\", \\\"linkedin\\\", \\\"ids\\\"],\\n  \\\"google_ids\\\": [\\\"Your\\\", \\\"google\\\", \\\"ids\\\"],\\n  \\\"twitter_ids\\\": [\\\"Your\\\", \\\"twitter\\\", \\\"ids\\\"],\\n  \\\"instagram_ids\\\": [\\\"Your\\\", \\\"instagram\\\", \\\"ids\\\"],\\n  \\\"github_ids\\\": [\\\"Your\\\", \\\"github\\\", \\\"ids\\\"],\\n  \\\"external_ids\\\": [\\\"Your\\\", \\\"external\\\", \\\"ids\\\"],\\n  \\\"notification\\\": {\\n    \\\"message\\\": \\\"Hello World!\\\" \\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYou can also specify a notification by your `Ionic Auth users` email addresses:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"emails\\\": [\\\"user1:::at:::ionic.io\\\", \\\"user2@email.com\\\"],\\n  \\\"notification\\\": {\\n    \\\"message\\\": \\\"Hello World!\\\" \\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Scheduling a push for later delivery\n\nIn addition to the `tokens`, `user_ids`, and `notification` fields in your POST data, you may also send an [RFC 3339 format](https://tools.ietf.org/html/rfc3339#section-5.8) timestamp with zero offset along, and your notification will be stored for later sending.  To do this, simply specify the `scheduled` field as below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"tokens\\\": [\\\"Your\\\", \\\"device\\\", \\\"tokens\\\"],\\n  \\\"scheduled\\\": \\\"2018-02-25T14:36:42+00:00\\\",\\n  \\\"notification\\\": {\\n    \\\"message\\\":\\\"Hello World!\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Adding custom data to your notifications\n\nYou can add custom key/value data to your notifications with the `payload` key as follows.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"title\\\": \\\"Hi\\\",\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"ios\\\": {\\n      \\\"message\\\": \\\"Hello iOS!\\\",\\n      \\\"payload\\\": {\\n      \\t\\\"baz\\\": \\\"boo\\\"\\n    \\t}\\n    },\\n    \\\"android\\\": {\\n      \\\"message\\\": \\\"Hello Android!\\\",\\n      \\\"payload\\\": {\\n      \\t\\\"foo\\\": \\\"bar\\\"\\n    \\t}\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nData set in this way will be available inside your app for handling (i.e. with an `onNotification` function).\n\n## PhoneGap Push Plugin Options\n\nThe push plugin supports a number of [extra options](https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/PAYLOAD.md), especially for Android devices. Most of these options are supported through the use of specific keys sent directly with APNs or GCM -- These options can be set using the `data` property of the `ios` or `android` options.\n\nFor example, to set this lovely image of [ionitron](https://pbs.twimg.com/profile_images/617058765167329280/9BkeDJlV.png) as the image for your Android notification, you could set the `image` property of the `android` options:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"title\\\": \\\"Hi\\\",\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"android\\\": {\\n      \\\"data\\\": {\\n        \\\"image\\\": \\\"https://pbs.twimg.com/profile_images/617058765167329280/9BkeDJlV.png\\\"\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Customizing your notification appearance\n\nIn addition to `\"title\"` and `\"message\"`, you can specify several fields to alter the appearance and behavior of your push.  Check them out below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"title\\\": \\\"Hi\\\",\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"sound\\\": \\\"sound.wav\\\",\\n    \\\"ios\\\": {\\n      \\\"message\\\": \\\"Hello iOS!\\\",\\n      \\\"sound\\\": \\\"ios-sound.wav\\\",\\n      \\\"badge\\\": 3,\\n    },\\n    \\\"android\\\": {\\n      \\\"message\\\": \\\"Hello Android!\\\",\\n      \\\"sound\\\": \\\"android-sound.wav\\\",\\n      \\\"icon\\\": \\\"ionitron.png\\\",\\n      \\\"icon_color\\\": \\\"#rrggbb\\\",\\n      \\\"collapse_key\\\": \\\"foo\\\",\\n      \\\"tag\\\": \\\"bar\\\"\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nLet's take a closer look at them:\n\n* `\"sound\"`: the name of a sound resource to use for the notification.  If not present, the default notification sound will be used.\n\n**iOS Fields:**\n\n* `\"badge\"`: the badge number to set on the application's icon.\n\n**Android Fields:**\n\n* `\"icon\"`: The icon to use for your push notification.\n* `\"icon_color\"`: The color to display your icon in the notification drawer.  Must be in hex format `#rrggbb`.\n* `\"collapse_key\"`: This parameter identifies a group of messages (e.g., with collapse_key: \"Updates Available\") that can be collapsed, so that only the last message gets sent when delivery can be resumed.\n* `\"tag\"`: Indicates whether each notification message results in a new entry on the notification center. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one.\n\n## Templating your push content\n\nCheck out the example push notification body below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"user_ids\\\": [\\\"some-user-id\\\"],\\n  \\\"profile\\\": \\\"your-security-profile\\\",\\n  \\\"notification\\\": {\\n    \\\"title\\\": \\\"Testing...\\\",\\n    \\\"message\\\": \\\"Hello user!\\\",\\n    \\\"ios\\\": {\\n      \\\"message\\\": \\\"Hello {{name}}\\\",\\n      \\\"badge\\\": 1\\n    },\\n    \\\"template_defaults\\\": {\\n      \\\"name\\\": \\\"Tim\\\"\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYou may notice the `{{name}}` field under the `ios` section.  When sending a notification to `user_ids` as opposed to raw device tokens, you can fill in the notification's message with any data you may have stored on the underlying Ionic User.  Simply use the `template_defaults` section to specify the value to fall back on in the case that it is not present.\n\n## Setting your notification's priority\n\nYou can customize the delivery priority of a notification as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"ios\\\": {\\n      \\\"priority\\\": 10\\n    },\\n    \\\"android\\\": {\\n      \\\"priority\\\" \\\"high\\\"\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nOn iOS, specify `priority` as`5` or `10`.  `10` will attempt to deliver the notification immediately (or immediately after it was scheduled.  `5` will attempt to deliver the notification at a time which conserves device battery power.\n\nOn Android, specify `priority` as`high` or `normal`.  `high` will attempt to deliver the notification immediately (or immediately after it was scheduled.  `notmal` will attempt to deliver the notification at a time which conserves device battery power.\n\n## Giving your notifications a TTL (Time to Live)\n\nYou can specify TTL's on your notifications, creating times after which GCM and APN will no longer attempt to send them.  This is accomplished as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"ios\\\": {\\n      \\\"expire\\\": \\\"2018-02-25T14:36:42+00:00\\\"\\n    },\\n    \\\"android\\\": {\\n      \\\"time_to_live\\\" 1234\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nFor iOS, use the `expire` keyword, which is an [RFC 3339 format](https://tools.ietf.org/html/rfc3339#section-5.8) timestamp after which APN will no longer attempt to deliver your notification.\n\nFor Android, use the `time_to_live` keyword, which is an integer second count until your notification is no longer valid.\n\n## Delaying notifications to idle devices\n\nOn Android only, you can tell GCM to delay the delivery of a notification until the target device is active:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"message\\\": \\\"Hello world!\\\",\\n    \\\"android\\\": {\\n      \\\"delay_while_idle\\\" true\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Sending background notifications\n\nYou may wish to send silent pushes, which will silently wake up your application to do some sort of processing in the background.  Tis is accomplished with the `content_available` key to `1` as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"notification\\\": {\\n    \\\"payload\\\": {\\n    \\t\\\"foo\\\": \\\"bar\\\"\\n  \\t},\\n    \\\"ios\\\": {\\n      \\\"content_available\\\": 1\\n    },\\n    \\\"android\\\": {\\n    \\t\\\"content_available\\\": 1\\n  \\t}\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThis will wake the app when the notification is received and allow your `onNotification` function to run, using the data you specify in the `payload` key.  \n\n## Checking the status of a push\n\nTo check on the delivery status of a given notification, you'll be making a GET request to the following endpoint:\n\n`https://api.ionic.io/push/notifications/<your-notification-uuid>/messages`\n\nwith the following headers:\n\n```javascript\nContent-Type: application/json\nAuthorization: Bearer <your-authentication-token>\n```\n\nHere's an example response you could see:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"meta\\\": {\\n    \\\"request_id\\\": \\\"your-request-id\\\",\\n    \\\"version\\\": \\\"2.0.0-beta.0\\\",\\n    \\\"status\\\": 200\\n  },\\n  \\\"data\\\": [\\n    {\\n      \\\"user_id\\\": null,\\n      \\\"uuid\\\": \\\"message-uuid\\\",\\n      \\\"token\\\": {\\n        \\\"id\\\": \\\"token-id\\\",\\n        \\\"type\\\": \\\"ios\\\",\\n        \\\"token\\\": \\\"the-device-token\\\",\\n        \\\"valid\\\": true,\\n        \\\"app_id\\\": \\\"your-app-id\\\",\\n        \\\"created\\\": \\\"2016-02-25T13:53:34.394390+00:00\\\",\\n        \\\"invalidated\\\": null\\n      },\\n      \\\"status\\\": \\\"error\\\",\\n      \\\"created\\\": \\\"2016-02-25T13:54:20.511749+00:00\\\",\\n      \\\"notification\\\": \\\"your-notification-uuid\\\",\\n      \\\"error\\\": \\\"NO_CREDENTIAL\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAs you can see, the above notification failed to deliver because there was no security credential specified.  You can read about all error codes [here](doc:push-error-codes). \n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"All Done!\",\n  \"body\": \"Congrats!  You're now a push notification wizard!\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Responses\"\n}\n[/block]\n## Notification State\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`PENDING`\",\n    \"0-1\": \"The notification is pending processing. It should be rare to see this state.\",\n    \"1-0\": \"`ENQUEUED`\",\n    \"1-1\": \"The notification has entered processing and may or may not yet be completed.\",\n    \"2-0\": \"`SCHEDULED`\",\n    \"2-1\": \"The notification has been accepted and scheduled to send at a future date.\",\n    \"3-0\": \"`FAILED`\",\n    \"3-1\": \"We were unable to process the notification and have marked it as a failure.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n## Notification Status\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`OPEN`\",\n    \"0-1\": \"The notification is available for edits. Notifications are typically only in this status  when they are scheduled.\",\n    \"1-0\": \"`LOCKED`\",\n    \"1-1\": \"The notification can no longer be modified.\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n## Message Status\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`SENT`\",\n    \"0-1\": \"We have delivered the message to the appropriate device provider (APNs, GCM, etc) and did not encounter any immediate errors. This does **NOT** indicate a message was received on the device.\",\n    \"1-0\": \"`QUEUED`\",\n    \"1-1\": \"The message has entered the delivery queue and should be sent out shortly.\",\n    \"2-0\": \"`PENDING`\",\n    \"2-1\": \"The message has been generated, but has not yet entered the delivery queue.\",\n    \"3-0\": \"`ERROR`\",\n    \"3-1\": \"The message was unable to be sent or rejected by the provider. See the [Error Codes](doc:push-error-codes) doc for more information.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","excerpt":"","slug":"push-sending-push","type":"basic","title":"Sending Push"}
[block:api-header] { "type": "basic", "title": "Contents" } [/block] ## General * [Notifications vs. Messages](doc:push-sending-push#section-notifications-vs-messages) ## Requests * [Basic API usage](doc:push-sending-push#section-basic-api-usage) * [Sending via user ID's](push-sending-push#section-sending-a-push-to-ionic-user-id-s) * [Scheduling a push for later delivery](doc:push-sending-push#section-scheduling-a-push-for-later-delivery) * [Adding custom data to notifications](push-sending-push#section-adding-custom-data-to-your-notifications) * [Customizing notification appearance](push-sending-push#section-customizing-your-notification-appearance) * [PhoneGap Push Plugin Options](push-sending-push#section-phonegap-push-plugin-options) * [Templating push content](doc:push-sending-push#section-templating-your-push-content) * [Setting delivery priority](push-sending-push#section-setting-your-notification-s-priority) * [Setting notification time to live](push-sending-push#section-giving-your-notifications-a-ttl-time-to-live-) * [Delaying notifications to idle devices](push-sending-push#section-delaying-notifications-to-idle-devices) * [Sending background notifications](push-sending-push#section-sending-background-notifications) * [Checking the status of a notification](doc:push-sending-push#section-checking-the-status-of-a-push) ## Responses * [Notification State](push-sending-push#section-notification-state) * [Notification Status](push-sending-push#section-notification-status) * [Message Status](push-sending-push#section-message-status) [block:api-header] { "type": "basic", "title": "" } [/block] Assuming you have registered some devices and uploaded the relevant credentials to a [security profile](doc:security-profiles), you're ready to start sending some push notifications! There are two main ways of accomplishing this; through the REST API and using the [ionic.io](https://apps.ionic.io/) dashboard. [block:image] { "images": [ { "image": [ "https://files.readme.io/iDeg3xM9Qfa2DBH3mFPu_send-push-diagram.png", "send-push-diagram.png", "2075", "772", "#4181b1", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "General" } [/block] ## Notifications vs. Messages Ionic.io push is composed of two main concepts, **Notifications** and **Messages**. We define them like so: * **Notifications**: The individual push notifications you create and send via the API or the ionic.io dashboard. These may have any number of recipients (via user ID's, device tokens, or queries). * **Messages**: A recipient of a notification. For instance, a push you send to 10 device tokens will be comprised of 10 messages. These track their delivery status independently, giving you granular detail on their delivery. [block:api-header] { "type": "basic", "title": "Requests" } [/block] ## Basic API usage Ionic.io has an API endpoint which you can use to send push notifications from your backend server (or with a **curl** for testing). You can send a push notification by making a **POST** to `https://api.ionic.io/push/notifications` with the following headers. ```javascript Content-Type: application/json Authorization: Bearer <your-authentication-token> ``` (If you're unsure what to put for the authentication token, check out [the docs](doc:api-getting-started) here) The POST data should be a JSON object of the following format as well: [block:code] { "codes": [ { "code": "{\n \"tokens\": [\"your\", \"device\", \"tokens\"],\n \"profile\": \"my-security-profile\",\n \"notification\": {\n \"title\": \"Hi\",\n \"message\": \"Hello world!\",\n \"android\": {\n \"title\": \"Hey\",\n \"message\": \"Hello Android!\"\n },\n \"ios\": {\n \"title\": \"Howdy\",\n \"message\": \"Hello iOS!\"\n }\n }\n}", "language": "json" } ] } [/block] Let's take a look at the individual parts of that. * `"tokens"`: An array of the device tokens you wish to receive this notification. * `"profile"`: The name of the [security profile](doc:security-profiles) which contains the push credentials you wish to use for this notification. * `"notification"`: The actual notification object. As you can see, a default `title` and `message` text are specified, and can be overwritten for each platform individually. Here's an Angular example, sending the above notification: [block:code] { "codes": [ { "code": "// Define relevant info\nvar jwt = 'your-authorization-token';\nvar tokens = ['your', 'target', 'tokens'];\nvar profile = 'your-security-profile-name';\n\n// Build the request object\nvar req = {\n method: 'POST',\n url: 'https://api.ionic.io/push/notifications',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': 'Bearer ' + jwt\n },\n data: {\n \"tokens\": tokens,\n \"profile\": profile,\n \"notification\": {\n \"title\": \"Hi\",\n \"message\": \"Hello world!\",\n \"android\": {\n \"title\": \"Hey\",\n \"message\": \"Hello Android!\"\n },\n \"ios\": {\n \"title\": \"Howdy\",\n \"message\": \"Hello iOS!\"\n }\n }\n }\n};\n\n// Make the API call\n$http(req).success(function(resp){\n // Handle success\n console.log(\"Ionic Push: Push success\", resp);\n}).error(function(error){\n // Handle error \n console.log(\"Ionic Push: Push error\", error);\n});", "language": "javascript", "name": null } ] } [/block] And here's an example response you could get from the server: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"request_id\": \"your-request-id\",\n \"version\": \"2.0.0-beta.0\",\n \"status\": 201\n },\n \"data\": {\n \"uuid\": \"your-notification-uuid\",\n \"app_id\": \"your-app-id\",\n \"state\": \"enqueued\",\n \"created\": \"2016-02-29T16:24:41.927954+00:00\",\n \"config\": {\n \"tokens\": [\"your\", \"device\", \"tokens\"],\n \"profile\": \"your-security-profile\",\n \"notification\": {\n \"message\": \"Hello world!\",\n \"ios\": {\n \"message\": \"Hello iOS!\",\n \"badge\": 5,\n \"title\": \"test\"\n },\n \"title\": \"Tester\"\n }\n },\n \"status\": \"open\"\n }\n}", "language": "json" } ] } [/block] **Note:** You can use the `uuid` field to [check the status of a notification](doc:push-sending-push#section-checking-the-status-of-a-push). ## Sending a push to Ionic User ID's If you would prefer to use registered Ionic User ID's, rather than sending a list of the device tokens you want to target, you may replace the `tokens` field with a `user_ids` field, as below (Make sure you've [set them up](doc:push-usage#section-integrating-with-ionic-user) first): [block:code] { "codes": [ { "code": "{\n \"user_ids\": [\"Your\", \"user\", \"ids\"],\n \"notification\": {\n \"message\":\"Hello World!\"\n }\n}", "language": "json" } ] } [/block] If you want to send notifications using the ids from the Oauth providers of your users or your own custom external_ids that you've assigned them, you may specify them with a `providername_ids` field, as seen below (Make sure you've [set them up](doc:social-providers) first): [block:code] { "codes": [ { "code": "{\n\t\"facebook_ids\": [\"Your\", \"facebook\", \"ids\"],\n \"linkedin_ids\": [\"Your\", \"linkedin\", \"ids\"],\n \"google_ids\": [\"Your\", \"google\", \"ids\"],\n \"twitter_ids\": [\"Your\", \"twitter\", \"ids\"],\n \"instagram_ids\": [\"Your\", \"instagram\", \"ids\"],\n \"github_ids\": [\"Your\", \"github\", \"ids\"],\n \"external_ids\": [\"Your\", \"external\", \"ids\"],\n \"notification\": {\n \"message\": \"Hello World!\" \n }\n}", "language": "json" } ] } [/block] You can also specify a notification by your `Ionic Auth users` email addresses: [block:code] { "codes": [ { "code": "{\n \"emails\": [\"user1@ionic.io\", \"user2@email.com\"],\n \"notification\": {\n \"message\": \"Hello World!\" \n }\n}", "language": "json" } ] } [/block] ## Scheduling a push for later delivery In addition to the `tokens`, `user_ids`, and `notification` fields in your POST data, you may also send an [RFC 3339 format](https://tools.ietf.org/html/rfc3339#section-5.8) timestamp with zero offset along, and your notification will be stored for later sending. To do this, simply specify the `scheduled` field as below: [block:code] { "codes": [ { "code": "{\n \"tokens\": [\"Your\", \"device\", \"tokens\"],\n \"scheduled\": \"2018-02-25T14:36:42+00:00\",\n \"notification\": {\n \"message\":\"Hello World!\"\n }\n}", "language": "json" } ] } [/block] ## Adding custom data to your notifications You can add custom key/value data to your notifications with the `payload` key as follows. [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"title\": \"Hi\",\n \"message\": \"Hello world!\",\n \"ios\": {\n \"message\": \"Hello iOS!\",\n \"payload\": {\n \t\"baz\": \"boo\"\n \t}\n },\n \"android\": {\n \"message\": \"Hello Android!\",\n \"payload\": {\n \t\"foo\": \"bar\"\n \t}\n }\n }\n}", "language": "json" } ] } [/block] Data set in this way will be available inside your app for handling (i.e. with an `onNotification` function). ## PhoneGap Push Plugin Options The push plugin supports a number of [extra options](https://github.com/phonegap/phonegap-plugin-push/blob/master/docs/PAYLOAD.md), especially for Android devices. Most of these options are supported through the use of specific keys sent directly with APNs or GCM -- These options can be set using the `data` property of the `ios` or `android` options. For example, to set this lovely image of [ionitron](https://pbs.twimg.com/profile_images/617058765167329280/9BkeDJlV.png) as the image for your Android notification, you could set the `image` property of the `android` options: [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"title\": \"Hi\",\n \"message\": \"Hello world!\",\n \"android\": {\n \"data\": {\n \"image\": \"https://pbs.twimg.com/profile_images/617058765167329280/9BkeDJlV.png\"\n }\n }\n }\n}", "language": "json" } ] } [/block] ## Customizing your notification appearance In addition to `"title"` and `"message"`, you can specify several fields to alter the appearance and behavior of your push. Check them out below: [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"title\": \"Hi\",\n \"message\": \"Hello world!\",\n \"sound\": \"sound.wav\",\n \"ios\": {\n \"message\": \"Hello iOS!\",\n \"sound\": \"ios-sound.wav\",\n \"badge\": 3,\n },\n \"android\": {\n \"message\": \"Hello Android!\",\n \"sound\": \"android-sound.wav\",\n \"icon\": \"ionitron.png\",\n \"icon_color\": \"#rrggbb\",\n \"collapse_key\": \"foo\",\n \"tag\": \"bar\"\n }\n }\n}", "language": "json" } ] } [/block] Let's take a closer look at them: * `"sound"`: the name of a sound resource to use for the notification. If not present, the default notification sound will be used. **iOS Fields:** * `"badge"`: the badge number to set on the application's icon. **Android Fields:** * `"icon"`: The icon to use for your push notification. * `"icon_color"`: The color to display your icon in the notification drawer. Must be in hex format `#rrggbb`. * `"collapse_key"`: This parameter identifies a group of messages (e.g., with collapse_key: "Updates Available") that can be collapsed, so that only the last message gets sent when delivery can be resumed. * `"tag"`: Indicates whether each notification message results in a new entry on the notification center. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one. ## Templating your push content Check out the example push notification body below: [block:code] { "codes": [ { "code": "{\n \"user_ids\": [\"some-user-id\"],\n \"profile\": \"your-security-profile\",\n \"notification\": {\n \"title\": \"Testing...\",\n \"message\": \"Hello user!\",\n \"ios\": {\n \"message\": \"Hello {{name}}\",\n \"badge\": 1\n },\n \"template_defaults\": {\n \"name\": \"Tim\"\n }\n }\n}", "language": "json" } ] } [/block] You may notice the `{{name}}` field under the `ios` section. When sending a notification to `user_ids` as opposed to raw device tokens, you can fill in the notification's message with any data you may have stored on the underlying Ionic User. Simply use the `template_defaults` section to specify the value to fall back on in the case that it is not present. ## Setting your notification's priority You can customize the delivery priority of a notification as follows: [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"message\": \"Hello world!\",\n \"ios\": {\n \"priority\": 10\n },\n \"android\": {\n \"priority\" \"high\"\n }\n }\n}", "language": "json" } ] } [/block] On iOS, specify `priority` as`5` or `10`. `10` will attempt to deliver the notification immediately (or immediately after it was scheduled. `5` will attempt to deliver the notification at a time which conserves device battery power. On Android, specify `priority` as`high` or `normal`. `high` will attempt to deliver the notification immediately (or immediately after it was scheduled. `notmal` will attempt to deliver the notification at a time which conserves device battery power. ## Giving your notifications a TTL (Time to Live) You can specify TTL's on your notifications, creating times after which GCM and APN will no longer attempt to send them. This is accomplished as follows: [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"message\": \"Hello world!\",\n \"ios\": {\n \"expire\": \"2018-02-25T14:36:42+00:00\"\n },\n \"android\": {\n \"time_to_live\" 1234\n }\n }\n}", "language": "json" } ] } [/block] For iOS, use the `expire` keyword, which is an [RFC 3339 format](https://tools.ietf.org/html/rfc3339#section-5.8) timestamp after which APN will no longer attempt to deliver your notification. For Android, use the `time_to_live` keyword, which is an integer second count until your notification is no longer valid. ## Delaying notifications to idle devices On Android only, you can tell GCM to delay the delivery of a notification until the target device is active: [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"message\": \"Hello world!\",\n \"android\": {\n \"delay_while_idle\" true\n }\n }\n}", "language": "json" } ] } [/block] ## Sending background notifications You may wish to send silent pushes, which will silently wake up your application to do some sort of processing in the background. Tis is accomplished with the `content_available` key to `1` as follows: [block:code] { "codes": [ { "code": "{\n \"notification\": {\n \"payload\": {\n \t\"foo\": \"bar\"\n \t},\n \"ios\": {\n \"content_available\": 1\n },\n \"android\": {\n \t\"content_available\": 1\n \t}\n }\n}", "language": "json" } ] } [/block] This will wake the app when the notification is received and allow your `onNotification` function to run, using the data you specify in the `payload` key. ## Checking the status of a push To check on the delivery status of a given notification, you'll be making a GET request to the following endpoint: `https://api.ionic.io/push/notifications/<your-notification-uuid>/messages` with the following headers: ```javascript Content-Type: application/json Authorization: Bearer <your-authentication-token> ``` Here's an example response you could see: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"request_id\": \"your-request-id\",\n \"version\": \"2.0.0-beta.0\",\n \"status\": 200\n },\n \"data\": [\n {\n \"user_id\": null,\n \"uuid\": \"message-uuid\",\n \"token\": {\n \"id\": \"token-id\",\n \"type\": \"ios\",\n \"token\": \"the-device-token\",\n \"valid\": true,\n \"app_id\": \"your-app-id\",\n \"created\": \"2016-02-25T13:53:34.394390+00:00\",\n \"invalidated\": null\n },\n \"status\": \"error\",\n \"created\": \"2016-02-25T13:54:20.511749+00:00\",\n \"notification\": \"your-notification-uuid\",\n \"error\": \"NO_CREDENTIAL\"\n }\n ]\n}", "language": "json" } ] } [/block] As you can see, the above notification failed to deliver because there was no security credential specified. You can read about all error codes [here](doc:push-error-codes). [block:callout] { "type": "success", "title": "All Done!", "body": "Congrats! You're now a push notification wizard!" } [/block] [block:api-header] { "type": "basic", "title": "Responses" } [/block] ## Notification State [block:parameters] { "data": { "0-0": "`PENDING`", "0-1": "The notification is pending processing. It should be rare to see this state.", "1-0": "`ENQUEUED`", "1-1": "The notification has entered processing and may or may not yet be completed.", "2-0": "`SCHEDULED`", "2-1": "The notification has been accepted and scheduled to send at a future date.", "3-0": "`FAILED`", "3-1": "We were unable to process the notification and have marked it as a failure." }, "cols": 2, "rows": 4 } [/block] ## Notification Status [block:parameters] { "data": { "0-0": "`OPEN`", "0-1": "The notification is available for edits. Notifications are typically only in this status when they are scheduled.", "1-0": "`LOCKED`", "1-1": "The notification can no longer be modified." }, "cols": 2, "rows": 2 } [/block] ## Message Status [block:parameters] { "data": { "0-0": "`SENT`", "0-1": "We have delivered the message to the appropriate device provider (APNs, GCM, etc) and did not encounter any immediate errors. This does **NOT** indicate a message was received on the device.", "1-0": "`QUEUED`", "1-1": "The message has entered the delivery queue and should be sent out shortly.", "2-0": "`PENDING`", "2-1": "The message has been generated, but has not yet entered the delivery queue.", "3-0": "`ERROR`", "3-1": "The message was unable to be sent or rejected by the provider. See the [Error Codes](doc:push-error-codes) doc for more information." }, "cols": 2, "rows": 4 } [/block]