SAMA chat server API: Push Notifications

LOUDLY — CONTROLLED — RELIABLE

Hey! *ring — ring*, *ring — ring* 🔔

Yes, you’ve heard this sound on your phone or other device many times. Nowadays, any application has notifications, and the messenger can’t do without them either.

That is why in our SAMA Push Notifications API, we have developed 4 methods for controlling your devices in the application system:

• ➕push_subscription_create | Subscribe your device to receive notifications
• 📃push_subscription_list | Get a list of user subscriptions
• ❌push_subscription_delete | Unsubscribe your device from notifications
• 📍push_event_create | Create your own event to send out

Subscribe your device to receive notifications

~ request name: push_subscription_create

First, let’s register our device in the system with its unique keys. Send the following request ⬆️:

{
  request: {
    push_subscription_create: {
      platform: "web",
      web_endpoint: "...",
      web_key_auth: "...",
      web_key_p256dh: "...",
      device_udid: "device_laptop"
    },
    id: "create_request"
  }
}

Pass a unique endpoint, key_auth, key_p256dh and of course device_id and create your record of the current device.

In response ⬇️, you will receive your record from the database:

{
  response: {
    subscription: {
      _id: "64f75a35e882c42a399c25de",
      platform: "web",
      web_endpoint: "...",
      web_key_auth: "...",
      web_key_p256dh: "...",
      device_udid: "device_laptop",
      user_id: "6479dfa24f8e0c57edf07dd1",
      created_at: "2023-08-25T12:44:10.372Z",
      updated_at: "2023-08-25T12:44:10.372Z"
    },
    id: "create_request"
  }
}

Get a list of user subscriptions

~ request name: push_subscription_list

If you have multiple devices or just want to check your active devices, send a request ⬆️ for a list of your subscriptions:

{
  request: {
    push_subscription_list: {
      user_id: "6479dfa24f8e0c57edf07dd1"
    },
    id: "list_request"
  }
}

And get an array of objects ⬇️:

{
  response: {
    subscriptions: [
      {
        _id: "644157e316eec28e3dfb8b34",
        platform: "web",
        web_endpoint: "...",
        web_key_auth: "...",
        web_key_p256dh: "...",
        device_udid: "device_laptop",
        user_id: "6479dfa24f8e0c57edf07dd1",
        created_at: "2023-08-25T12:44:10.372Z",
        updated_at: "2023-08-25T12:44:10.372Z"
      },
      {
        _id: "644157e316eec28e3dfb8b35",
        platform: "ios",
        web_endpoint: "...",
        web_key_auth: "...",
        web_key_p256dh: "...",
        device_udid: "device_mobile",
        user_id: "6479dfa24f8e0c57edf07dd1",
        created_at: "2023-08-25T12:44:10.372Z",
        updated_at: "2023-08-25T12:44:10.372Z"
      },
      ...
    ],
    id: "list_request"
  }
}

Unsubscribe your device from notifications

~ request name: push_subscription_delete

If you have lost your device or do not want to receive notifications for it, you can unsubscribe with the following request ⬆️:

{
  request: {
    push_subscription_delete: {
      device_udid: "device_mobile"
    },
    id: "delete_request"
  }
}

And get a confirmation in response ⬇️:

{ 
  response: { 
    success: true, 
    id: "delete_request"
  } 
}

Create your own event to send out

~ request name: push_event_create

Sometimes you’ll need to create a notification that doesn’t exist in the system. Therefore, you can use this recap to create your own event by specifying the list of recipients.

The request ⬆️ will look like this:

{
  request: {
    push_event_create: {
      recipients_ids: [
        "644157e316eec28e3dfb8b31", 
        "644157e316eec28e3dfb8b32"
      ],
      message: {
        title: "Hey!",
        body: "This is your custom event!"
      }
    },
    id: "event_request"
  }
}

And Get the relevant object in response ⬇️:

{
  response: {
    event: {
      _id: "64415891066758fe6754f477",
      user_id: "64415890066758fe6754f472",
      recipients_ids: [
        "644157e316eec28e3dfb8b31", 
        "644157e316eec28e3dfb8b32"
      ],
      message: "{"title":"Hey!","body":"This is your custom event!"}",
      created_at: "2023-08-25T12:44:10.372Z",  
      updated_at: "2023-08-25T12:44:10.372Z"
    },
    id: "event_request"
  }
}

Conclusion

Want to manage device subscriptions and notifications correctly? Then use our tools 🪛, such as the SAMA Push Subscriptions API. The speed result will positively impress you!

👀 Check out more posts on our page for fantastic improvements to your app!

Try SAMA 👇🏼

To run SAMA server locally — follow https://github.com/SAMA-Communications/sama-server. Frontend app is available at https://github.com/SAMA-Communications/sama-client

Discover, enjoy, and all feedback is welcome. We will be thankful a lot for every GitHub star, issue, or comment!

SAMA-Communications