Push
Use this API to register your subscribers' devices, send a push notification to one subscriber from your backend, and record when someone opens a notification. Campaigns and automations use the same devices.
All endpoints live under https://app.bentonow.com/api/v1. Every request needs your site_uuid in the query string. Authenticate with HTTP Basic auth, using your publishable key as the username and your secret key as the password.
403 with a message that says what to change.New to push? Start with the setup guides: push overview, web push, iOS with APNs, and Android with Firebase.
Available Endpoints
- POST
/push/devicesRegister A Device
Add or update a subscriber device and its permission.
- DELETE
/push/devicesRemove A Device
Stop sending to a device, for example on logout.
- POST
/push/sendSend A Push
Send a push notification to one subscriber.
- POST
/push/opensReport An Open
Record a tap on a notification or one of its buttons.
- GET
/push/web/configWeb Push Config
Get the public keys a browser needs to subscribe.
- POST
/push/web/subscriptionsSubscribe A Browser
Save a browser subscription from your website.
- DELETE
/push/web/subscriptionsUnsubscribe A Browser
Remove a browser subscription from your website.
Register A Device
/v1/push/devicesCreates a device the first time and updates it after that, so repeat calls are safe. Call it whenever your app starts, gets a new token, or sees a permission change. A device receives pushes only while it is active and its permission is granted or provisional.
If the email or uuid is new to Bento, registering adds the subscriber. A visitor_id must belong to a subscriber already on this site.
Subscriber Selector
Send one of these. When you send more than one, visitor_id wins, then email, then uuid.
- Name
emailstring- Description
Subscriber email address. Adds the subscriber if they are new.
- Name
uuidstring- Description
Your stable ID for this person, up to 255 letters, numbers, and
_ . : -. Adds the subscriber if they are new. When you also send an email for a new subscriber, Bento stores this uuid on them.
- Name
visitor_idstring- Description
Bento subscriber ID, either the prefixed ID or the number. Must already exist on this site.
Required Attributes
- Name
credential_idinteger- Description
The credential ID Bento shows after you save an APNs, FCM, or web push credential.
- Name
installation_idstring- Description
A stable ID your app creates once per install and stores. Up to 255 characters. Not used for web devices.
- Name
tokenstring- Description
The APNs device token as a hex string, or the FCM registration token. Not used for web devices.
- Name
platformstring- Description
One of
ios,android, orweb.
- Name
permissionstring- Description
One of
granted,provisional,denied,not_determined, orunknown.
Optional Attributes
- Name
app_versionstring- Description
Your app version, such as
2.4.0.
- Name
os_versionstring- Description
Operating system version, such as
18.1.
- Name
localestring- Description
Device locale, such as
en-US.
- Name
timezonestring- Description
IANA time zone, such as
America/New_York.
- Name
last_seen_atstring- Description
ISO 8601 time the app was last used. Defaults to now and can't be in the future. Bento uses the most recent value to pick a device when sending.
Web Devices
To register a browser from your server, send platform as web with a subscription instead of installation_id and token. Bento identifies the device by its endpoint. If you use bento-push.js on your website, it registers browsers for you through Web Subscriptions.
- Name
subscription.endpointstring- Description
The push service URL from the browser's
PushSubscription. Must be an https endpoint on a known push service.
- Name
subscription.keys.p256dhstring- Description
The subscription's P-256 public key, base64url encoded.
- Name
subscription.keys.authstring- Description
The subscription's 16-byte auth secret, base64url encoded.
- Name
browserstring- Description
Optional browser name, up to 64 characters.
- Name
osstring- Description
Optional operating system name, up to 64 characters.
- Name
originstring- Description
Optional website origin, such as
https://example.com.
Response
Returns the device and whether this call created it.
- Name
device.idinteger- Description
Bento device ID.
- Name
device.statusstring- Description
One of
active,invalid, orrevoked.
- Name
device.permissionstring- Description
The permission you last sent.
- Name
device.eligibleboolean- Description
truewhen the device can receive pushes right now.
- Name
device.providerstring- Description
One of
apns,fcm, orweb, from the credential.
- Name
createdboolean- Description
truewhen this call added the device,falsewhen it updated one.
The device also includes bento_visitor_id, credential_id, platform, installation_id, the optional fields you sent, last_seen_at, created_at, and updated_at.
Errors
Errors return a JSON body with an error message.
| Status | Error | What to do |
|---|---|---|
422 | Add credential_id, installation_id, token, platform, and permission to the request. | Lists only the fields that are missing. |
422 | Add subscription with endpoint and keys to the request. | Web devices need a subscription with an endpoint. |
422 | Add a visitor_id, uuid, or email so Bento knows whose device this is. | Send a subscriber selector. |
422 | Check the subscriber's email address or uuid. | The email or uuid isn't valid, or the visitor_id isn't a subscriber on this site. |
422 | Validation failed | A value isn't allowed, such as an unknown permission, a future last_seen_at, or web subscription keys that don't decode. |
404 | Not found. | The credential_id doesn't belong to this site. |
503 | Push is temporarily unavailable. Try again shortly. | Retry later. |
Remove A Device
/v1/push/devicesStops sending to a device. Call it when someone logs out so they stop getting pushes meant for that account. Send the attributes in the query string or the JSON body.
Required Attributes
- Name
credential_idinteger- Description
The credential the device was registered with.
- Name
installation_idstring- Description
The installation ID you registered. For a web device, send
endpointinstead.
- Name
endpointstring- Description
Web devices only: the subscription endpoint, used when
installation_idis missing.
Response
Returns 204 No Content with an empty body. Removing a device that was already removed also returns 204.
| Status | Error | What to do |
|---|---|---|
422 | Add credential_id to the request. | Send the credential ID. |
422 | Add installation_id (or endpoint for a web device) to the request. | Send one of them. |
404 | Not found. | No device matches that credential and installation ID or endpoint. |
Send A Push
/v1/push/sendSends a push notification to one subscriber, such as "your order shipped". By default Bento sends to the device they used most recently. The subscriber must already be in Bento.
Text fields support Liquid personalization with the subscriber's data, as in the example. Only Liquid's standard filters are available, and each text field can be up to 4,096 characters before rendering.
Subscriber Selector
Send one of visitor_id, uuid, or email. When you send more than one, visitor_id wins, then uuid, then email.
Required Attributes
- Name
titlestring- Description
Notification title, up to 200 characters after personalization.
- Name
bodystring- Description
Notification body, up to 2,000 characters after personalization.
Optional Attributes
- Name
subtitlestring- Description
Shown under the title on iOS. Up to 200 characters.
- Name
urlstring- Description
Deep link or web page to open on tap. Up to 2,048 characters.
javascript:,data:, andvbscript:URLs are rejected.
- Name
image_urlstring- Description
An
httpsimage URL, up to 2,048 characters.
- Name
actionsarray- Description
Up to 3 buttons. Each has an
id(1 to 64 letters, numbers,-or_, unique in the list), atitle(up to 40 characters), and an optionalurl.
- Name
dataobject- Description
Custom key-value data delivered with the notification. Up to 50 keys with text values. Keys can't start with
bento_,google, orgcm, and can't beaps,notification,data,message,token,topic,condition,android,apns,webpush,fcm_options,from,message_type, orcollapse_key.
- Name
collapse_keystring- Description
Groups notifications so a newer one replaces an older one. 1 to 64 letters, numbers, and
. _ : -.
- Name
ttl_secondsinteger- Description
How long the push service keeps trying to deliver. Defaults to
86400(one day). Values outside60to2419200(28 days) are moved to the nearest limit.
- Name
prioritystring- Description
high(default) ornormal.
- Name
device_targetstring- Description
last_used(default) sends to the subscriber's most recently used device.allsends to up to 100 of their most recently used devices.
- Name
platform_overridesobject- Description
Per-platform changes keyed by
ios,android, orweb. All three accepttitle,body,image_url, andurl. iOS also acceptssubtitle,sound,badge,interruption_level,relevance_score,thread_id,category, andmutable_content. Android also acceptschannel_id,small_icon,color,sound,priority,visibility,tag,sticky, andstyle(big_pictureorbig_text). Web also acceptsicon,badge,require_interaction, andactions.
- Name
idempotency_keystring- Description
Makes retries safe. Up to 200 letters, numbers, and
_ . : -. A repeat request with a key already used on this site returnsduplicateand sends nothing.
Response
Returns 202 Accepted when the push is queued, or 200 OK when nothing new was sent.
- Name
send.statusstring- Description
queuedwhen deliveries were created,duplicatewhen theidempotency_keywas already used, orskippedwhen nothing could be sent.
- Name
send.source_keystring- Description
The key Bento used to deduplicate this send.
- Name
send.delivery_idsarray- Description
One ID per device the push was queued for. Empty when skipped, and left out for duplicates.
- Name
send.skipped_reasonstring- Description
no_eligible_deviceswhen the subscriber has no device that can receive pushes.
Errors
Content checks return 422 with an error message. When a field breaks a limit, the response also includes details, keyed by the field path.
| Status | Error | What to do |
|---|---|---|
422 | Add title and body to the request. | Lists only the fields that are missing. |
422 | idempotency_key can use letters, numbers, and _ . : - (up to 200 characters). | Shorten or simplify the key. |
422 | Check the push content: data must be valid JSON. | The message after the colon names the problem, such as a Liquid error or a filter that isn't available. |
422 | Title and body must not be blank after personalization. | Add fallback text, for example with Liquid's default filter. |
422 | Validation failed | See details for each field and its limit. |
404 | Subscriber not found. Add them to Bento before sending them a push. | Add the subscriber first, or check the selector. |
403 | Your plan doesn't include Bento Chat. Add Chat to your plan in Bento to use it. | Add Bento Chat to your plan. |
403 | Your account needs approval before you can use Bento Chat. Request approval in Bento to continue. | Request account approval. |
503 | Push is temporarily unavailable. Try again shortly. | Retry with the same idempotency_key. |
Report An Open
/v1/push/opensRecords that someone tapped a notification and adds a $push_opened event to the subscriber. Read bento_open_token from the notification data and send it here.
This endpoint works with only site_uuid in the query string, so your app or service worker can call it directly without your secret key. The open token proves which notification was opened. If you send API key credentials, Bento checks them as usual.
Required Attributes
- Name
open_tokenstring- Description
The
bento_open_tokenvalue from the notification data.
Optional Attributes
- Name
opened_atstring- Description
ISO 8601 time of the tap. Bento uses the current time when it's missing or outside the time between sending and now.
- Name
action_idstring- Description
The
idof the button that was tapped, up to 64 characters. An ID that wasn't on the notification is recorded as a tap on the notification itself.
Response
Returns whether this was the first open of the notification. Later taps return false and don't add another event.
- Name
open.first_openboolean- Description
truethe first time this notification is opened.
| Status | Error | What to do |
|---|---|---|
422 | Add open_token to the request. | Send the token from the notification data. |
422 | action_id must be text of 64 characters or fewer. | Send the button's id. |
404 | Not found. | The token isn't valid for this site, or the site_uuid is wrong. |
Web Push Config
/v1/push/web/configReturns the public keys a browser needs to call PushManager.subscribe(). These keys aren't secret, so this endpoint needs only site_uuid. bento-push.js calls it for you.
Response
- Name
webarray- Description
One entry per web push credential. The credential made for the requesting page's origin comes first.
- Name
web[].credential_idinteger- Description
Send this as
credential_idwhen subscribing.
- Name
web[].bundle_idstring- Description
The website origin the credential was made for, or
webfor any origin.
- Name
web[].public_keystring- Description
The VAPID public key to pass as
applicationServerKey.
- Name
web[].statusstring- Description
Credential status, such as
valid.
Web Subscriptions
/v1/push/web/subscriptionsSaves or removes a browser subscription from your website. bento-push.js calls these endpoints for you, so most sites never call them directly.
These requests need only site_uuid in the query string, and must come from your website: the browser's Origin has to match your site's URL or a domain you've allowed for tracking. Other origins get 403 with "Push subscriptions must come from your website."
Subscribe Attributes
- Name
uuidstring- Description
Required. The Bento.js visitor uuid for this browser. The visitor must already exist, so load Bento.js on the page first.
- Name
credential_idinteger- Description
Required. A
credential_idfrom the web push config.
- Name
subscriptionobject- Description
Required. The browser's
PushSubscriptionwithendpointandkeys.p256dhandkeys.auth.
- Name
permissionstring- Description
Optional. Defaults to
granted.
- Name
browser, os, locale, timezonestring- Description
Optional details shown on the device.
The response returns device with id, platform, status, permission, and eligible, plus created. If the visitor uuid isn't found, the response is 422 with "Load Bento.js on this page before subscribing to push."
Unsubscribe
Send DELETE to the same path with credential_id and the subscription endpoint. Bento responds with 204 No Content.
Notification Data
Your app can read these keys from the notification data (userInfo on iOS, data on Android, the push payload on web). Custom data you send arrives alongside them.
| Key | When it is sent | What to do with it |
|---|---|---|
bento_open_token | Always | Send it to Report An Open when the notification is tapped. |
bento_url | When the push has a url | Open the deep link or web page. |
bento_campaign_id | With campaign pushes | Optional. Use it for your own analytics. |
bento_image_url | iOS and Android, when the push has an image | On iOS, download it in a Notification Service Extension and attach it. |
bento_actions | iOS and Android, when the push has buttons | A JSON string of up to 3 buttons, each with id, title, and optional url. |
bento_subtitle | Android, when the push has a subtitle | FCM has no subtitle field. Show it as the notification's sub text. |
bento_style | Android, when the Android override sets style to big_text | Show the full body with BigTextStyle. |
Web pushes carry the image and buttons in the notification itself, and bento-sw.js shows them for you.
Events
Bento records these events on the subscriber. Use them in segments and automations, for example to follow up with people who haven't turned on notifications.
| Event | When it happens |
|---|---|
$push_subscribed | A device can now receive pushes: it was registered with permission, permission was granted, or it moved to this subscriber. |
$push_unsubscribed | A device can no longer receive pushes: permission was denied, the device was removed, its token stopped working, its credential was deleted, or it moved to another subscriber. |
$push_opened | The subscriber tapped a notification. The event includes the delivery, the url, and the action_id when a button was tapped. |
Each event includes the device's platform, provider, credential_id, and installation_id, and a reason for subscribe and unsubscribe events.
Rate Limits
Push endpoints have these limits, counted per minute. Requests over a limit get 429 Too Many Requests.
| Endpoint | Limit |
|---|---|
POST /push/devices, DELETE /push/devices, and POST /push/send combined | 1,200 per IP address |
POST /push/opens | 300 per IP address and 10,000 per site |
/push/web/* | 60 per IP address and 6,000 per site |
POST and DELETE /push/web/subscriptions | 1,200 per site, on top of the /push/web/* limits |
| bento-push.js and bento-sw.js scripts | 300 per IP address |
The per-site limits read site_uuid from the query string, so always send it there.