Quickstart

This guide will get you all set up and ready to use the Notify. We’ll cover how to connect a user, and then send your first push notification.

Before you can make requests to the Notify API, you will need to grab your API key from your dashboard. You find it under Settings » API Key.

Try the playground

If you haven't already, we highly recommend checking out the playground. It's a great way to quickly see how the platform works, and send yourself a notification.

Go to the playground

Connecting your user

Before we can send a notification, we need to connect a user to Notify. This is done by generating an intent and directing the user scan the QR code.

1. Generate and display an intent

Example implementation in Next.js app router

app/settings/notifcations/page.tsx

export default async function NotificationsPage() {
  const user = await getCurrentUser()

  const response = await fetch(
    `https://notify.dev/api/v1/intent?user_id=${user.id}`,
    {
      method: 'GET',
      headers: {
        Authorization: process.env.NOTIFY_API_KEY,
        'Content-Type': 'application/json',
      },
    }
  )

  const { image_url, direct_link } = await response.json()

  return (
    <div>
      <h2>Notifications</h2>
      <h3>Push Notifications</h3>
      <p>
        Receive updates on your mobile phone via push notifications. Simply scan
        the QR Code below using your camera (or click the connect button if
        you're already on your phone).
      </p>
      <img src={image_url} alt="QR code" />
      <a href={direct_link}>Connect</a>
    </div>
  )
}

Read the docs for the Intent endpoint

2. User creates the connection

Once the user has scanned the QR code, they will be directed to download the Notify app. The intent will survive the install process and create a connection once launched.

If the user already has the Notify app installed (e.g. they have more than one account for your application, or already use Notify with another application), they can simply scan the QR code inside the app.

3. Your app receives a webhook

Example consumer in Next.js app router

app/api/webhooks/notify/route.ts

export async function POST(request: Request) {
  try {
    const event = await request.json()
    await handleWebhookEvent(event)
    return new Response('success', { status: 200 })
  } catch (error) {
    console.error(error)
    return new Response('error', { status: 500 })
  }
}

If you've setup a webhook, we'll let you know once the user is connected. You can use this to update your UI, or save the value to your database so you know you can send psuh notifications to this user.

Send a push notification

Now that we have a connection, we can send a push notification to the user.

Example function to send push notifications

export async function sendPushNotification(
  userId: string,
  title: string,
  body: string
): Promise<boolean> {
  try {
    const user = await db.query.users.findFirst({
      where: eq(users.id, userId),
    })

    if (user.notify_status !== 'active') {
      console.info('User is not connected to Notify')
      return false
    }

    const response = await fetch('https://notify.dev/api/v1/notify', {
      method: 'POST',
      headers: {
        Authorization: process.env.NOTIFY_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        user_id: user.id,
        title,
        body,
      }),
    })

    const { message } = await response.json()

    if (!response.ok) {
      console.error('Failed to send push notification', message)
      return false
    }

    return true
  } catch (error) {
    console.error(error)
    return false
  }
}

What's next?

Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the Notify API: