Notification channels in REST APIs

API's and SDK's
1

The AT&T API Marketplace (APIM) https://apimarket.att.com supports three types of notification channels:

  • Websockets
  • OMAPush (Mobile push)
  • Webhooks

Here are some useful highlights for each:

  • Websockets:
    • APIM supports mono-directional websocket channels, where in general the message flow is from APIM to client. The only exception is connCheck-connAck mechanism (application level ping-pong) where client also can send a specified message for keep-alive purpose.
    • When connection drops for any reason, APIM websocket channels support reconnection with same channelId directly on websocket protocol until notificationChannelLifetime of REST resource itself expires.
    • A single-page web apps (SPA) is a good example of a client that utilizes websocket channels.
  • Mobile push:
    • There are two mobile push providers supported: Apple APNS and Google FCM.
    • Unlike websocket channels, mobile push channels are permanent, meaning that you do not need to refresh them. They exist on APIM until removed by client explicitly, or an error message is received from APNS or FCM indicating mapping device token does not exist anymore.
    • Obviously a mobile native app can use mobile push channels.
  • Webhooks:
    • APIM uses webhooks to send notifications using HTTP POST request.
    • While creating a webhook channel, apps can utilize x-authorization input to request HTTP Authorization header within webhook notification requests.
    • Like mobile push channels, webhook channels do not expire as well.
    • A server-side app is a good example for webhook using client.

In order to receive notifications related with APIM services, there is a two step API flow:

  1. Create notification channel
  2. Subscribe to related service(s) pointing to the notification channel resource

Not all the APIM services provide notifications. Here is a summary of APIs and services that you need notification channels:

  • SMS - /smsmessaging API - for incoming SMS.
    • You do not need a notification channel to send SMS.
  • Chat - /chat API - for incoming 1-1 and group chat messages including notifications like group invitations, isComposing messages, delivery receipts etc.
    • You again do not need a notification just to send a chat message, however that is not a common use case in chat context.
  • WebRTC Calls - /webrtcsignaling API - for any call related notifications, such as incoming call, call end, etc.
  • Presence - /presence API - for presence update notifications from watched list.
  • User Management - /account API - for user status changes for managed users.

Finally, there are some restrictions related with services and channel types:

  • Presence notifications are not supported for mobile push channels.
  • User management notifications can only be delivered via webhooks.

For more details on notification channels, you can refer to this quickstarts section: Notification Channels on the AT&T API Marketplace Developer Documentation pages https://apimarket.att.com/developer

2 Likes