Interactive messaging events for Team Messaging

Unlike other outbound events sent by RingCentral, events related to interactive messages do not require the application to explicitly subscribe for a particular set of events. Instead, you will provide an "Outbound webhook URL" when you create your application, to which RingCentral will automatically deliver any event relating to an interactive message posted by that app.

Interactive messaging events are also unique in that applications are expected to issue a response upon receiving an event that will signal to RingCentral how the system should respond to the event. See "Responding to interactive message events" below.

What interactive messaging events are supported?

Currently, the only event RingCentral will transmit to your app is one relating to a user submitting a form contained by an adaptive card posted by the corresponding app. Forms are submitted via users clicking buttons associated with actions of type Action.Submit.

• See Adaptive Cards
• See Creating an Add-in

Responding to interactive message events

Upon receiving an interactive messaging event, applications should respond with an HTTP status code of 200 in order to acknowledge receipt of the event. A developer should respond this way even if an error occurred while processing the event.

In the payload of your response, you can optionally transmit a dialog to cause RingCentral to spawn a dialog. The contents of a modal dialog can either be an adaptive card, or an iframe to an external website. If the payload of the response is anything else, the response will be ignored.

Finally, dialogs will appear only to the person who interacted with the card that spawned the dialog. In this way, dialogs create a private interaction between the user who clicked an adaptive card's submit button, and a bot or add-in.

Learn more about Modal Dialogs »

Verifying the authenticity of an event

With every message posted to an Outbound Webhook URL, RingCentral will also transmit an HTTP header called X-Glip-Signature. The value of this header will be in the format of:

sha1=<signature>

The signature is generated by computing the HMAC SHA1 hash of the receiving application's "shared secret" (generated for you when you created the app), and the event's payload, or the HTTP post's body.

You can verify that RingCentral is the sender of an event by generating your own signature, and comparing it to the one contained in the HTTP header.

const SHARED_SECRET = "abcdefghijklmnopqrstuvwxyz"
api.post('/hook', function (req, res) {
 var signature = req.get('X-Glip-Signature');
 var bodyCrypted = require('crypto')
     .createHmac(
         'sha1',
         SHARED_SECRET 
     )
     .update(JSON.stringify(req.body))
     .digest()
     .toString('hex');

 if (bodyCrypted !== signature) {
     res.status(401).send();
     return;
 }

 console.log('Webhook received')
 // code continues 
})

Handling long-running or asynchronous processes

Some actions that a user intiates may produce the need to update the contents of the original message. Consider for example that a message is delivered to a software engineering team about a new software defect. One of the team members clicks a button to "claim" the issue - signaling to the rest of the team that they will fix the issue. When the message is first posted it shows the assignee as "Unassigned." After the user clicks the "Claim" button, the app wants to update the content of the message to show that the assignee is now "Chewbacca."

To accomplish this, use the Team Messaging REST API to fetch the contents of the corresponding post. This is done via the Get Post endpoint. Then use the Update Post endpoint to modify the contents of the post/message.

Event schema

Each event transmitted to an outbound webhook URL will contain the following information:

• The app ID associated with the event.
• The user who triggered the event.
• The chat in which the event was triggered.
• The message or post the event is associated with.
• The payload of the event, e.g. data submitted by an end user

The payload of the event will contain the data submitted by the user in the form of a name/value pair map.

Example event

{
    'uuid': 'abcdefg',
    'timestamp': '2016-03-10T18:07:52.534Z',
    'type': 'button_submit',
    'appId': 'abcdefg-123443-ghijklmnop',
    'user': {
        'id': 'abcdefg-1234',
        'firstName': 'Luke',
        'lastName': 'Skywalker',
        'accountId': '09283928373'
    },
    'conversation': {
        'id': 'abcdefg-1234',
        'type': 'group',
        'public': true,
        'name': 'Going-away party for Han'
    },
    'post': {
        'id': 'abcdefg-1234',
        'creationTime': '2016-03-10T18:07:52.534Z',
        'lastModifiedTime': '2016-03-10T18:07:52.534Z',
    },
    'data': {
        'foo1' : 'bar1',
        'foo2' : 'bar2'
    }
}

User

Conversation

Post