Converse AI by Smartsheet

Custom Channel

The custom channel allows users to integrate directly into Converse without the need for an external messaging channel.

This may because they want to directly build their own messaging integration, or wish to integrate directly into a third party messaging network and use Converse to provide automation for some or all of it.

The custom channel works by using inbound and outbound webhooks. The custom channel sends messages to Converse as required, and Converse will automatically send, asynchronously messages back to the outbound webhook.

We strongly recommend the outbound webhook to be a SSL enabled address (https) with a properly validated certificate (e.g no Self Signed).

If the message to the outbound webhook fails to be sent, we will repeat attempts for up to 10 minutes, after 10 minutes we will disable the webhook and the User will need to reregister the webhook when fixed.

When the webhook is registered, a request will be sent.

Using Rich Media Elements

If you are using custom channel as a proxy between another messaging channel i.e messenger, workchat, slack, you will be able to use the appropriate rich media elements.
To invoke the rich media elements you would need to indicate when the plugin registered which channel elements that you going to use, this needs to be done at the custom channel registration window

Challenge Request

The challenge request is send to the specified outbound webhook the request looks as follows

{
  "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.

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

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

Users, Threads & 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, for example for 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.

Verifying Calls

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

{
  "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:

{
      "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 Converse has populated the object with userUUID and requestUUID these are the Converse references for the user and the request which links up with your system

Sending Messages

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

{
  "action": "message",
  "verifyString": "yourverifystring",
  "payload": {
    "message": {
      "userID": "username",
      "threadID": "threadid",
      "text": "subscribe"
    }
  }
}

Recieving Messages

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

{
  "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.

Receiving Media Message

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

{
	"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 witch contain the channel media type (in this example "FACEBOOK_MEDIA")

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.

Custom Channel


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.