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
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": "zendesk",
                        "action": "page",
                        "description": "",
                        "disabled": false,
                        "updated_time": 1414715708597,
                        "created_time": 1414715708593
                    }
                ]
            },
            {
                "binder_id": "By0mC8O3r0EI0UXSMWshOw5",
                "count": 1,
                "integrations": [
                    {
                        "webhook_url": "https://api.moxtra.com/webhooks/CAEqBXhkdSSDAehdCeTBtQzhPM3IwRUkwSUM4TVdzaE93NYABBJADFA",
                        "id": "15",
                        "service": "jira",
                        "action": "todo",
                        "description": "",
                        "disabled": false,
                        "updated_time": 1414798605588,
                        "created_time": 1414798605577
                    }
                ]
            }
        ]
    }
}
          

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",
    	    ...
    	}
        }	    
      }

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": "76",
                "service": "jira",
                "action": "page",
                "description": "jira 1",
                "disabled": false,
                "updated_time": 1420358925820,
                "created_time": 1420358925817
            },
            {
                "webhook_url": "https://api.moxtra.com/webhooks/CAEqBUU2VmFVehdCMzRncTQ5MWSYHsZqYm1PUlc1eFFrQ4ABTpADFA",
                "id": "78",
                "service": "jira",
                "action": "todo",
                "description": "jira 2",
                "disabled": false,
                "updated_time": 1420360295781,
                "created_time": 1420360295777
            }
        ]
    }
}

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"
}