Push

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.

Call the device and send endpoints from your own server. Never ship your Bento secret key in a mobile app, a browser, or any other client.
Push needs Bento Chat on your plan and an approved account. Without them, every endpoint answers 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


Register A Device

POST/v1/push/devices

Creates 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, or web.

  • Name
    permissionstring
    Description

    One of granted, provisional, denied, not_determined, or unknown.

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, or revoked.

  • Name
    device.permissionstring
    Description

    The permission you last sent.

  • Name
    device.eligibleboolean
    Description

    true when the device can receive pushes right now.

  • Name
    device.providerstring
    Description

    One of apns, fcm, or web, from the credential.

  • Name
    createdboolean
    Description

    true when this call added the device, false when 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.

StatusErrorWhat to do
422Add credential_id, installation_id, token, platform, and permission to the request.Lists only the fields that are missing.
422Add subscription with endpoint and keys to the request.Web devices need a subscription with an endpoint.
422Add a visitor_id, uuid, or email so Bento knows whose device this is.Send a subscriber selector.
422Check 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.
422Validation failedA value isn't allowed, such as an unknown permission, a future last_seen_at, or web subscription keys that don't decode.
404Not found.The credential_id doesn't belong to this site.
503Push is temporarily unavailable. Try again shortly.Retry later.

Remove A Device

DELETE/v1/push/devices

Stops 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 endpoint instead.

  • Name
    endpointstring
    Description

    Web devices only: the subscription endpoint, used when installation_id is missing.



Response

Returns 204 No Content with an empty body. Removing a device that was already removed also returns 204.

StatusErrorWhat to do
422Add credential_id to the request.Send the credential ID.
422Add installation_id (or endpoint for a web device) to the request.Send one of them.
404Not found.No device matches that credential and installation ID or endpoint.

Send A Push

POST/v1/push/send

Sends 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:, and vbscript: URLs are rejected.

  • Name
    image_urlstring
    Description

    An https image 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), a title (up to 40 characters), and an optional url.

  • 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, or gcm, and can't be aps, notification, data, message, token, topic, condition, android, apns, webpush, fcm_options, from, message_type, or collapse_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 outside 60 to 2419200 (28 days) are moved to the nearest limit.

  • Name
    prioritystring
    Description

    high (default) or normal.

  • Name
    device_targetstring
    Description

    last_used (default) sends to the subscriber's most recently used device. all sends to up to 100 of their most recently used devices.

  • Name
    platform_overridesobject
    Description

    Per-platform changes keyed by ios, android, or web. All three accept title, body, image_url, and url. iOS also accepts subtitle, sound, badge, interruption_level, relevance_score, thread_id, category, and mutable_content. Android also accepts channel_id, small_icon, color, sound, priority, visibility, tag, sticky, and style (big_picture or big_text). Web also accepts icon, badge, require_interaction, and actions.

  • Name
    idempotency_keystring
    Description

    Makes retries safe. Up to 200 letters, numbers, and _ . : -. A repeat request with a key already used on this site returns duplicate and sends nothing.



Response

Returns 202 Accepted when the push is queued, or 200 OK when nothing new was sent.

  • Name
    send.statusstring
    Description

    queued when deliveries were created, duplicate when the idempotency_key was already used, or skipped when 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_devices when 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.

StatusErrorWhat to do
422Add title and body to the request.Lists only the fields that are missing.
422idempotency_key can use letters, numbers, and _ . : - (up to 200 characters).Shorten or simplify the key.
422Check 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.
422Title and body must not be blank after personalization.Add fallback text, for example with Liquid's default filter.
422Validation failedSee details for each field and its limit.
404Subscriber not found. Add them to Bento before sending them a push.Add the subscriber first, or check the selector.
403Your plan doesn't include Bento Chat. Add Chat to your plan in Bento to use it.Add Bento Chat to your plan.
403Your account needs approval before you can use Bento Chat. Request approval in Bento to continue.Request account approval.
503Push is temporarily unavailable. Try again shortly.Retry with the same idempotency_key.

Report An Open

POST/v1/push/opens

Records 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_token value 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 id of 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

    true the first time this notification is opened.

StatusErrorWhat to do
422Add open_token to the request.Send the token from the notification data.
422action_id must be text of 64 characters or fewer.Send the button's id.
404Not found.The token isn't valid for this site, or the site_uuid is wrong.

Web Push Config

GET/v1/push/web/config

Returns 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_id when subscribing.

  • Name
    web[].bundle_idstring
    Description

    The website origin the credential was made for, or web for 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

POST/v1/push/web/subscriptions

Saves 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_id from the web push config.

  • Name
    subscriptionobject
    Description

    Required. The browser's PushSubscription with endpoint and keys.p256dh and keys.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.

KeyWhen it is sentWhat to do with it
bento_open_tokenAlwaysSend it to Report An Open when the notification is tapped.
bento_urlWhen the push has a urlOpen the deep link or web page.
bento_campaign_idWith campaign pushesOptional. Use it for your own analytics.
bento_image_urliOS and Android, when the push has an imageOn iOS, download it in a Notification Service Extension and attach it.
bento_actionsiOS and Android, when the push has buttonsA JSON string of up to 3 buttons, each with id, title, and optional url.
bento_subtitleAndroid, when the push has a subtitleFCM has no subtitle field. Show it as the notification's sub text.
bento_styleAndroid, when the Android override sets style to big_textShow 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.

EventWhen it happens
$push_subscribedA device can now receive pushes: it was registered with permission, permission was granted, or it moved to this subscriber.
$push_unsubscribedA 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_openedThe 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.

EndpointLimit
POST /push/devices, DELETE /push/devices, and POST /push/send combined1,200 per IP address
POST /push/opens300 per IP address and 10,000 per site
/push/web/*60 per IP address and 6,000 per site
POST and DELETE /push/web/subscriptions1,200 per site, on top of the /push/web/* limits
bento-push.js and bento-sw.js scripts300 per IP address

The per-site limits read site_uuid from the query string, so always send it there.