Core

Connectors

Connectors expose the API operations of the third party services that you will be integrating with Tray.

If you were building an integration between Salesforce and Slack, you would need both Salesforce and Slack connectors. You will use the relevant operations on both connectors to build the integration.

What's a service inside the connector object?

A Tray connector essentially exposes underlying third party APIs (ex. a Salesforce connector has a corresponding Salesforce service in Tray). The service object contains the details about the service attached to the connector.

Different versions of the connectors may use different service versions. As third party services update their APIs, new service and it's associated connector is added to Tray.

Tray regularly deprecates services and the connectors that use those services regularly. Unless you specififcally want to use the old APIs of a third party service, you should go with the latest service and the latest connector version associated to it.

List Connectors

This endpoint is non-billable.

Returns a list with all the available connectors from Tray's connector library.

A connector can have multiple versions. the following key data is returned:

Connector name and version are required inputs for Get connector operations and Call connector.
The service id is required for building the url for the Auth-only dialog

Response Examples

{
  "elements": [
    {
      "title": "Slack",
      "description": "Slack connector",
      "name": "slack",
      "service": {
        "id": "3e21b055-1597-40ae-bcc2-72af0843b283",
        "name": "slack",
        "version": 4
      },
      "version": "9.0"
    },
    {
      "name": "twilio-output",
      "description": "Cloud communication platform for developers",
      "service": {
        "id": "55d1154c-4fd8-4c2c-ba22-041deabfcbfd",
        "name": "twilio",
        "version": 1
      },
      "version": "2.1",
      "title": "Twilio"
    },
    {
      "name": "shopify",
      "service": {
        "id": "e0b2cbd7-657d-4917-8362-31d028968e0b",
        "name": "shopify",
        "version": 4
      },
      "title": "Shopify",
      "version": "4.1",
      "description": "Shopify gives you everything you need to build a successful online business."
    }
  ]
}

Call Connector

This endpoint is billable. Every call to this endpoint is billed as one task.

Executes an operation of a connector and returns the result as the response.

The input is a regular json object that must fit the input schema of the operation as retrieved from Get connector operations.
The authId field should be the id of a previously created authentication. The output is also a regular json object containing the response from the 3rd party.
The outcome field indicates whether or not the execution was successful.

Note:

For error handling, please refer to Error Handling (Tray) and Error Handling (3rd Party).
For handling paginated results by 3rd party, refer this guide.

Request Example

Request Examples

{
  "operation": "send_message",
  "authId": "fe6ce53d-b414-4f24-b0d5-16a0a75544a0",
  "input": {
    "channel": "",
    "text": "aText"
  }
}

Response Examples

{
  "outcome": "success",
  "output": {
    "ok": true,
    "channel": "",
    "ts": "1654555157.195399",
    "message": {
      "username": "",
      "text": "test",
      "type": "message",
      "ts": "1654555157.195399",
      "app_id": "",
      "subtype": "bot_message",
      "bot_id": ""
    }
  }
}

List Connector Operations

This endpoint is non-billable.

Returns a list with all the available operations for a given connector

Each connector operation has an input and output schema that can be used by a frontend to build a form or validate data.

You can then use the schema to correctly construct your inputs for the 'Call connector' operation.

Response Examples

{
  "elements": [
    {
      "name": "send_message",
      "inputSchema": {
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The workspace id that has the channel where the reminder will be sent",
            "title": "Workspace",
            "lookup": {
              "message": "list_workspaces_ddl",
              "input": {}
            }
          },
          "description": {
            "type": "string",
            "description": "The description of the reminder",
            "title": "Description"
          },
          "time": {
            "type": "string",
            "description": "When this reminder should happen. Some examples that work: 1458678068, 20, in 5 minutes, tomorrow, at 3:30pm, on Tuesday, or next week.",
            "title": "Time"
          },
          "channel_id": {
            "type": "string",
            "title": "Channel",
            "description": "The ID of the channel where the reminder will be sent",
            "lookup": {
              "message": "list_channels_ddl",
              "input": {
                "include_private_channels": false,
                "workspace_id": "{{{workspace_id}}}"
              }
            }
          },
          "message": {
            "type": "string",
            "description": "The content of the reminder",
            "title": "Message"
          }
        },
        "required": [
          "message",
          "time",
          "channel_id"
        ],
        "type": "object",
        "additionalProperties": false,
        "advanced": [
          "description"
        ],
        "$schema": "https://api.tray.io/core/v1/connectors/operations/input-schema#"
      },
      "title": "Send Message",
      "description": "Send a message to a user or channel.",
      "outputSchema": {
        "$schema": "https://api.tray.io/core/v1/connectors/operations/output-schema#",
        "type": "object",
        "properties": {
          "reminder_id": {
            "type": "string",
            "description": "The content of the reminder",
            "title": "Message"
          }
        }
      },
      "hasDynamicOutput": false,
      "authScopes": [
        "chat:write:bot",
        "chat:write:user",
        "channels:write",
        "channels:read"
      ]
    },
    {
      "title": "Send Reminder",
      "hasDynamicOutput": false,
      "outputSchema": {
        "$schema": "https://api.tray.io/core/v1/connectors/operations/output-schema#",
        "type": "object",
        "properties": {
          "reminder_id": {
            "type": "string",
            "description": "The content of the reminder",
            "title": "Message"
          }
        }
      },
      "name": "send_reminder",
      "authScopes": [
        "reminder:send"
      ],
      "description": "Periodically sends a reminder to a channel",
      "inputSchema": {
        "additionalProperties": false,
        "type": "object",
        "$schema": "https://api.tray.io/core/v1/connectors/operations/input-schema#",
        "advanced": [
          "description"
        ],
        "required": [
          "message",
          "time",
          "channel_id"
        ],
        "properties": {
          "workspace_id": {
            "type": "string",
            "description": "The workspace id that has the channel where the reminder will be sent",
            "title": "Workspace",
            "lookup": {
              "message": "list_workspaces_ddl",
              "input": {}
            }
          },
          "channel_id": {
            "type": "string",
            "title": "Channel",
            "description": "The ID of the channel where the reminder will be sent",
            "lookup": {
              "message": "list_channels_ddl",
              "input": {
                "include_private_channels": false,
                "workspace_id": "{{{workspace_id}}}"
              }
            }
          },
          "time": {
            "type": "string",
            "description": "When this reminder should happen. Some examples that work: 1458678068, 20, in 5 minutes, tomorrow, at 3:30pm, on Tuesday, or next week.",
            "title": "Time"
          },
          "description": {
            "type": "string",
            "description": "The description of the reminder",
            "title": "Description"
          },
          "message": {
            "type": "string",
            "description": "The content of the reminder",
            "title": "Message"
          }
        }
      }
    }
  ]
}