Integration

An integration object in Moxtra provides the following properties:

Name Description Example
id The integration ID. 5
service The 3rd party service that integrates with Moxtra. Availables are:
  • incoming - Webhooks integration service
  • airbrake - Airbrake service
  • appsignal - AppSignal service
  • bitbucket - Bitbucket service
  • celery - Celery service
  • chargebee - Chargebee service
  • chargify - Chargify service
  • crashlytics - Crashlytics service
  • datadog - Datadog service
  • formstack - Formstack service
  • fulcrum - Fulcrum service
  • github - GitHub service
  • gitlab - GitLab service
  • gosquared - GoSquared service
  • hubspot - Hubspot service
  • intercom - Intercom service
  • jira - Jira service
  • librato - Librato service
  • mailchimp - MailChimp service
  • marketo - Marketo service
  • netlify - Netlify service
  • olark - Olark service
  • opbeat - Opbeat service
  • opsgenie - OpsGenie service
  • pagerduty - PagerDuty service
  • paypal - PayPal service
  • pivotaltracker - Pivotal Tracker service
  • postmark - Postmark service
  • raygun - Raygun service
  • runscope - Runscope service
  • sparkpost - SparkPost service
  • sprintly - Sprint.ly service
  • stripe - Stripe service
  • supportbee - SupportBee service
  • testfairy - TestFairy service
  • tribehr - TribeHR service
  • wufoo - Wufoo service
  • xplenty - Xplenty service
  • yo - Yo service
  • zendesk - Zendesk service
  • zoho - Zoho service
For the outgoing service using "outgoing" as the service name.
github
name The customized name for the service. Test
action The content to be displayed via the Moxtra actions: chat, page, or todo. chat
description The description of the integration. github integration
webhook_url The webhook URL in Moxtra to be called from the 3rd party service. For the outgoing service integration, this is the URL to send the response back. https://api.moxtra.com/webhooks/ CAEqBXNiRVhxehdCeTBtQzhPM3Iw RUkwSUM4TVdzaE93NYABZpAYZH
disabled Wehther the integration is disabled. false
created_time The timestamp, when the integration object was created. 1348864985783
updated_time The timestamp, when the integration object was updated. 1348864985783

Name Description Example
outgoing_url The endpoint URL of the 3rd party for the outgoing webhook to invoke. https://www.thirdparty.com/endpoint
comment_posted Event triggered when a comment is posted on a binder; such as chat or todo comment true
comment_posted_on_page Event triggered when a comment is posted on a binder page. true
page_created Event triggered when a page is created in a binder. true
file_uploaded Event triggered when a file is uploaded in a binder; such as page or todo attachment. true
page_annotated Event triggered when a binder page is annotated. true
todo_created Event triggered when a todo task is created. true
todo_completed Event triggered when a todo task is completed. true
meet_recording_ready Event triggered when a meet recording is ready. true

Get Integration List

Get integration list identified by {user_id}.

GET /{user_id}/integrations

Sample Request
GET /me/integrations
Sample Response
{
    "code": "RESPONSE_SUCCESS",
    "data": {
        "binders": [
            {
                "binder_id": "B34gq491gkjFjbmXYW5xQkC",
                "count": 2,
                "integrations": [
                    {
                        "webhook_url": "https://api.moxtra.com/webhooks/CAEqBUsrSXdxehdCMzRncTQ5MWdrakZqYXshUlc1eFFrQ4ABTJADFA",
                        "id": "313",
                        "service": "github",
                        "action": "chat",
                        "description": "Test",
                        "disabled": false,
                        "updated_time": 1414713251918,
                        "created_time": 1414713251914
                    },
                    {
                        "webhook_url": "https://api.moxtra.com/webhooks/CAEqBVlIU0doehdCb2wyVGhzU3Jyb0Z0JsoENWcxUWVsSIABuwKQAxQ",
                        "id": "315",
                        "service": "outgoing",
                        "action": "chat",
                        "description": "",
                        "disabled": false,
                        "updated_time": 1414715708597,
                        "created_time": 1414715708593,
                        "outgoing": {
				"outgoing_url": "https://github.com/test/moxtra",
				"comment_posted": true,
				"comment_posted_on_page": true,
				"page_created": true,
				"file_uploaded": true,
				"page_annotated": false,
				"todo_created": true,
				"meet_recording_ready": false,
				"todo_completed": false
                        }            
                    }
                ]  
            }
        ]
    }
}
          

