Moxtra Bot SDK

Moxtra's Bot SDK is to ease the Bot development for Moxtra's business collaboration platform. Once you complete the Bot App creation flow, others can add your Bot user via Add Bot Users to Binder.

Below diagram depicts the Bot App flow:

Bot LifeCycle

  • Partner Admin creates a bot app configuration via Partner Admin Console.
  • An Org Admin enables this bot app via Org Admin Console or API, this bot app becomes a bot user inside this org. A bot_enabled event gets generated.
  • When the Org Admin disabled this bot app via Org Admin Console or API, a bot_disabled event gets generated.
  • Binder users of the same org as the binder owner can then add this bot user into the binder. A bot_installed event gets triggered.
  • When the bot user leaves the binder, a bot_uninstalled event gets generated.

SDK

Below are the SDKs you can clone from github:

Receive Messages

Bot would receive event messages while an event gets triggered. A sample outgoing comment event message looks like below:

{
    "message_id": "2889",
    "message_type": "comment_posted",
    "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
    "client_id":"ODM3YmFiNWF",
    "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",    
    "event": {
	"timestamp": "2017-04-25T23:17:10Z",
	"user": {
	    "id": "Utkj3YC5BxRHCCaq9widP67",
	    "name": "Joe Smith"
	},
	"comment": {
	    "id": "2888",
	    "text": "what is a bot?",
	    "audio": null
	},
	"target": {
	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
	    "object_type": "binder"
	}
    }
}


The request will not wait for the return value from the Bot. Depending on the event type, different message format gets generated as shown below:

