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.
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
Authorization | string You can either pass your master token here or user token of an end user. Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521 |
OK - returns an elements
array which contains the name
and version
(required for Get service environments Get connector operations and Call connector)
Array of objects (PublicConnector) Contains all connector details |
Invalid input
Unauthorized - Verify the token validity
Forbidden
Not found
Limit exceeded
Internal error
{- "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."
}
]
}
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.
Authorization | string You can either pass your master token here or user token of an end user. Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521 |
OK - Returns an elements
array which contains the input schema for Call connector
Array of objects (PublicConnectorOperation) |
Invalid input
Unauthorized - Verify the token validity
Forbidden
Not found
Limit exceeded
Internal error
{- "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"
],
}, - "title": "Send Message",
- "description": "Send a message to a user or channel.",
- "outputSchema": {
- "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": {
- "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",
- "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"
}
}
}
}
]
}
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.
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. Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521 |
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 |
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)
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.
Unauthorized - Verify the token validity
Forbidden
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
Limit exceeded
Internal error
{- "operation": "send_message",
- "authId": "fe6ce53d-b414-4f24-b0d5-16a0a75544a0",
- "input": {
- "channel": "<aChannel>",
- "text": "aText"
}
}
{- "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>"
}
}
}