Create Incoming Integration to Binder

Add incoming integration identified by {binder_id}.

POST /{binder_id}/integrations

Third-party services push information to Moxtra as chat, page, or todo set in the "action" along with specific pushing methods defined by those third-party services. Generic incoming service via the following mechanism:

  • POST request with Content-Type: application/x-www-form-urlencoded and set key-value pairs as follows:
    key1=value1&key2=value2&...

    or set "payload" parameter as shown below:
    payload=This is a line of text in a binder.\nAnd this is another line of text.
  • POST request with Content-Type: application/json and set the content body as follows:
    { "text": "This is a line of text in a binder.\nAnd this is another line of text." }

    or
    { 
        "key1": "value1",
        "key2": "value2",
        ...
      }
  • POST request with Content-Type: application/json and set the content body as structured message format where "sender" is optional and message content could set as "text", "richtext", or "fields" as shown below:

    { 
        "sender": {
    	"name": "Sender Name",
    	"avatar_url": "Sender's Avatar"
        },
        "message": {
    	"text": "simple text message",
    	"richtext": "text message in BBCode style",
    	"fields": {
    	    "key1": "value1",
    	    "key2": "value2",
    	    ...
    	}
        }	    
      }
  • Upload file and add audio comment with Content-Type: multipart/form-data and set parameters as follows:

    • payload - Optional the key-value pairs message with Content-Type: application/x-www-form-urlencoded as before-mentioned

    • file - Optional the file that is getting uploaded into the binder, for example

      ...
        Content-Type: multipart/form-data; boundary=---------------------------9051914041544843365972754266
        Content-Length: 3234
        
        -----------------------------9051914041544843365972754266
        Content-Disposition: form-data; name="file"; filename="start.png"
        Content-Type: image/png
        
        Content of start.png
        
    • audio - Optional the audio file (audio/x-m4a, audio/3gpp) for audio comment that is getting uploaded into the binder, for example

      ...
        Content-Type: multipart/form-data; boundary=---------------------------9051914041544843365972754266
        Content-Length: 4568
        
        -----------------------------9051914041544843365972754266
        Content-Disposition: form-data; name="audio"; filename="test_comment.3gpp"
        Content-Type: audio/3gpp
        
        Content of test_comment.3gpp
        

JSON Parameters
Name Type Description
service String Supported 3rd party services:
  • incoming - Webhooks integration service
  • airbrake - Airbrake service
  • appsignal - AppSignal service
  • bitbucket - Bitbucket service
  • celery - Celery service
  • chargebee - Chargebee service
  • chargify - Chargify service
  • crashlytics - Crashlytics service
  • datadog - Datadog service
  • formstack - Formstack service
  • fulcrum - Fulcrum service
  • github - GitHub service
  • gitlab - GitLab service
  • gosquared - GoSquared service
  • hubspot - Hubspot service
  • intercom - Intercom service
  • jira - Jira service
  • librato - Librato service
  • mailchimp - MailChimp service
  • marketo - Marketo service
  • netlify - Netlify service
  • olark - Olark service
  • opbeat - Opbeat service
  • opsgenie - OpsGenie service
  • pagerduty - PagerDuty service
  • paypal - PayPal service
  • pivotaltracker - Pivotal Tracker service
  • postmark - Postmark service
  • raygun - Raygun service
  • runscope - Runscope service
  • sparkpost - SparkPost service
  • sprintly - Sprint.ly service
  • stripe - Stripe service
  • supportbee - SupportBee service
  • testfairy - TestFairy service
  • tribehr - TribeHR service
  • wufoo - Wufoo service
  • xplenty - Xplenty service
  • yo - Yo service
  • zendesk - Zendesk service
  • zoho - Zoho service
