Send a notification to one user, a group, or everyone
POST /v1/notifications
Send to one of your users with user_id; to a group with any mix of user_ids, emails, contact_ids and contacts (the same filters as GET /v1/contacts, such as { "stage": "customer" }); or to everyone with audience: "all". A bell is found by your own user id, so an email or a contact reaches someone only when Launch knows their user id: from identify() with a user id and an email, feedback sent with both, or a paying customer’s metadata. meta.audience says how many were reached and up to 20 who were not; when nobody can be reached the answer is NO_REACHABLE_RECIPIENTS (422), and a group is at most 10,000 people (TOO_MANY_RECIPIENTS). send_at schedules it up to 60 days ahead. A broadcast shows in a bell for 30 days. Every notification, a group or a broadcast included, counts once against the monthly cap per project (Free 1,000, Indie 20,000, Builder 200,000, per calendar month in UTC); past it the answer is PLAN_LIMIT_REACHED (403). meta.usage has the month so far.
Auth: Secret key only. The dashboard has the same operation under /v1/dashboard/notifications.
Authorizations
Section titled “Authorizations ”Request Body required
Section titled “Request Body required ”object
One user. Leave out for a group or a broadcast.
Worked out when left out: users when any group field is sent, else user.
A Contacts filter: stage, consent, detail (name or name=value), paying, has_feedback, status, source, q. Values as strings, like the query parameters of GET /v1/contacts.
object
An http(s) URL, or a path on your own site such as /billing.
A short name the bell can show as a tab, such as billing.
Up to two buttons. Each url is an http(s) URL or a path on your own site.
object
Anything your page needs with the item (at most 2,048 bytes as JSON). Never shown; the bell widget passes it in its events.
Show it from this time, at most 60 days ahead. A time in the past means now.
Keep it at the top of the bell until each person archives it (a maintenance notice). A pinned broadcast is not dropped after 30 days; retention of 90 days still applies.
Responses
Section titled “ Responses ”Sent
object
object
Example
ntf_01J...Set on a direct notification only.
user: one user id. users: a group. all: everyone.
A short name the bell can show as a tab, such as billing.
Up to two buttons. Each url is an http(s) URL or a path on your own site.
object
Anything your page needs with the item (at most 2,048 bytes as JSON). Never shown; the bell widget passes it in its events.
Direct notifications only; null on a group or a broadcast, which are read per person.
When it shows in bells: created_at, or the scheduled time.
Waiting for visible_at. Delete it to cancel; the month’s count is given back.
1 for a direct notification, the group’s size for a group, null for a broadcast.
The reaction names people can pick in the bell; empty for none.
object
Error envelope. See error.code for the discriminator.
object
object
object
Error envelope. See error.code for the discriminator.
object
object
object
Error envelope. See error.code for the discriminator.