> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # Invoke # Package: actions # Namespace: ActionProviderService # Method link: https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/invoke.md ## Introduction Runs your action. Wix calls Invoke when an automation that uses your action is triggered. The request includes parameters as specified in the action's [input schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/the-action-input-schema.md), as well as metadata about the current automation run. If your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), return your action's output parameters. Your action can return its results immediately, or it can tell Wix to wait for your action to complete by [specifying a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/introduction.md#action-timeouts) and calling [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) to let Wix know that the action has completed. > **Note**: When your response includes a timeout, save the `activationContext.invocationToken` and include it in your call to Report Action Invocation Completed. This ensures that Wix associates your action's results with the correct automation run. --- ## REST API ### Schema ``` Method: invoke Description: Runs your action. Wix calls Invoke when an automation that uses your action is triggered. The request includes parameters as specified in the action's [input schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/the-action-input-schema.md), as well as metadata about the current automation run. If your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), return your action's output parameters. Your action can return its results immediately, or it can tell Wix to wait for your action to complete by [specifying a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/introduction.md#action-timeouts) and calling [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) to let Wix know that the action has completed. > **Note**: When your response includes a timeout, save the `activationContext.invocationToken` and include it in your call to Report Action Invocation Completed. This ensures that Wix associates your action's results with the correct automation run. URL: null Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: actionParams, actionKey Method parameters: param name: actionKey | type: actionKey | description: Action key specified when you [added the action to your app](https://dev.wix.com/docs/api-reference/business-management/automations/actions/add-an-action-to-your-app.md). | required: true param name: actionParams | type: actionParams | description: Action parameters as specified in your action's [input schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/the-action-input-schema.md). Wix validates the parameters it sends against your action's schema, so you don't need to validate them yourself. | required: true param name: activationContext | type: ActivationContext - name: activationId | type: string | description: Activation GUID. Wix uses this to identify the current automation run. - name: triggerKey | type: string | description: Trigger key you specified when you [added the trigger to your app](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/add-a-trigger-to-your-app.md). - name: triggerAppId | type: string | description: [GUID of the app](https://dev.wix.com/docs/build-apps/get-started/overview/glossary.md#app-id) that set up the trigger. Learn more about [adding a trigger to your app](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/add-a-trigger-to-your-app.md). - name: actionId | type: string | description: GUID of the action in the current automation. Learn more about [configuring your action](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/configure-your-automation.md#configuring-actions). - name: payload | type: object | description: Full aggregated payload passed to the action being invoked. The payload includes the complete [trigger payload](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/the-trigger-payload-schema.md) as well as any additional [output parameters](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema) passed from previous actions. Learn more about Wix Automations [architecture and data flow](https://dev.wix.com/docs/api-reference/business-management/automations/architecture-data-flow.md). - name: actionAppId | type: string | description: [GUID of the app](https://dev.wix.com/docs/build-apps/get-started/overview/glossary.md#app-id) that set up the action. Learn more about [adding an action to your app](https://dev.wix.com/docs/api-reference/business-management/automations/actions/add-an-action-to-your-app.md). - name: invocationToken | type: string | description: Invocation token. When your action [includes a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/introduction.md#action-timeouts), specify this token when you call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) to let Wix know that the action has completed. This ensures that Wix associates your action's results with the correct automation run. Learn more about [running an invoked action with a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/sample-flow.md#run-an-invoked-action-with-a-timeout). - name: activationSourceInfo | type: ActivationInitiationSourceInfo | description: Information about how this activation was initiated (e.g., event-driven or manual activation) - ONE-OF: - name: manualActivationInfo | type: ManualActivationInfo | description: Details for MANUAL_ACTIVATION source. - name: testMode | type: boolean | description: Whether this activation is running in test mode. In test mode: - Draft automations can be executed - Certain actions may be skipped (e.g., delays, rate limits) - Used primarily for testing automations before publication Default: false (standard production mode) - name: rerunActivationInfo | type: RerunActivationInfo | description: Details for RERUN_ACTIVATION source. - name: originalActivationId | type: string | description: The activation GUID of the original activation being rerun. - name: skipDelays | type: boolean | description: When true, delay actions will be skipped during the rerun. - name: activationInitiationSource | type: ActivationInitiationSource | description: The source type of this activation. - enum: - TRIGGER_PROVIDER_EVENT: Activation triggered by a provider event (e.g., reportEvent, bulkReportEvent). The automation runs in response to a business event. Uses published automations only. - MANUAL_ACTIVATION: Activation triggered by manual execution (e.g., testAutomation, ReRunAutomation). Explicitly initiated by user or API caller with explicit payload. - RERUN_ACTIVATION: Activation triggered by re-running a previous activation. - name: initiatorInfo | type: InitiatorInfo | description: Information about the user who initiated the activation. - name: initiatorUserId | type: string | description: The user GUID of the initiator. - name: wixEmployee | type: boolean | description: Whether the initiating user is a Wix employee. - name: preinstalledInfo | type: PreinstalledInfo | description: Information about the preinstalled automation, if applicable. - name: appId | type: string | description: GUID of the app that added the preinstalled automation. - name: componentId | type: string | description: App component GUID of the preinstalled automation. - name: forceSync | type: boolean | description: Whether this invocation is in force-sync mode (e.g., from a Functions automation). Return type: InvokeResponse - ONE-OF: - name: timeoutLengthOptions | type: TimeoutLengthOptions | description: Required when `InvokeTimeoutType` is `TIMEOUT_LENGTH`. The length of time that Wix waits for your action to complete. - name: timeoutInMinutes | type: integer | description: Time in minutes Wix waits for your action to complete. > **Note**: You can specify a maximum timeout period in minutes of up to 24 hours. - name: timeoutDateOptions | type: TimeoutDateOptions | description: Required when `InvokeTimeoutType` is `TIMEOUT_DATE`. The date until which Wix waits for your action to complete. - name: timeoutDate | type: string | description: Timeout date. Wix waits until this date for your action to complete. > **Note**: You can specify a timeout date up to 1 year from the current date. - name: result | type: object | description: Your action's results. When your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), return an object with the action's output parameters in the structure specified by the output schema. Otherwise, return an empty object. - name: invokeTimeoutType | type: InvokeTimeoutType | description: Timeout period between when Wix invokes your action and when it continues to the next step in the automation. You can tell Wix to continue immediately, wait a specified amount of time, or wait until a certain date. When you want Wix to continue immediately to the next step in the automation, specify `IMMEDIATE`. If your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), include your action's results in `result`. However, when you want Wix to wait for your action to complete, specify `TIMEOUT_LENGTH` or `TIMEOUT_DATE` and their respective options. Then, call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) in that timeout period to let Wix know that the action has completed. If you don't call this method by the end of the period, Wix [marks the action as failed](https://support.wix.com/en/article/wix-automations-understanding-run-logs#understanding-statuses) and continues to the next step in the automation. Default: `IMMEDIATE`. - enum: - UNKNOWN_INVOKE_TIMEOUT_TYPE: - IMMEDIATE: Action completes immediately and Wix can continue to the next step in the automation. - TIMEOUT_LENGTH: Wix waits the specified length of time for your app to call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md). - TIMEOUT_DATE: Wix waits until the specified date for your app to call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md). ``` ### Examples ### Invoke sent by Wix Invoke request with a sample response body ```curl curl -X POST https://provider.example.com/v1/invoke \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "actionParams": { "to": "my@email.com", "subject": "Your registration to 2022 Event is Confirmed", "body": "Hi Jane, you are confirmed for the event" }, "actionKey": "email-client" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.actions.ActionProviderService.invoke(request, metadata) Description: Runs your action. Wix calls Invoke when an automation that uses your action is triggered. The request includes parameters as specified in the action's [input schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/the-action-input-schema.md), as well as metadata about the current automation run. If your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), return your action's output parameters. Your action can return its results immediately, or it can tell Wix to wait for your action to complete by [specifying a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/introduction.md#action-timeouts) and calling [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) to let Wix know that the action has completed. > **Note**: When your response includes a timeout, save the `activationContext.invocationToken` and include it in your call to Report Action Invocation Completed. This ensures that Wix associates your action's results with the correct automation run. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: InvokeRequest - name: actionParams | type: object | description: Action parameters as specified in your action's [input schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/the-action-input-schema.md). Wix validates the parameters it sends against your action's schema, so you don't need to validate them yourself. - name: actionKey | type: string | description: Action key specified when you [added the action to your app](https://dev.wix.com/docs/api-reference/business-management/automations/actions/add-an-action-to-your-app.md). - name: activationContext | type: ActivationContext | description: Activation context that includes metadata about the current automation run. - name: activationId | type: string | description: Activation GUID. Wix uses this to identify the current automation run. - name: triggerKey | type: string | description: Trigger key you specified when you [added the trigger to your app](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/add-a-trigger-to-your-app.md). - name: triggerAppId | type: string | description: [GUID of the app](https://dev.wix.com/docs/build-apps/get-started/overview/glossary.md#app-id) that set up the trigger. Learn more about [adding a trigger to your app](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/add-a-trigger-to-your-app.md). - name: actionId | type: string | description: GUID of the action in the current automation. Learn more about [configuring your action](https://dev.wix.com/docs/api-reference/business-management/automations/automations/automations-v2/configure-your-automation.md#configuring-actions). - name: payload | type: object | description: Full aggregated payload passed to the action being invoked. The payload includes the complete [trigger payload](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/the-trigger-payload-schema.md) as well as any additional [output parameters](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema) passed from previous actions. Learn more about Wix Automations [architecture and data flow](https://dev.wix.com/docs/api-reference/business-management/automations/architecture-data-flow.md). - name: actionAppId | type: string | description: [GUID of the app](https://dev.wix.com/docs/build-apps/get-started/overview/glossary.md#app-id) that set up the action. Learn more about [adding an action to your app](https://dev.wix.com/docs/api-reference/business-management/automations/actions/add-an-action-to-your-app.md). - name: invocationToken | type: string | description: Invocation token. When your action [includes a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/introduction.md#action-timeouts), specify this token when you call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) to let Wix know that the action has completed. This ensures that Wix associates your action's results with the correct automation run. Learn more about [running an invoked action with a timeout](https://dev.wix.com/docs/api-reference/business-management/automations/actions/action-provider-service-plugin/sample-flow.md#run-an-invoked-action-with-a-timeout). - name: activationSourceInfo | type: ActivationInitiationSourceInfo | description: Information about how this activation was initiated (e.g., event-driven or manual activation) - ONE-OF: - name: manualActivationInfo | type: ManualActivationInfo | description: Details for MANUAL_ACTIVATION source. - name: testMode | type: boolean | description: Whether this activation is running in test mode. In test mode: - Draft automations can be executed - Certain actions may be skipped (e.g., delays, rate limits) - Used primarily for testing automations before publication Default: false (standard production mode) - name: rerunActivationInfo | type: RerunActivationInfo | description: Details for RERUN_ACTIVATION source. - name: originalActivationId | type: string | description: The activation GUID of the original activation being rerun. - name: skipDelays | type: boolean | description: When true, delay actions will be skipped during the rerun. - name: activationInitiationSource | type: ActivationInitiationSource | description: The source type of this activation. - enum: - TRIGGER_PROVIDER_EVENT: Activation triggered by a provider event (e.g., reportEvent, bulkReportEvent). The automation runs in response to a business event. Uses published automations only. - MANUAL_ACTIVATION: Activation triggered by manual execution (e.g., testAutomation, ReRunAutomation). Explicitly initiated by user or API caller with explicit payload. - RERUN_ACTIVATION: Activation triggered by re-running a previous activation. - name: initiatorInfo | type: InitiatorInfo | description: Information about the user who initiated the activation. - name: initiatorUserId | type: string | description: The user GUID of the initiator. - name: wixEmployee | type: boolean | description: Whether the initiating user is a Wix employee. - name: preinstalledInfo | type: PreinstalledInfo | description: Information about the preinstalled automation, if applicable. - name: appId | type: string | description: GUID of the app that added the preinstalled automation. - name: componentId | type: string | description: App component GUID of the preinstalled automation. - name: forceSync | type: boolean | description: Whether this invocation is in force-sync mode (e.g., from a Functions automation). Return type: PROMISE - ONE-OF: - name: timeoutLengthOptions | type: TimeoutLengthOptions | description: Required when `InvokeTimeoutType` is `TIMEOUT_LENGTH`. The length of time that Wix waits for your action to complete. - name: timeoutInMinutes | type: integer | description: Time in minutes Wix waits for your action to complete. > **Note**: You can specify a maximum timeout period in minutes of up to 24 hours. - name: timeoutDateOptions | type: TimeoutDateOptions | description: Required when `InvokeTimeoutType` is `TIMEOUT_DATE`. The date until which Wix waits for your action to complete. - name: timeoutDate | type: Date | description: Timeout date. Wix waits until this date for your action to complete. > **Note**: You can specify a timeout date up to 1 year from the current date. - name: result | type: object | description: Your action's results. When your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), return an object with the action's output parameters in the structure specified by the output schema. Otherwise, return an empty object. - name: invokeTimeoutType | type: InvokeTimeoutType | description: Timeout period between when Wix invokes your action and when it continues to the next step in the automation. You can tell Wix to continue immediately, wait a specified amount of time, or wait until a certain date. When you want Wix to continue immediately to the next step in the automation, specify `IMMEDIATE`. If your action has an [output schema](https://dev.wix.com/docs/api-reference/business-management/automations/actions/about-actions.md#the-output-schema), include your action's results in `result`. However, when you want Wix to wait for your action to complete, specify `TIMEOUT_LENGTH` or `TIMEOUT_DATE` and their respective options. Then, call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md) in that timeout period to let Wix know that the action has completed. If you don't call this method by the end of the period, Wix [marks the action as failed](https://support.wix.com/en/article/wix-automations-understanding-run-logs#understanding-statuses) and continues to the next step in the automation. Default: `IMMEDIATE`. - enum: - UNKNOWN_INVOKE_TIMEOUT_TYPE: - IMMEDIATE: Action completes immediately and Wix can continue to the next step in the automation. - TIMEOUT_LENGTH: Wix waits the specified length of time for your app to call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md). - TIMEOUT_DATE: Wix waits until the specified date for your app to call [Report Action Invocation Completed](https://dev.wix.com/docs/api-reference/business-management/automations/triggers/triggered-events/report-action-invocation-completed.md). ``` ### Examples ### invoke ```javascript import { actionProvider } from '@wix/automations/service-plugins'; async function invoke(request,metadata) { const response = await actionProvider.invoke(request,metadata); }; ``` ### invoke (with elevated permissions) ```javascript import { actionProvider } from '@wix/automations/service-plugins'; import { auth } from '@wix/essentials'; async function myInvokeMethod(request,metadata) { const elevatedInvoke = auth.elevate(actionProvider.invoke); const response = await elevatedInvoke(request,metadata); } ``` ### invoke (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { actionProvider } from '@wix/automations/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { actionProvider }, // Include the auth strategy and host as relevant }); async function invoke(request,metadata) { const response = await myWixClient.actionProvider.invoke(request,metadata); }; ``` ---