action String Action for this integration: chat, page, or todo.
name String Optional: customized name for this integration.
description String Optional: description for this integration.
disabled Boolean Optional: true to disable, false to enable.
Sample Request
POST /B7V4ze37oO08PYO70973lX6/integrations
{
    "service": "github",
    "action": "chat",
    "description": "Github version control"    
}
Sample Response
{
    "code": "RESPONSE_SUCCESS",
    "data": {
        "id": "68",
        "webhook_url": "https://api.moxtra.com/webhooks/CAEqBXhkdSSDAehdCeTBtQzhPM3IwRUkwSUM4TVdzaE93NYABBJADFA",
        "service": "github",
        "action": "chat",
        "description": "Github version control",
        "disabled": false,
        "created_time": 1342813061602,
        "updated_time": 1342813061602
    }
}

Create Outgoing Integration to Binder

Add outgoing integration identified by {binder_id}.

POST /{binder_id}/integrations

Moxtra pushes the event information to the endpoint URL set in the "outgoing_url" using POST method with Content-Type: application/json and the event information is based on the configured action event which gets triggered. Configurable events are as follows:

  • comment_posted - when a comment is generated on a Chat or a Todo
  • comment_posted_on_page - when a comment is generated on a Page
  • page_created - when a page is generated in a Binder
  • page_annotated - when an annotation is generated on a Page
  • file_uploaded - when a file is upload onto a Chat, a Binder or a Todo
  • todo_created - when a todo task gets generated
  • todo_completed - when a todo task is completed
  • meet_recording_ready - when a meet recording is ready in the Binder where the Meet starts
