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.

Get Connectors

get/core/v1/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:

SecuritybearerAuth
Request
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - returns an elements array which contains the name and version
(required for Get service environments Get connector operations and Call connector)

Response Schema: application/json
Array of objects (PublicConnector)

Contains all connector details

400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found

429

Limit exceeded

500

Internal error

Request samples 
Response samples 
application/json
{
  • "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."
      }
    ]
}
Get Connector Operations
get/core/v1/connectors/{connector-name}/versions/{connector-version}/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.


SecuritybearerAuth 
Request 
path Parameters
connector-name
required
string
The name of the connector


 
 Example:  slack
connector-version
required
string
The version of the connector


 
 Example:  9.1
header Parameters
Authorization
string
You can either pass your master token here or user token of an end user.


 
 Example:  Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses 
200
OK - Returns an elements array which contains the input schema for Call connector


Response Schema: application/json
Array of objects (PublicConnectorOperation) 
 
400
Invalid input


401
Unauthorized - Verify the token validity


403
Forbidden


404
Not found


429
Limit exceeded


500
Internal error


Request samples 
Response samples 
application/json
{
  • "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": {},
      • "hasDynamicOutput": false,
      • "authScopes": [
        • "chat:write:bot",
        • "chat:write:user",
        • "channels:write",
        • "channels:read"
        ]
      },
    • {
      • "title": "Send Reminder",
      • "hasDynamicOutput": false,
      • "outputSchema": {},
      • "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"
            }
          }
        }
      }
    ]
}
Call Connector
post/core/v1/connectors/{connector-name}/versions/{connector-version}/call

    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.


For error handling, please refer to Error Handling (Tray) and Error Handling (3rd Party).


For handling paginated results by 3rd party, refer this guide.


SecuritybearerAuth 
Request 
path Parameters
connector-name
required
string
The name of the connector retrieved from Get connectors


 
 Example:  slack
connector-version
required
string
The version of the connector retrieved from Get connectors


 
 Example:  9.1
header Parameters
Authorization
string
This must be a user token to call the connector on behalf of an end user. Note that authID must belong to the end user whose user token is being used. 
 If master token is used, you would essentially be calling the connector from your Tray account. Note that authID must belong to your account.


 
 Example:  Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Request Body schema: application/json
required
operation
required
string
The name of the operation obtained using Get connector operations


 
authId
string <uuid> 
The End User-specific auth id obtained when using Create user authentication


 
required
object
The exact schema of inputs must be retrieved from Get connector operations


 
returnOutputSchema
boolean
Only applicable if Get connector operations has returned true for hasDynamicOutput - indicating that the output changes depending on the input


 
Responses 
200
OK - will return either success or error from the 3rd party.  
 A success response will include all relevant data including pagination tokens etc. if relevant.  
 An error response will include details of e.g. 429, 401, 404 from 3rd party (note that this is not currently in standardized format)


Response Schema: application/json
outcome
required
string (PublicConnectorCallResultOutcome) 
 Enum: "success" "error"  
required
object
 
400
Invalid input - Use Get connector operations to find correct schema.  
 You can also use the Operations explorer tool to quickly find the input schema.  
 Finally, you can use the Form builder app to see input schema getting generated live as you fill the form.


401
Unauthorized - Verify the token validity


403
Forbidden


404
Not found - Indicates incorrect connector name, connector version, or auth id
Use Get Connectors to retrieve correct service details and Get User Auths to check auth exists


429
Limit exceeded


500
Internal error


Request samples 
application/json
{
  • "operation": "send_message",
  • "authId": "fe6ce53d-b414-4f24-b0d5-16a0a75544a0",
  • "input": {
    • "channel": "<aChannel>",
    • "text": "aText"
    }
}
Response samples 
application/json
{
  • "outcome": "success",
  • "output": {
    • "ok": true,
    • "channel": "<aChannel>",
    • "ts": "1654555157.195399",
    • "message": {
      • "username": "<defaultUsername>",
      • "text": "test",
      • "type": "message",
      • "ts": "1654555157.195399",
      • "app_id": "<anAppId>",
      • "subtype": "bot_message",
      • "bot_id": "<aBotId>"
      }
    }
}