Get Notification on Fax Status Change for FaxOut RingCentral API

Question

I am using RingCentral FaxOut API to submit a fax. The fax status in that response is Queued. Is there any Subscription to get the Updated Fax Status for that Message. RingCentral Blog mentions about getting the latest status using GetMessage call to their API.

https://www.ringcentral.com/blog/2015/02/know-fax-transmission-api-succeeded/

They do have Push Notifications for User Presence. https://github.com/ringcentral/ringcentral-js

Answer 1

First, there is an older FaxOut API, and then there is the newer RingCentral Platform API Message-Fax resource. The latter is the one which I am going to address here, if you are using the former version please create a support case with RingCentral for assistance.

The not so good news is that there is no direct way using Push Notifications (subscriptions) to receive the specific fax status data you are seeking, but there is the ability to monitor for message store events, and filter the incoming data for EVENT_DATA.changes.type === 'Fax'.

Learn about how to use the message-store eventFilter in your subscriptions: https://developers.ringcentral.com/api-docs/latest/index.html#!#RefGetMessageEvent

Also, I have created a demo application in Node.js showing developers how to create subscriptions (it uses the JavaScript SDK you referenced in your question): https://github.com/bdeanindy/ringcentral-subscription-basics (there are configuration parameters you can set in the .env file to dictate which eventFilters you want to use).

Here is the subscription event stream when I send a fax outbound from RingCentral. Pay attention to the EVENT FILTERS, one of those is a subscription to message-store which is where Fax messages are made available for developers using the API (I've added light comments above each phase of the events):

Succesfully logged into the RC Account
EVENT FILTERS:  [ '/account/~/extension/2557490012',
  '/account/~/extension/2557490012/presence?detailedTelephonyState=true&aggregated=true',
  '/account/~/extension/2557490012/message-store',
  '/account/~/extension/2557490012/presence/line',
  '/account/~/extension/2557490012/message-store/instant?type=SMS' ]
SUBSCRIPTION CREATED SUCCESSFULLY



Fax Sent
SUBSCRIPTION NOTIFICATION.....
{ uuid: '8004a0b2-7907-458b-8a9b-ec1ba3202f5e',
  event: '/restapi/v1.0/account/2557490012/extension/2557490012/message-store',
  timestamp: '2016-09-30T22:43:53.762Z',
  subscriptionId: 'bd6a307b-a05f-4421-acc5-85f093aae2b3',
  body: 
   { extensionId: 2557490012,
     lastUpdated: '2016-09-30T22:43:43.902+0000',
     changes: [ { type: 'Fax', newCount: 1, updatedCount: 0 }, [length]: 1 ] } }


Waiting to connect         
SUBSCRIPTION NOTIFICATION.....
{ uuid: '627d3cdf-1638-4029-9e0b-94bbf3325c61',
  event: '/restapi/v1.0/account/2557490012/extension/2557490012/message-store',
  timestamp: '2016-09-30T22:44:13.776Z',
  subscriptionId: 'bd6a307b-a05f-4421-acc5-85f093aae2b3',
  body: 
   { extensionId: 2557490012,
     lastUpdated: '2016-09-30T22:44:01.879+0000',
     changes: [ { type: 'Fax', newCount: 0, updatedCount: 1 }, [length]: 1 ] } }
SUBSCRIPTION NOTIFICATION.....
{ uuid: 'f1e1310e-11c7-479d-b988-087379bdcad3',
  event: '/restapi/v1.0/account/2557490012/extension/2557490012/message-store',
  timestamp: '2016-09-30T22:44:23.769Z',
  subscriptionId: 'bd6a307b-a05f-4421-acc5-85f093aae2b3',
  body: 
   { extensionId: 2557490012,
     lastUpdated: '2016-09-30T22:44:15.565+0000',
     changes: [ { type: 'Fax', newCount: 0, updatedCount: 1 }, [length]: 1 ] } }

Waiting to have sent confirmation
SUBSCRIPTION NOTIFICATION.....
{ uuid: '2148d2d9-8e05-4adc-8019-518774187116',
  event: '/restapi/v1.0/account/2557490012/extension/2557490012/message-store',
  timestamp: '2016-09-30T22:45:33.767Z',
  subscriptionId: 'bd6a307b-a05f-4421-acc5-85f093aae2b3',
  body: 
   { extensionId: 2557490012,
     lastUpdated: '2016-09-30T22:45:21.232+0000',
     changes: [ { type: 'Fax', newCount: 0, updatedCount: 1 }, [length]: 1 ] } }

But how do you determine if the fax has been sent, or is queued, or has failed? You use the EVENT.event property to GET the Message Store list filtering in the query for: messageType=Fax&availability=Alive&direction=Outbound&messageStatus=Sent

Then, the resulting Message Store records will have a new item in records you can use the to.phoneNumber to match the origination event (HTTP POST to send the Fax).

{
      "uri": "{{REMOVED_FOR_SECURITY}}",
      "id": {{REMOVED_FOR_SECURITY}},
      "to": [
        {
          "phoneNumber": "+{{REMOVED_TO_PREVENT_SPAM}}",
          "name": "Hello Fax",
          "messageStatus": "Sent"
        }
      ],
      "type": "Fax",
      "creationTime": "2016-09-30T22:43:43.000Z",
      "readStatus": "Unread",
      "priority": "Normal",
      "attachments": [
        {
          "id": {{REMOVED_FOR_SECURITY}},
          "uri": "{{REMOVED_FOR_SECURITY}}",
          "type": "RenderedDocument",
          "contentType": "application/pdf"
        }
      ],
      "direction": "Outbound",
      "availability": "Alive",
      "messageStatus": "Sent",
      "faxResolution": "High",
      "faxPageCount": 2,
      "lastModifiedTime": "2016-09-30T22:45:21.232Z",
      "coverIndex": 0
    }