The sample outgoing message looks like below:
{
	"message_id": "2889",
	"message_type": "comment_posted",
	"binder_id": "BAGUChIRH7P7eBdR9h9nyR5",
	"callback_url": "https://api.moxtra.com/webhooks/CAEqBS8wcXkzehdCQUdVQ2hJUkg3UDdlQmRSOWg5bnlSNYABvBaQAxQ",
	"event": {
		"timestamp": "2016-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 third-party. If there is information the third-party wants to return, the third-party has to make a request back on the endpoint specified in the "callback_url" with the following mechanism:
  • POST request with Content-Type: application/x-www-form-urlencoded and set key-value pairs as follows:
    key1=value1&key2=value2&...

    or set "payload" parameter as shown below:
    payload=This is a line of text in a binder.\nAnd this is another line of text.
  • POST request with Content-Type: application/json and set the content body as follows:
    { "text": "This is a line of text in a binder.\nAnd this is another line of text." }

    or
    { 
        "key1": "value1",
        "key2": "value2",
        ...
      }

JSON Parameters
Name Type Description
service String "outgoing" as the service name.
name String Optional: customized name for this integration.
description String Optional: description for this integration.
disabled Boolean Optional: true to disable, false to enable.
outgoing_url (In outgoing) String The endpoint URL of the 3rd party for the outgoing webhook to invoke.
comment_posted (In outgoing) Boolean Optional: "Comment Posted" event for the outgoing service.
comment_posted_on_page (In outgoing) Boolean Optional: "Comment Posted On Page" event for the outgoing service.
page_created (In outgoing) Boolean Optional: "Page Created" event for the outgoing service.
page_annotated (In outgoing) Boolean Optional: "Page Annotated" event for the outgoing service.
file_uploaded (In outgoing) Boolean Optional: "File Uploaded" event for the outgoing service.
todo_created (In outgoing) Boolean Optional: "Todo Created" event for the outgoing service.
todo_completed (In outgoing) Boolean Optional: "Todo Completed" event for the outgoing service.
meet_recording_ready (In outgoing) Boolean Optional: "Meet Recording Ready" event for the outgoing service.
Sample Request for the outgoing service
POST /B7V4ze37oO08PYO70973lX6/integrations
{
    "service": "outgoing",
    "description": "Outgoing integration",
    "outgoing": {
    	"outgoing_url": "https://test.webhooks.com/moxtra",
    	"comment_posted": true,
    	"file_uploaded": true
    }
}
Sample Response for the outgoing service
{
    "code": "RESPONSE_SUCCESS",
    "data": {
        "id": "69",
        "webhook_url": "https://api.moxtra.com/webhooks/CAEqBXhkdSSDAehdCeTBtQzhPM3IwRUkwSUM4TVdzaE93NYABBJADFA",
        "service": "outgoing",
        "action": "chat",
        "description": "Outgoing integration",
        "disabled": false,
        "created_time": 1342813061602,
        "updated_time": 1342813061602
    }
}

Get Binder Integrations

Get the integrations in a binder identified by {binder_id}.

GET /{binder_id}/integrations

Sample Request
GET /BRTaH8slmbPAY4odz0RbBIF/integrations
Sample Response
{
    "code": "RESPONSE_SUCCESS",
    "data": {
        "binder_id": "BRTaH8slmbPAY4odz0RbBIF",
        "count": 2,
        "integrations": [
            {
                "webhook_url": "https://api.moxtra.com/webhooks/CAEqBUsrSXdxehdCMzRncTQ5MWdrakZqYXshUlc1eFFrQ4ABTJADFA",
                "id": "313",
                "service": "github",
                "action": "chat",
                "description": "Test",
                "disabled": false,
                "updated_time": 1414713251918,
                "created_time": 1414713251914
            },
            {
                "webhook_url": "https://api.moxtra.com/webhooks/CAEqBVlIU0doehdCb2wyVGhzU3Jyb0Z0JsoENWcxUWVsSIABuwKQAxQ",
                "id": "315",
                "service": "outgoing",
                "action": "chat",
                "description": "",
                "disabled": false,
                "updated_time": 1414715708597,
                "created_time": 1414715708593,
                "outgoing": {
                	"outgoing_url": "https://github.com/test/moxtra",
                	"comment_posted": true,
                	"comment_posted_on_page": true,
                	"page_created": true,
                	"file_uploaded": true,
                	"page_annotated": false,
                	"todo_created": true,
                	"meet_recording_ready": false,
                	"todo_completed": false
                }            
            }
        ]        
    }
}

Enable/Disable Integration

Enable/Disable an integration in the binder identified by {binder_id} & {integration_id}.

POST /{binder_id}/integrations/{integration_id}

JSON Parameters
Name Type Description
disabled Boolean true to disable, false to enable.
Sample Request
POST /B7V4ze37oO08PYO70973lX6/integrations/24
{
    "disabled": true
}
Sample Response
{
    "code": "RESPONSE_SUCCESS"
    }
}

Upload Avatar

Upload an avatar file to the integration in the binder identified by {binder_id} & {integration_id} via multipart/form-data.

POST /{binder_id}/integrations/{integration_id}/upload

Form-data Parameters
Name Type Description
file file Actual avatar (128 x 128px) file that is uploaded to the integration.

Sample Request
POST /B7V4ze37oO08PYO70973lX6/integrations/24/upload
...
Content-Type: multipart/form-data; boundary=---------------------------9051914041544843365972754266
Content-Length: 3234

-----------------------------9051914041544843365972754266
Content-Disposition: form-data; name="file"; filename="incoming.png"
Content-Type: images/png

Content of incoming.png
Sample Response
{
    "code": "RESPONSE_SUCCESS"
}

Delete Integration in Binder

Delete an integration in the binder identified by {binder_id} & {integration_id}.

DELETE /{binder_id}/integrations/{integration_id}

Sample Request
DELETE /B7V4ze37oO08PYO70973lX6/integrations/24
Sample Response
{
    "code": "RESPONSE_SUCCESS"
}