Scripting in converted Legacy Web Builder Integrations
This guide provides instructions on editing and maintaining existing scripting methods for legacy web builder integrations that have been converted to either the Platform UI or Platform CLI.
Introduction
Note: This guide isn’t for new integrations built in Platform CLI or Platform UI. For new integrations, use the Platform UI or the Platform CLI to build an integration in code.
If you are creating new functionality, check maintaining your converted integration for the best way forward.
Much like Code Mode, Zapier’s Web Builder Scripting was the previous way to allow you to directly manipulate the requests and responses that are exchanged between your app’s API and Zapier. It continues to be supported using both the Platform UI and CLI.
Access and edit scripting
For integrations converted to Platform UI, you can access and edit these scripting methods by:
- Log into the Platform UI.
- Select your integration.
- In the Build section in the left sidebar, click Advanced.
- Click the Legacy Web Builder tab.
For integrations converted to Platform CLI, you can access and edit these scripting methods in the Scripting.js file. Its default location in the root directory of your CLI integration.
Every converted Web Builder integration will have a root module Zap
defined in this Scripting.js file. By default, it is a blank JavaScript object. You add to it by specifying one or more of the available methods. Each method accepts a single variable called bundle
, which is a JSON serializable object. The content of the bundle varies depending on the method you are implementing. The output of your method must also be a serializable object.
Below is an example of implementing a method to be a pass-through:
Note: All code written in the Scripting API must adhere to strict mode, which is a subset of Javascript. Any issues with your code that violate this will be shown in the Scripting API editor with red X marks in the sidebar. The code will run in the current Node.js used for the platform - you can track this here.
Available methods
There are various methods for manipulating requests Zapier makes to your API. Below is the complete list of methods you can use in scripting. You may provide any, all, or none of these methods.
Trigger methods
Many of the trigger methods follow a naming pattern of key + method name, where key is the key given to the trigger when you created it. Below, Zapier uses the convention of KEY
as the placeholder for the trigger’s actual key. For example, if you define a trigger with the key “my_trigger” and want to implement the pre_poll method, you would write a method called my_trigger_pre_poll
.
Polling
KEY_pre_poll
Runs before the request to the polling URL can modify the request before it is sent.
See bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_poll
It runs after Zapier receives a response from the polling URL. Can parse the response to format the data that enters Zapier or throw an exception. Zapier will automatically throw for status codes 4xx and 5xx after the method runs.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_poll
It runs in place of pre_poll and post_poll. When you get a bundle, you are expected to make the request and return a list of results or throw an exception. Zapier will not throw for status codes like 4xx and 5xx automatically!
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
Static and REST hooks
KEY_catch_hook
It runs when Zapier receive a static or subscription hook from your API and can parse the response to format the data that enters Zapier.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
REST hooks and notification REST hooks
pre_subscribe
It runs before Zapier subscribes.
Learn more in bundle.request.
Note: This code is only valid for Zapier’s legacy web builder, and is mostly incompatible with Platform CLI and Platform UI).
post_subscribe
It runs after Zapier subscribes. It is exclusively for storing results that are needed later for pre_unsubscribe.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
pre_unsubscribe
It runs before Zapier unsubscribes.
Learn more in bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
Notification REST hooks
KEY_pre_hook
It runs before the consuming call.
Learn more in bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_hook
It runs after Zapier receive a response from the consuming call and can parse the response to format the data that enters Zapier or throw an exception. Zapier will automatically throw for status codes 4xx and 5xx after the method runs.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
Available to all triggers
KEY_pre_custom_trigger_fields
It runs before the request to the custom field URL (if provided).
Note: Although this method does not end with
result_fields
like there are for actions and searches it does in fact define custom fields and labels for the result (sample) of the trigger and not for its Edit Template step in the Zap editor.
Learn more in bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_trigger_fields
Runs after the response for custom fields is received. Can parse the response to format the data that enters Zapier or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically.
Note: Although this method does not end with
result_fields
like there are for actions and searches it does in fact define custom fields and labels for the result (sample) of the trigger and not for its Edit Template step in the Zap Editor.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
Action Methods
Action methods follow a naming pattern of key + method name, where key is the key given to the action when you created it. Below, Zapier use the convention of KEY
as the placeholder for the action’s actual key. For example, if you define an action with the key “my_action” and you want to implement the pre_write method, you would write a method called my_action_pre_write
.
KEY_pre_write
Runs before the request to the action URL, can modify the request before it is sent.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_write
Runs after Zapier receive a response from the action endpoint, can modify the response or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically. Note: If the action occurs as part of a search-or-create Zap, the output of this method is not exactly what the user sees. In that case, the action will be followed up with a request to fetch the written record, and Zapier will present the user with the output from that follow-up request. If you need to modify the returned data in that scenario, use _post_read_resource
.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_write
Runs in place of pre_write and post_write. You get a bundle and are expected to make the request and return the appropriate response or throw an exception. Zapier will not throw for status codes like 4xx and 5xx automatically! _Note:_ If the action occurs as part of a search-or-create Zap, the output of this method is not exactly what the user sees. In that case, the action will be followed up with a request to fetch the written record, and Zapier will present the user with the output from that follow-up request. If you need to modify the returned data in that scenario, use _post_read_resource
.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_action_fields
Runs before the request to the custom field URL (if provided).
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_action_fields
Runs after the response for custom fields is received. Can parse the response to format the data that enters Zapier or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_action_fields
Allows you to completely take over the handling of retrieving and processing field metadata for custom action fields. Pre- and Post- methods will not be called if you’ve implemented this method. This method will be passed a bundle and must return an array of custom field metadata. If a request to an endpoint fails, you will need to throw an exception - the platform will not do it automatically.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_action_result_fields
It allows you to completely take over the handling of retrieving and processing field metadata for custom fields when users are working with results of your action in the Zap editor. Pre- and Post- methods will not be called if you’ve implemented this method. This method will be passed a bundle and must return an array of custom field metadata. If a request to an endpoint fails, you will need to throw an exception - the platform will not do it automatically.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_action_result_fields
Runs before the request to the custom response fields URL (if provided).
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_action_result_fields
Runs after the response for custom response fields is received. Can parse the response to format the data that enters Zapier or throw an exception exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically.
Search Methods
Search methods follow a naming pattern of key + method name, where key is the key given to the search when you created it. Below, Zapier use the convention of KEY
as the placeholder for the search’s actual key. For example, if you define an search with the key “my_search” and you want to implement the pre_search method, you would write a method called my_search_pre_search
.
KEY_pre_search
Runs before the request to the search URL, can modify the request before it is sent.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_search
Runs after Zapier receive a response from the search endpoint, can modify the response or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically. Note: The output of the method is not exactly what the user sees. Zapier follow searches up with requests for the individual resources and present the user with the output from those follow-up requests. If you wish to modify the number (or ordering) of the search results, use _post_search
. If you wish to modify the data the user sees, use _post_read_resource
. One other thing to be aware of is that searches must return an array of objects, so if your search endpoint returns a single object, you can use this method to wrap your object in an array.
Note we’ll only use the first object in the array for now, so if you can add optional fields to help narrow the search down, it’s a great idea.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_search
Runs in place of pre_search and post_search. You get a bundle and are expected to make the request and return the appropriate response or throw an exception. Zapier will not throw for status codes like 4xx and 5xx automatically! Note: The output of the method is not exactly what the user sees. Zapier follow searches up with requests for the individual resources and present the user with the output from those follow-up requests. If you wish to modify the number (or ordering) of the search results, you can do that inside _search
. If you wish to modify the data the user sees, use _post_read_resource
.
Note we’ll only use the first object in the array for now, so if you can add optional fields to help narrow the search down, it’s a great idea.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_custom_search_fields
Runs before the request to the custom field URL (if provided).
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_search_fields
Runs after the response for custom fields is received. Can parse the response to format the data that enters Zapier or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_search_fields
Allows you to completely take over the handling of retrieving and processing field metadata for custom search action fields. Pre- and Post- methods will not be called if you’ve implemented this method. This method will be passed a bundle and must return an array of custom field metadata. If a request to an endpoint fails, you will need to throw an exception - the platform will not do it automatically.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_custom_search_result_fields
Allows you to completely take over the handling of retrieving and processing field metadata for custom fields when users are working with results of your search action in the Zap editor. Pre- and Post- methods will not be called if you’ve implemented this method. This method will be passed a bundle and must return an array of custom field metadata. If a request to an endpoint fails, you will need to throw an exception - the platform will not do it automatically.
Note: This code is only valid for Zapier’s legacy web builder, and is mostly incompatible with Platform CLI and Platform UI).
KEY_pre_custom_search_result_fields
Runs before the request to the custom search result field URL (if provided)
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_custom_result_search_fields
Runs after the response for custom search result fields is received. Can parse the response to format the data that enters Zapier or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_pre_read_resource
Runs before Zapier do the request to read an individual resource. Use to modify the request before it is sent.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_post_read_resource
Runs after Zapier do the request to read an individual resource. Use to modify the data returned or throw an exception. Zapier will throw for status codes 4xx and 5xx after the method runs automatically.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
KEY_read_resource
Runs in place of pre_read_resource and post_read_resource. You get a bundle and are expected to make the request and return the appropriate response or throw an exception. Zapier will not throw for status codes like 4xx and 5xx automatically!
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
Authentication Methods
pre_oauthv2_token
Modify the request we’d send to the access token endpoint.
Be aware that for legacy reasons the request does not follow RFC6749 and passes the parameters via the query string. If you define
pre_oauthv2_token
then it is up to you correct this if needed. Without the method, Zapier will retry the request conform standards if the API returns an error on the first attempt.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
post_oauthv2_token
Modify the response from the access token endpoint or throw an exception. Zapier will throw for status codes 4xx and 5xx before the method runs automatically.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
pre_oauthv2_refresh
Modify the request we’d send to the refresh token endpoint. Only use if you have set the auth type for your App to be OAuth V2 with Refresh.
Learn more about bundle.request.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
get_session_info
Zapier exposes a get_session_info()
function for APIs that require any form of session-based authorization. Feel free to use the following skeleton function to inspire your session authorization:
Zapier will only invoke this function on an as-needed basis. It will be called when your API returns a 401 or when you raise an
InvalidSessionException
in yourKEY_post_poll
orKEY_post_write
functions. Zapier will retry the request if the function returns new session info successfully.
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
get_connection_label
Zapier exposes a get_connection_label()
function for APIs that need customization on their Connection Label:
Zapier will only invoke this function after the authentication is tested (when a new account is connected, and when the “test” button is pressed).
Note: This code is only valid for Zapier’s Legacy Web Builder. It’s mostly incompatible with Zapier’s Platform CLI and Platform UI.
Built-in Functions and Tools
Available Libraries
Our scripting engine uses JavaScript. As you’d expect, it provides the standard JavaScript interfaces (JSON, Math, Date and more) as well as $
for jQuery (1.8.3), _
for Underscore (1.4.4), and moment
for Moment.js (2.0.0 with timezone), crypto
, and async
(0.2.9). Plus, it has some handy Zapier specific tools on the z
object!
Note: Do not use Underscore’s collection methods (
_.each()
,_.map()
…) on objects. This will break if the object has alength
property. UseObject.keys(obj, fn)
instead.
Unavailable Objects
Some “common” objects you might expect to find Zapier don’t provide access to include root
, child_process
, Function
, module
, process
, global
, and setInterval
(they’ll be undefined
at runtime).
Making Outbound Requests (z.request)
The z.request
function allows you to make external calls. It performs in a synchronous manner for ease of use, but also provides standard asynchronous features as well if you pass an optional callback.
Usage
- Asynchronous:
z.request(request, [callback])
- Synchronous:
var response = z.request()
Options
request <Object>
: Takes all options for the NPM request package plus some that allow it to accept what most pre-scripting methods receive asbundle.request
:request <Object>
: Means you can also passbundle
and we’ll extractbundle.request
to work with.auth <Array> | <Object>
: Ifauth
is anArray
, it will be transforrmed to{'user':auth[0], 'pass':auth[1]}
to match the package’s HTTP Authentication. If your Zapier app is configured to use Basic Auth thenbundle.request.auth
will be array with 2 elements for the username and password. If it uses Digest Auth then the third element will befalse
. In this case, whenauth[2]
is set, Zapier will setauth.sendImmediately
toauth[2]
and also defaultjar
totrue
since most digest servers require cookies.params <Object>
: Will becomeqs
unless that already exists.data <string>
Will becomebody
unless that already exists. Whilebundle.request.data
will always be aString
, be aware thatbody
also accepts aBuffer
,ReadStream
or - ifjson
is set totrue
- any JSON-serializable object.callback Function ([error], response)
: Will be called on completion, with: -error <Error>
: Any error, when applicable. -response <Object>
: See Response.
Response
You will not receive the full response but a selection from http.IncomingMessage
that matches what most post-scripting methods receive as bundle.response
:
status_code <number>
: The 3-digit HTTP response status code. E.G.404
.headers <Array>
: Key-value pairs of header names (lower-cased) and values.content <string>
: Ifhttp.IncomingMessage.body
is astring
orBuffer
then we’ll wrap it inString()
.
Errors
When you call z.request()
without a callback and an error occurs, it will be thrown. Wrap your call in try/catch
block to handle it.
Example
Let’s call http://httpbin.org/get?hello=world with a header to tell it Zapier like JSON:
Please note that your scripts have 30 seconds, including waiting for and processing any requests. If you need to do lots of extra API calls, especially in a loop, you should look our hydration routine.
Parsing JSON (z.JSON.parse)
The z.JSON.parse
function acts a lot like the native JSON.parse
, but adds some helpful logging and error handling.
z.JSON.parse(string)
, where string
is the string representation of a valid JSON object. An error will be thrown if the structure is invalid.
Hashing
Zapier support both hashing and HMAC hashing.
For output encoding (the encoding
parameter) Zapier defaults to hex
and also support base64
as a parameter value. For input encoding (the input_encoding
parameter) Zapier default to binary
and also support utf8
as a parameter value. You should use utf8
if you expect data to be hashed that may include UTF8 characters.
The following hash algorithms are supported:
DSA-SHA1-old
, dsa
, dsa-sha
, dsa-sha1
, dsaEncryption
, dsaWithSHA
, dsaWithSHA1
, dss1
, ecdsa-with-SHA1
, md4
, md4WithRSAEncryption
, md5
, md5WithRSAEncryption
, mdc2
, mdc2WithRSA
, ripemd
, ripemd160
, ripemd160WithRSA
, rmd160
, rsa-md4
, rsa-md5
, rsa-mdc2
, rsa-ripemd160
, rsa-sha
, rsa-sha1
, rsa-sha1-2
, rsa-sha224
, rsa-sha256
, rsa-sha384
, rsa-sha512
, sha
, sha1
, sha224
, sha256
, sha384
, sha512
, ssl2-md5
, ssl3-md5
, ssl3-sha1
, whirlpool
Base 64 Encoding
If you’re looking to turn some text to base64 for something like Basic Auth or otherwise, use this simple function available from Node.js:
Hydration & Dehydration
Dehydration is what Zapier calls the creation of a pointer to some data, this is what you’ll normally use to provide data that may not be needed now but could the future.
Hydration is the opposite of dehydration. It is the consumption of a pointer that returns data. Let’s show an example!
In the example above, get_contact
will not be called when post_poll is called. Instead, a unique hash is created and stored in place of deal.contact
.
There are two scenarios when get_contact
will then be called and “hydrated”.
-
When a user is first setting up their Zap in the UI and accessing fields (because
deal.contact
may have keys to choose from on itself). -
When a user’s Zap tries to send
deal.contact
out to another app.
Files
Dehydrating Files
Dehydration is what Zapier call the creation of a pointer to data, this is what you’ll normally use in triggers to provide binary data out of band to Zapier. The idea is you don’t want to download all the attachments from all 100 records in a poll - that would take way too long and would be wasteful. So Zapier offer a handy way to create pointers that Zapier can consume “on-demand”.
Please note that request will be done via the requests library for Python which is different from z.request(). You cannot set an
auth
property (e.g. for Basic Auth). Instead provide the exactparams
andheaders
.
Hydrating Files
The scripting portion of hydration in actions is incomplete - right now your API will need to adhere to our multipart pattern.
Bundle Details
Prepared request via bundle.request
All pre
and methods like KEY_write
receive a prepared request via bundle.request
. This object has the same format as what the pre
methods are expected. This means you can modify and return it. It is also the same format that z.request()
accepts. This is what you’d do in most KEY_TYPE
methods.
url <string>
: Configured Polling, Action or Search Endpoint URL. Any variables will be resolved.method <string>
: Will beGET
in most cases, butPOST
for actions (_write
),pre_subscribe
andpre_unsubscribe
.auth <Array>
: Will only be set if the app’s Auth Type is Basic or Digest Auth. The first 2 elements are the username and password. Digest Auth has a third element which is alwaysfalse
.headers <Object>
: If the Auth Type is API Key (Headers) or when it is OAuth V2, OAuth V2 (w/refresh) or Session Auth and you have selected Header or Both for Access Token Placement, then this object will have the required/mapped headers. In addition, Zapier always setContent-Type: application/json; charset=utf-8
andAccept: application/json
sincedata
defaults to JSON and Zapier prefer to get that back as well.params <Object>
: Will be mapped into the querystring. If the Auth Type is API Key (Query String) or when it is OAuth V2, OAuth V2 (w/refresh) or Session Auth and you have selected Querystring or Both for Access Token Placement, then this object will have the required/mapped parameters. If you need to convert this to an actual querystring, use$.param(bundle.request.params)
. Be aware that Zapier do not automatically set params for your Trigger Fields!data <string>
: Will form the body of the request. This will be set to a JSON string forpre_subscribe
,pre_unsubscribe
and actions (_write
) that have one or more fields with Send to Action Endpoint URL in JSON body enabled. To parse a JSON string back to an object usez.JSON.parse(bundle.request.data)
. To stringify an object useJSON.stringify(your_object)
.files <Object>
: For actions (_write
) that have file-type Action Fields this will be an object with the field keys as keys while the values are anArray
of: -[0] <string>
Filename ornull
. -[1] <string>
URL to a zapier.com endpoint that will stream the file. -[2] <string>
Mimetype ornull
.
For Static and REST Hooks, KEY_catch_hook
also receives bundle.request
, but as this is an incoming request it has a different structure. It does not have an url
or auth
property, params <Object>
is querstring <string>
and data
is called content
.
Raw URL via bundle.url_raw
The bundle.url_raw
is simply the unrendered version of the URL with {% templatetag openvariable %}curlies{% templatetag closevariable %}
still intact.
Auth Fields via bundle.auth_fields
The bundle.auth_fields
is a javascript object that matches the authentication settings provided by the user when the API is connected. For example, if you have an authentication field of api_key
and subdomain
you can expect:
Rendered Fields via bundle.trigger_fields
or bundle.action_fields
Both bundle.trigger_fields
and bundle.action_fields
are javascript objects that surface the data given by a user to power a part of a zap. This is after rendering {% templatetag openvariable %}curlies{% templatetag closevariable %}
. These follow the trigger fields or action fields) you define. For example, maybe you have a field with a key list_id
and name
:
For actions, this will prune out any fields you chose not to send in the JSON. Use bundle.action_fields_full
if you want them included as well.
Raw Fields via bundle.trigger_fields_raw
or bundle.action_fields_raw
Both bundle.trigger_fields_raw
or bundle.action_fields_raw
are javascript objects that surface the data given by a user to power a part of a zap. This is before rendering {% templatetag openvariable %}curlies{% templatetag closevariable %}
. These follow the trigger fields or action fields you define. For example, maybe you have a field with a key list_id
:
For actions, this will prune out any fields you chose not to send in the JSON.
Trigger Details via bundle.trigger_data
This is deprecated and will be going away entirely soon. Instead, use standard action fields which the user maps, to access trigger data.
Webhook Payload via bundle.cleaned_request
The bundle.cleaned_request
is our best guess at the parsed payload. Zapier does its best to parse JSON, XML and form-encoded data into respective javascript objects. If Zapier cannot parse it correctly - look into bundle.request.content
and parse it yourself.
Zap Details via bundle.zap
The bundle.zap
object contains extra information about the zap (FYI: you may not see this information in debug bundles until the zap
is referenced at least once in your script):
You can access the information like this:
Extra Request Info via bundle.meta
The bundle.meta
object contains some runtime information about the Zap which you can use.
Use bundle.meta.page to implement pagination - this is especially important for triggers that power dropdowns.
You can access the information for limited pagination features like this:
Available exceptions
Note: This guide is for Zapier’s legacy web builder. If you use Platform UI, Zapier expects standard HTTP errors to be thrown. If you use Platform CLI, learn more in our CLI error handling docs.
In scripting, you have several exception classes at your disposal:
- General errors
- Halting execution
- Stale authentication credentials
- Updating session credentials
General errors
The most rudimentary exception class is the ErrorException
. Use it in situations where the user has something misconfigured with their Zap and will need to take action. Typically, this will be for prettifying 4xx
responses and API’s that return errors as 200
with a payload that describes the error.
Example: throw new ErrorException('Your error message.');
If a Zap raises too many error messages it will be automatically turned off, so only use these if the scenario is truly an error that needs to be fixed.
Halting execution
Any method can be interrupted or “halted” (not success, not error, but stopped for some specific reason) with a HaltedException
. You might find yourself using this exception in cases where a required pre-condition is not met. For example, in an action to add notes to a contact where contacts are searched for by email address, you would want to throw a HaltedException
if a contact was not found. Unlike the ErrorException
, a Zap will never be turned off when this exception is raised (even if it is raised more often than not).
Example: throw new HaltedException('Your reason.');
Any pre_XXX call can be interrupted silently with StopRequestException
. This will prevent the request from being made and will never cause a user’s Zap to be turned off.
Example: throw new StopRequestException('Your reason.');
Stale authentication credentials
For apps that require manual refresh of authorization on a regular basis, Zapier provide a mechanism to notify users of expired credentials. With the ExpiredAuthException
, the current call is interrupted, the Zap is turned off (to prevent more calls with expired credentials), and a predefined email is sent out informing the user to refresh the credentials.
Example: throw new ExpiredAuthException('Your message.');
For apps that use OAuth, but do not return a typical 401 when tokens expire, you can use the RefreshTokenException
in a post_XXX. This will signal to Zapier to attempt to refresh the access token and then repeat the failed call.
Example: throw new RefreshTokenException('Your message.');
Updating Session Credentials
For session-based APIs only, stale authorization credentials can be refreshed by throwing the InvalidSessionException
. This will tell Zapier to invoke your provided get_session_info()
function. Zapier will store these results for you and make them available to every poll
and write
. Zapier will throw the exception for you if the API responds with a 401 status.
Code examples
Trigger pre-poll examples
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Trigger post-poll examples
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Catching webhooks example
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Action pre-write examples
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Search post-write examples
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Sometimes, a search endpoint will return a successful response despite the search being unsuccessful. To account for this, you need to manipulate the response in a _post_search
method:
REST hook subscription xamples
Heads up! This code is only valid for the v2 platform, and is incompatible with today’s Platform CLI and Platform UI.
Adding trigger fields to subscription payload
Session authentication examples
Note This code is only valid for the v2 platform. It’s incompatible with Platform CLI and Platform UI.
Testing and Debugging
As your legacy scripting methods are now running within the platform, you’ll want to use the tools available on each.
If you have console.log
references, these will be translated to z.console.log
, so the console logs can be made available in our different logging tools.
For Platform UI: /build/test-auth#monitoring
For Platform CLI: /reference/cli-docs#logging
Previous: Custom Actions and API Requests Actions Next: Changelog
Need help? Tell us about your problem and we’ll connect you with the right resource or contact support.