API Reference

Webhooks

Webhooks enable apps to subscribe to changes in certain pieces of data and receive updates in real time. When a change occurs, an HTTP POST request will be sent to a callback URL belonging to your conversation bot. See Getting Started section for an example of deploying an app with a defined webhook.

Format of message that hootsy would send to your webhook:

{
object:"Message",
entry:[{
id:"PAGE_ID",
time:63624884710891,
messaging:[{
"sender":{
"id":"USER_ID"
},
"recipient":{
"id":"OBJECT_INSTANCE_ID"
},
"message":{
"mid":"mid.1457764197618:41d102a3e1ae206a38",
"text":"hello, world!",
}
}]
}]
}
Field Name Description Type
mid Message ID String
text Text of message String

Send API

This describes how to send responses to Hootsy assistants which are then provided to users.

To send a message, make a POST request to https://hootsy.com/vr/relay/send?access_token= with your access token. The payload must be provided in JSON format as described below:

curl -X POST -H "Content-Type: application/json" -d '{
"recipient": {
"id": "USER_ID"
},
"message": {
"text": "hello, world!"
"action": "default.welcome"
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"

Payload

Property Name Description Required
recipient recipient Object Yes
message message object Yes

message Object

Property Name Description Required
text Message text spoken by the object text or attachment must be set
action Message action. This is sent to the Action Control Script in the SDK to allow actions in the scene like grow or remove object No
attachment attachment object text or attachment must be set
quick_replies Array of quick_reply to be sent with messages No
metadata Custom string that will be re-delivered to the webhook listeners No

Content Types

Text Message

Provides a simple text response which is spoken by the assistant.

Text Message

Property Name Description Required
text Message text spoken by the object Yes

Image Attachment

Provides a 2D image that displays next to the assistant.

Image Attachment

curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"USER_ID"
},
"message":{
"attachment":{
"type":"image",
"payload":{
"url":"https://sample.com/image.png"
}
}
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"
Property Name Description Required
type image Yes
payload.src Source URL of image Yes

Model Attachment

Provides a 3D model that displays next to the assistant. This attachment type is unique to Hootsy.

Model Attachment

curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"USER_ID"
},
"message":{
"attachment":{
"type":"model",
"payload":{
"url":"https://sample.com/sofa.gltf",
"context": "sofa",
"subcontext": ["cushion", "legs"],
"scale": 1,
"x_position": 1.5,
"y_position": 0.5,
"z_position": 1,
"y_rotation": 90
}
}
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"
Property Name Description Required
type model Yes
payload.url URL of image. Must be a GLTF, GLB or FBX model. Yes
payload.context Defines the context that will be sent in a subsequent message if the user looks at the model and says a new command. Managed by the Context Control script No
payload.subcontext Defines the subcontext which are parts of the model that will be sent in a subsequent message if the user looks at that part of the model and says a new command. For example, if user looks at the sofa cushion and says ‘what is this’. This message is sent with context of ‘sofa’ and ‘cushion’. Managed by the Context Control script No
payload.scale Scale of model. Defaults to 1. No
payload.x_position X position of model. Defaults to 0 which is a position far enough to the right of the assistant to ensure no overlap. No
payload.y_position Y position of model. Defaults to 0 which is ground height. No
payload.z_position Z position of model. Defaults to 0. No
payload.y_rotation Y rotation of model in degrees. Defaults to 0. No

Animation Attachment

Tells the assistant to play a specified animation like waving when responding with ‘hello’. This attachment type is unique to Hootsy.

Model Attachment

curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"USER_ID"
},
"message":{
"attachment":{
"type":"animation",
"payload":{
"name":"Waving"
}
}
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"
Property Name Description Required
type background Yes
payload.name Name of the animation. This must be defined for the character in the hootsy studio with Repeat set to ‘On Request’. This will stop any continuous animation until the animation completes. Yes

Templates

These are structured message templates supported by Hootsy.

Button Template

Provides buttons that display next to the object along with spoken text for the object.

Button Template

curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"USER_ID"
},
"message":{
"attachment":{
"type":"template",
"payload":{
"template_type":"button",
"text":"What would you like to know more about?",
"buttons":[
{
"type":"postback",
"title":"Basic Response",
"payload":"USER_DEFINED_PAYLOAD_BASICRESPONSE"
},
{
"type":"postback",
"title":"Animation",
"payload":"USER_DEFINED_PAYLOAD_ANIMATION"
},
{
"type":"postback",
"title":"Model",
"payload":"USER_DEFINED_PAYLOAD_MODEL"
},
{
"type":"postback",
"title":"Carousel",
"payload":"USER_DEFINED_PAYLOAD_CAROUSEL"
}
]
}
}
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"

attachment Object

Property Name Description Required
type Value must be template Yes
payload payload of button template Yes

payload Object

Property Name Description Type Required
template_type Value must be button String Yes
text UTF-8 encoded text of up to 640 characters String Yes
buttons Set of one to three buttons that appear as call-to-actions Array of button Yes

Generic Template

Provides a scrollable carousel of items.

Generic Template

curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"USER_ID"
},
"message":{
"attachment":{
"type":"template",
"payload":{
"template_type":"generic",
"elements":[
{
"title":"Blue Winchester sofa.",
"image_url":"https://sample.com/blue_sofa.png",
"subtitle":"Made of fine leather.",
"buttons":[
{
"type":"postback",
"title":"Blue Winchester",
"payload":"USER_DEFINED_PAYLOAD_SELECT"
}
]
}
]
}
}
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"

attachment Object

Property Name Description Required
type Value must be template Yes
payload payload of generic template Yes

payload Object

Property Name Description Type Required
template_type Value must be generic String Yes
elements Data for each bubble in message Array of element Yes

element Object

Property Name Description Type Required
title Spoken by the object. String Yes
subtitle Spoken by the object after saying the title. String No
image_url Image to display String No
buttons Set of buttons that appear as call-to-actions Array of button No

Buttons

Buttons are supported by the button template and generic template. Buttons provide an additional way for a user to interact with your object beyond spoken commands.

Postback Button

The postback button will send a call to your webhook.

...
"buttons":[
{
"type":"postback",
"title":"Bookmark Item",
"payload":"DEVELOPER_DEFINED_PAYLOAD"
}
]
...

buttons Fields

Property Name Description Type Required
type Type of button. Must be postback. String Yes
title Button title. 20 character limit. String Yes
payload This data will be sent back to your webhook. 1000 character limit. String Yes

The callback to your webhook will appear as follows:

{
"sender":{
"id":"USER_ID"
},
"recipient":{
"id":"PAGE_ID"
},
"postback":{
"payload":"DEVELOPER_DEFINED_PAYLOAD"
}
}

URL Button

(Web SDK only) The URL button opens a webpage. An example use case would be opening a webview to finalize the purchase of items. The button must be selected via click or tap action so we recommend indicating this in the assistant’s response when displaying these buttons.

...
"buttons":[
{
"type":"web_url",
"title":"Web Item",
"url":"https://samplesite.com"
}
]
...

buttons Fields

Property Name Description Type Required
type Type of button. Must be web_url. String Yes
title Button title. 20 character limit. String Yes
url The location of the site you want to open in a webview. String Yes

Quick Replies

Quick replies display buttons to the user for quick response to a request. They provide an additional way for a user to interact with your object beyond spoken commands.

Quick Replies

Message webhook sends to Hootsy:

curl -X POST -H "Content-Type: application/json" -d '{
"recipient":{
"id":"USER_ID"
},
"message":{
"text":"Are you hungry?",
"quick_replies":[
{
"content_type":"text",
"title":"Yes",
"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_YES",
},
{
"content_type":"text",
"title":"No",
"payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_NO",
}
]
}
}' "https://hootsy.com/vr/relay/send?access_token=<OBJECT_ACCESS_TOKEN>"

Quick Replies is an array of up to 11 quick_reply objects. Each corresponding to a button. Scroll buttons will display when there are more than 3 quick replies. Example:

Quick Replies Paged

quick_reply Object

Property Name Description Type Required
content_type Only ‘text’ is currently supported. String Yes
title Caption of button String Yes
payload Custom data that will be sent back to you via webhook String No

When a Quick Reply is selected, a text message will be sent to your webhook Message Received Callback. The text of the message will correspond to the Quick Reply payload.

Response sent to your webhook:

{
"sender": {
"id": "USER_ID"
},
"recipient": {
"id": "OBJECT_ID"
},
"message": {
"mid": "mid.1464990849238:b9a22a2bcb1de31773",
"text": "Red",
}
}

Get Started Message

This message is sent the first time a virtual assistant starts listening. The text of the message is defined when the assistant is created. It is useful if you want to have the assistant initiate the conversation when the user first looks at it or want to display an additional model along with the assistant.