{
     "message_id": "2889",
     "message_type": "bot_enabled",
     "binder_id": "",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"bot": {
 	    "id": "ODM3YmFiNWF",
 	    "name": "Test Bot"
 	},
 	"target": {
 	    "id": "Pg3dAcMahyYFJDE4HyfFZw6",
 	    "object_type": "org"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "bot_disabled",
     "binder_id": "",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"bot": {
 	    "id": "ODM3YmFiNWF",
 	    "name": "Test Bot"
 	},
 	"target": {
 	    "id": "Pg3dAcMahyYFJDE4HyfFZw6",
 	    "object_type": "org"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "bot_installed",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"bot": {
 	    "id": "ODM3YmFiNWF",
 	    "name": "Test Bot"
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "bot_uninstalled",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"bot": {
 	    "id": "ODM3YmFiNWF",
 	    "name": "Test Bot" 	    
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "comment_posted",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"comment": {
 	    "id": "2888",
 	    "text": "what is a bot?",
 	    "audio": null
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "comment_posted_on_page",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"comment": {
 	    "id": "2888",
 	    "text": "what is a bot?",
 	    "audio": null
 	},
 	"target": {
 	    "id": "2772",
 	    "object_type": "page"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "file_uploaded",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"file": {
 	    "id": "2888",
 	    "name": "foreground.png",
 	    "mimeType": "image/png"
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "meet_recording_ready",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"meet": {
 	    "id": "777652546",
 	    "topic": "Joe's Meet",
 	    "recording_url": null,
 	    "start_time": "2016-04-26T01:26:56Z",
 	    "end_time": "2016-04-26T01:27:56Z"
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "page_created",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"page": {
 	    "id": "2917",
 	    "type": "PAGE_TYPE_WHITEBOARD"
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "page_annotated",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"annotate": {
 	    "id": "2909"
 	},
 	"target": {
 	    "id": "2772",
 	    "object_type": "page"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "todo_created",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"todo": {
 	    "id": "2925",
 	    "name": "New project planning"
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}
{
     "message_id": "2889",
     "message_type": "todo_completed",
     "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
     "client_id":"ODM3YmFiNWF",
     "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",
     "event": {
 	"timestamp": "2017-04-25T23:17:10Z",
 	"user": {
 	    "id": "Utkj3YC5BxRHCCaq9widP67",
 	    "name": "Joe Smith"
 	},
 	"todo": {
 	    "id": "2925",
 	    "name": "New project planning"
 	},
 	"target": {
 	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
 	    "object_type": "binder"
 	}
     }
}

Get Access Token for Bot User

To obtain the access_token, please make a simple HTTPS GET request to:

  • https://apisandbox.moxtra.com/apps/token (for sandbox environment)
  • https://api.moxtra.com/apps/token (for production environment)

https://apisandbox.moxtra.com/v1/apps/token?client_id=CLIENT-ID&org_id=ORG-ID&timestamp=TIMESTAMP&signature=SIGNATURE

Request Parameters
Name Type Description
client_id String The client ID you received from Moxtra when Partner Admin sets up bot app configuration.
org_id String The org ID where the bot app is enabled.
timestamp String The request time in milliseconds since 1/1/1970 0:0:0.
signature String It is the HMAC-SHA256 hash of the message content (client_id + org_id + timestamp) signed with client_secret.

On successful authentication, Moxtra will return the access token as a JSON response as shown below:

{
    "access_token": "F6YwMQAAATp7lE9TAACowENMLWNsaWVudCAgICAgICAgICAgICAgAAAAAw",
    "expires_in": 43199
}

Response Parameters
Name Description
access_token Access token for use in Moxtra REST API calls.
expires_in Expiration time (in seconds)

Post Message to Binder

Bot can post a message to the specified binder Details can refer to Post Message to Binder.

POST /{binder_id}/messages

Bot sends the message to the REST API endpoint URL using POST method with Content-Type: application/json with the following format:

{ 
    "message": {
	"text": "simple text message",
	"richtext": "text message in BBCode style",
	"fields": {  
	    "key1": "value1",
	    "key2": "value2",
	    ...
	},
	"action": "chat", "page", or "todo",
	"buttons": [  	
	    {
	    	"type": "account_link",
	    	"text": "TEXT"
	    },	
	    {
	    	"type": "postback",
	    	"text": "TEXT",
	    	"payload": "PAYLOAD"	    	
	    }
	]
    },
    "fields_template": [    
	{	
	    "template_type": "text", "richtext", or "page",
	    "template": "Template For Fields"
	},
	...
    ] 
  }

JSON Parameters
Name Type Description
text (in message) String Plain text message.
richtext (in message) String Text message in BBCode style.
fields (in message) JSON Key-value pairs in JSON.
action (in message) String Optional: on-demand target action for "chat", "page", or "todo".
buttons (in message) Array Buttons array.
type (in buttons array) String "account_link" or "postback".
text (in buttons array) String Text for the button.
payload (in buttons array) JSON or String Optional: payload for "postback" button.
template_type (in fields_template) String Optional for fields: on-demand template for "text", "richtext", or "page".
template (in fields_template) String Optional for fields: template for rendering key-value pairs.

Buttons

Two types of buttons you can put in the response message:

  • postback - a button contains "text" and "payload", which can be a JSON object or a string. Once the button gets tapped, a "postback" event postes to the Bot. The sample message is shown below:

    {
        "message_id": "1124",
        "message_type": "bot_postback",
        "binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
        "client_id":"ODM3YmFiNWF",
        "org_id":"Pg3dAcMahyYFJDE4HyfFZw6",    
        "event": {
    	"timestamp": "2017-04-25T23:17:10Z",
    	"user": {
    	    "id": "Utkj3YC5BxRHCCaq9widP67",
    	    "name": "Joe Smith"
    	},
    	"postback": {
    	    "text": "Not Sure?",
    	    "payload": "MOXTRABOT_NOT SURE?"
    	},
    	"target": {
    	    "id": "BAGUChIRH7P7eBdR9h9nyR5",
    	    "object_type": "binder"
    	}
        }
    }

  • account_link - a button contains "text". Once tapped it will follow the Account Linking flow.

Test your Bot

After you have configured your Bot with required 'YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET', 'API_ENDPOINT' and other OAuth2 configurations if performing account linking.
You can install your Bot in one of your binders via UI or Add Bot Users to Binder API.