@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
md 310 lines 9.41 KB
Rendered Raw
1 # Triggers
2
3 The Triggers API allows you to manage and subscribe to real-time events from your connected accounts. This guide explains how to work with triggers using the Composio SDK.
4
5 ## Overview
6
7 Triggers are real-time events that occur in your connected accounts. The SDK provides methods to:
8
9 - List active triggers
10 - Create new trigger instances
11 - Update existing triggers
12 - Enable/disable triggers
13 - Subscribe to real-time trigger events
14 - Manage trigger types
15
16 ## Methods
17
18 ### List Active Triggers
19
20 Fetch a list of all active triggers with optional filtering:
21
22 ```typescript
23 const triggers = await composio.triggers.listActive({
24 authConfigIds: ['auth-config-id'],
25 connectedAccountIds: ['connected-account-id'],
26 limit: 10,
27 cursor: 'cursor-string', // Use cursor for pagination
28 showDisabled: false,
29 triggerIds: ['trigger-id'],
30 triggerNames: ['trigger-name'],
31 });
32 ```
33
34 ### Create Trigger Instance
35
36 Create a new trigger instance for a specific user and trigger type. The trigger instance version is determined by the global `toolkitVersions` configuration set during Composio initialization (defaults to `'latest'`). If a connected account ID is not provided, the backend resolves the first active connection for the user and toolkit.
37
38 **With Connected Account ID:**
39
40 ```typescript
41 const trigger = await composio.triggers.create('default', 'GMAIL_NEW_GMAIL_MESSAGE', {
42 connectedAccountId: 'ca_jjYIG9L40LDIS', // Specify which connected account to use
43 triggerConfig: {
44 labelIds: 'INBOX',
45 userId: 'me',
46 interval: 60,
47 },
48 });
49 ```
50
51 **Without Connected Account ID (Using First Available):**
52
53 ```typescript
54 const trigger = await composio.triggers.create('default', 'GMAIL_NEW_GMAIL_MESSAGE', {
55 triggerConfig: {
56 labelIds: 'INBOX',
57 userId: 'me',
58 interval: 60,
59 },
60 }); // The backend resolves the first active connection for the user and toolkit
61 ```
62
63 > **Note:** It's recommended to provide a `connectedAccountId` when you have multiple connected accounts for the same toolkit to ensure the trigger is created for the intended account. If not provided, the backend resolves the first active connection for the user and toolkit (ordered by most recently created).
64
65 **Parameters:**
66
67 - `userId` (string, required): The ID of the user to create the trigger instance for
68 - `slug` (string, required): The slug of the trigger type to create
69 - `body` (TriggerInstanceUpsertParams, optional): Configuration for the trigger instance
70 - `connectedAccountId` (string, optional): ID of the connected account to use. If not provided, the backend resolves the first active connection for the user and toolkit
71 - `triggerConfig` (object, optional): Trigger-specific configuration parameters
72
73 **Returns:** Promise<TriggerInstanceUpsertResponse> - The created trigger instance with the following structure:
74
75 ```typescript
76 {
77 triggerId: string; // The ID of the created trigger instance
78 }
79 ```
80
81 **Behavior:**
82
83 - The method uses the global toolkit version configured in the Composio client (defaults to `'latest'`)
84 - To use a specific toolkit version for trigger creation, configure `toolkitVersions` when initializing the Composio instance
85 - See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
86
87 **Throws:**
88
89 - `ValidationError`: If `userId` is empty or the provided parameters are invalid
90 - `ComposioTriggerTypeNotFoundError`: If the trigger type with the given slug is not found
91
92 > **Note:** Connection resolution now happens on the backend. If no active connection exists for the user and toolkit — or a pinned `connectedAccountId` is invalid — the upsert call rejects with the backend error, not a client-side `ComposioConnectedAccountNotFoundError`.
93
94 **Example with Specific Toolkit Version:**
95
96 ```typescript
97 // Configure toolkit versions at initialization
98 const composio = new Composio({
99 apiKey: 'your-api-key',
100 toolkitVersions: {
101 gmail: '12082025_00',
102 github: '10082025_01'
103 }
104 });
105
106 // Now create will use the configured version for Gmail
107 const trigger = await composio.triggers.create('default', 'GMAIL_NEW_GMAIL_MESSAGE', {
108 connectedAccountId: 'ca_jjYIG9L40LDIS',
109 triggerConfig: {
110 labelIds: 'INBOX',
111 userId: 'me',
112 interval: 60,
113 },
114 });
115 // This will create the trigger instance using version '12082025_00' for Gmail
116 ```
117
118 **Example with Error Handling:**
119
120 ```typescript
121 try {
122 const trigger = await composio.triggers.create('default', 'GMAIL_NEW_GMAIL_MESSAGE', {
123 // Connected account ID is optional - if not provided, will use first available
124 connectedAccountId: 'ca_jjYIG9L40LDIS',
125 triggerConfig: {
126 labelIds: 'INBOX',
127 userId: 'me',
128 interval: 60,
129 },
130 });
131 console.log('Trigger created:', trigger.triggerId);
132 } catch (error) {
133 if (error instanceof ComposioTriggerTypeNotFoundError) {
134 console.error('Trigger type not found:', error.message);
135 // Handle invalid trigger type
136 } else if (error instanceof ValidationError) {
137 console.error('Invalid parameters:', error.message);
138 // Handle validation errors
139 } else {
140 // Connection problems now surface here as backend errors, for example when
141 // no active connection exists for the user and toolkit, or the pinned
142 // connectedAccountId is invalid.
143 console.error('Unexpected error:', error);
144 // Handle other errors
145 }
146 }
147 ```
148
149 ### Update Trigger Instance
150
151 Update an existing trigger instance:
152
153 ```typescript
154 const updatedTrigger = await composio.triggers.update('trigger-id', {
155 // Updated configuration
156 });
157 ```
158
159 ### Enable/Disable Triggers
160
161 Control trigger activation state:
162
163 ```typescript
164 // Disable a trigger
165 await composio.triggers.disable('trigger-id');
166
167 // Enable a trigger
168 await composio.triggers.enable('trigger-id');
169 ```
170
171 ### Real-time Trigger Subscription
172
173 Subscribe to real-time trigger events with optional filtering:
174
175 ```typescript
176 composio.triggers.subscribe(
177 triggerData => {
178 console.log('Received trigger:', triggerData);
179 },
180 {
181 toolkits: ['toolkit-name'],
182 triggerId: 'specific-trigger-id',
183 connectedAccountId: 'connected-account-id',
184 triggerSlug: ['trigger-type'],
185 triggerData: 'custom-data',
186 userId: 'user-id',
187 }
188 );
189 ```
190
191 #### Trigger Payload Format
192
193 When you receive a trigger event, the payload will have the following structure:
194
195 ```typescript
196 interface IncomingTriggerPayload {
197 id: string; // Unique trigger instance ID
198 triggerSlug: string; // Type of trigger
199 toolkitSlug: string; // Associated toolkit
200 userId: string; // User ID associated with the trigger
201 payload: unknown; // Processed trigger payload
202 originalPayload: unknown; // Raw trigger payload
203 metadata: {
204 id: string;
205 triggerConfig: unknown; // Trigger configuration
206 triggerSlug: string;
207 toolkitSlug: string;
208 triggerData: string;
209 connectedAccount: {
210 id: string; // Connected account nano ID
211 uuid: string; // Connected account UUID
212 authConfigId: string; // Auth config nano ID
213 authConfigUUID: string; // Auth config UUID
214 userId: string; // User ID
215 status: string; // Connection status
216 };
217 };
218 }
219 ```
220
221 ### Unsubscribe from Triggers
222
223 Stop receiving trigger events:
224
225 ```typescript
226 await composio.triggers.unsubscribe();
227 ```
228
229 ### Manage Trigger Types
230
231 #### List Trigger Types
232
233 List all available trigger types with optional filtering:
234
235 ```typescript
236 const triggerTypes = await composio.triggers.listTypes({
237 toolkits: ['github'],
238 cursor: 'cursor-string',
239 limit: 10
240 });
241 ```
242
243 **Parameters:**
244
245 - `toolkits` (string[], optional): Filter trigger types by toolkit slugs
246 - `cursor` (string, optional): Pagination cursor for fetching the next page
247 - `limit` (number, optional): Maximum number of trigger types to return
248
249 **Returns:** Promise<TriggersTypeListResponse> - A paginated list of trigger types
250
251 #### Get Trigger Type
252
253 Retrieve details of a specific trigger type by its slug. The trigger type version is determined by the global `toolkitVersions` configuration set during Composio initialization.
254
255 ```typescript
256 // Get trigger type using the globally configured toolkit version
257 const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
258 ```
259
260 **Parameters:**
261
262 - `slug` (string, required): The slug of the trigger type to retrieve
263
264 **Returns:** Promise<TriggersTypeRetrieveResponse> - The trigger type object containing details such as:
265
266 ```typescript
267 {
268 slug: string;
269 name: string;
270 description: string;
271 toolkit: {
272 slug: string;
273 name: string;
274 };
275 // ... other trigger type properties
276 }
277 ```
278
279 **Behavior:**
280
281 - The method uses the global toolkit version configured in the Composio client (defaults to `'latest'` if not provided)
282 - To use a specific toolkit version, configure `toolkitVersions` when initializing the Composio instance
283 - See [Toolkit Versions Configuration](../getting-started.md#toolkit-versions) for details on setting toolkit versions
284
285 **Example with Specific Toolkit Version:**
286
287 ```typescript
288 // Configure toolkit versions at initialization
289 const composio = new Composio({
290 apiKey: 'your-api-key',
291 toolkitVersions: {
292 gmail: '12082025_00',
293 github: '10082025_01'
294 }
295 });
296
297 // Now getType will use the configured version for Gmail
298 const triggerType = await composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE');
299 // This will fetch the trigger type using version '12082025_00' for Gmail
300 ```
301
302 #### Get Trigger Enums
303
304 Fetch the list of all available trigger enums:
305
306 ```typescript
307 const triggerEnum = await composio.triggers.listEnum();
308 ```
309
310 This method returns an enumeration of all available trigger types and is primarily used by the CLI.