Custom Channel Reference Guide

Applies to

Bridge by Smartsheet

Challenge request

The challenge request is sent to the specified outbound webhook. The request looks as follows:

JSON

{

  "action": "challenge",

  "verifyString": "anystring",

  "payload": {

    "message": {

      "text": "8B58A4A4-DEC3-401D-AE3D-A7F19AC97560",

      "time": 1480034360028

    }

  }

}

The Webhook handler needs to respond with a challenge reply sending the same text response back.

JSON

{

  "challenge": "8B58A4A4-DEC3-401D-AE3D-A7F19AC97560"

}

When the challenge is successful the user is given (in the Bridge UI) the inbound url which can be used to send

Users, threads, and comments

The custom messaging channel has three key components: Users, Threads and Comments.

Each user can have one or more threads, and each thread has one or more comments.

You may wish to use multiple threads if you want to support multiple simultaneous conversations, such as a channel based messaging network.

To get started, you need to create a new thread. You can create the user in the same call.

When creating secondary threads, any user details that are specified and different (firstName, lastName etc), will be updated for all the users threads.

Verify calls

For every call you make, you need to include the 'verifyString' that you set originally.

JSON

{

  "action": "thread",

  "verifyString": "yourverifystring",

  "payload": {

    "thread": {

      "userID": "username",

      "threadID": "threadid",

      "firstName": "First",

      "lastName": "Last",

      "email": "e-mail@example.com"

    }

  }

}

On success you will get a response like:

JSON

{

      "userID": "username",

      "userUUID": "06467517-4E44-4B8F-9405-93F3DECCB516",

      "requestUUID": "3FC43963-BBC6-4833-9BB2-E2F1303430B6",

      "threadID": "threadid",

      "firstName": "First",

      "lastName": "Last",

      "email": "e-mail@example.com"

    }

  }

}

As you can see Bridge has populated the object with userUUID and requestUUID. These are the Bridge references for the user and the request which links up with your system.

Send messages

A message needs to be sent to Bridge in the following format. On successful message delivery Bridge will return you a 200 ok status.

JSON

{

  "action": "message",

  "verifyString": "yourverifystring",

  "payload": {

    "message": {

      "userID": "username",

      "threadID": "threadid",

      "text": "subscribe"

    }

  }

}

Receive messages

Bridge processes messages asynchronously. If a response is generated, it will be sent back to the outbound webhook with the following syntax:

JSON

{

  "action": "message",

  "verifyString": "yourverifystring",

  "payload": {

    "message": {

      "threadID": "threadid",

      "userId": "username",

      "text": "Do you want to subscribe for the service ?",

      "time": 1480037596179

    }

  }

}

Messages that can then be exchanged back and forwards as required.

Receive media messages

When you enable using channel specific media elements with the custom channel you will get the fully built element that you can pass to the channel.

JSON

{

    "action": "message",

    "verifyString": "yourverifystring",

    "payload": {

        "message": {

            "threadID": "threadid",

            "userId": "username",

            "isRichMedia": true,

            "time": 1505993126379,

            "conversationUUID": "40262BBF-8B3A-4AAA-AF19-5A83A8ECE951",

            "messageID": "A5E8B708-BC67-4D65-8A0B-65378072BDAB",

            "mediaData": {

                "element": {

                    "quick_replies": [{

                        "content_type": "text",

                        "payload": "Value",

                        "title": "Title"

                    }],

                    "text": "answer replacement"

                },

                "type": "FACEBOOK_MEDIA"

            }

        }

    }

}

If you are getting rich media data, the outbound message will have isRichMedia set to true and a mediaData object which contain the channel media type (in this example FACEBOOK_MEDIA)

NOTE: You need to handle the inbound side of rich media as you are proxying the call i.e the postbacks coming form buttons etc, as the inbound structure changes.