This tutorial walks you through the process of building, testing, and pushing an example app to Zapier using Platform CLI. We’ll use a mock API for recipes in this tutorial, but for production Zapier apps, you’d want to connect to a real API.
zapier help
.
~/.zapierrc
. You’ll want to keep that file safe and not check it into source control.
init
command to setup the needed structure. You’ll be presented with a list of available templates to start with.
package.json
is a typical requirements file of any Node.js application. It’s pre-populated with a few dependencies, most notably the zapier-platform-core
, which is what makes your app work with the Zapier Platform. There is also an index.js
file and a test directory (more on those later). Before we go any further, we need to install the dependencies for our app:
index.js
index.js
is the entry point to your app. This is where the Platform will look to understand how your app will interact with Zapier. Open the app directory you created in your code editor of choice.
You may see the following in index.js
:
module.exports
definition which will be interpreted by Zapiertriggers
will describe ways to trigger off of data in your appsearches
will describe ways to find data in your appcreates
will describe ways to create data in your appresources
are purely optional but convenient ways to describe CRUD-like objects in your app (see an example resources app)beforeRequest
& afterResponse
are hooks into the HTTP client to manipulate the request/response on every callrecipe.js
in the triggers
folder. When building your own integration, you’ll likely name your JS files with nouns like contact.js
, lead.js
or order.js
.
Open triggers/recipe.js
(file created by zapier scaffold trigger recipe
) and replace it with:
zapier invoke
. The command will ask you which action you’d like to invoke. Now we only have one trigger recipe
, so you can choose that one.
listRecipes
handles the API work, making the HTTP request and returning the parsed response data.
In JavaScript, async/await
are syntactic sugar built on top of Promises. Be sure to use await
or .then()
when you call asynchronous functions.
The listRecipes
function receives two arguments, a z
object and a bundle
object.
z.request
to make the HTTP call.z
object as there are features built into these utilities that augment the Zapier experience like logging of HTTP calls and error handling.
In module.exports
, we export some metadata plus our listRecipes
function and a sample. We’ll explain later how Zapier uses this metadata and exposes it to the end user. For now, know that it satisfies the minimum info required to define a trigger.
As well as defining the trigger, the scaffold
command has done the following:
index.js
file now includes:
recipe.test.js
file was created:
zapier test
and see it pass:
triggers/recipe.js
, replace the file with:
"style"
was added in the following places:
inputFields
on operation
- this defines the field as exposed in the Zap Editor for the user to see. The field is not required, so it could be null.listRecipes
function - we use the provided style via the bundle bundle.inputData.style
.zapier invoke
to verify everything still works. This time, let’s skip those interactive prompts. Specify the action type (trigger
), the key (recipe
), and the input data in the command, and you’ll see:
recipe.test.js
file with:
zapier register
command and Zapier will ask you to provide a name and some details about your app. Follow the prompt and then you can push your app using zapier push
:
Zapier will ask you to provide a name and some details about your app with the zapier register
command. Follow the prompts and then push your app again.
triggers/recipe.js
.
In the Zap editor, see the input field "style"
and fill it out. Run the trigger test and the listRecipes
function associated with the trigger runs, making the API request and returning the result to Zapier.
Go back to your terminal. Use the zapier logs --type http
command to see the HTTP requests Zapier made.
authentication
section for the example app you’ve built. In index.js
, add the following to module.exports
:
authentication
:
fields
is where we define our auth fields. This works similar to the inputFields
of triggers. When users connect their account to Zapier, they’ll be prompted to fill in this field, and the value they enter becomes available in the bundle.authData
. Not every authentication type will include inputFields
.test
is a function used during the account connection process to verify that the user entered valid credentials. The goal of the function is to make an authenticated API request whose response indicates if the credentials are correct. A profile in the connected app, such as a /me
endpoint, is a common choice. If valid, the test function can return anything. On invalid credentials, the test needs to raise an error. Since z.request()
already throws an error for non-2xx responses, we don’t need to throw an error explicitly in this case.index.js
, edit the file to include:
addApiKeyToHeader
, adds the user-provided API key as a request header called My-Auth-Header
. The name chosen is illustrative, the header would be whatever the API you are integrating with requires. Sometimes, an API would require it in a query parameter instead of a header, and/or encoded first. You’ll want to reference the API documentation for the expected format.
Finally, to ensure the helper function takes effect, it needs to be registered in the app.
In index.js
, edit module.exports
to also include:
beforeRequest
is a list of functions that are called before every HTTP request that uses z.request
. It’s where you add headers, query params, or whatever is needed to be within all outbound requests. With this addition, every outgoing HTTP request made by z.request
will now have the API key added in a header.
The zapier invoke
command has auth test
subcommand that essentially calls the authentication.test
function for you to verify the credentials locally. But first, you need to initialize the auth credentials with the auth start
subcommand:
auth test
subcommand to verify the credentials. You’ll know you have the right API key if you can see the response data from the /me
endpoint:
To check progress, re-push the app.
authentication.test
function to confirm the credentials are valid.
We can verify the header is present in the request by looking at the logs again.
:censored:6:b1af149262:
, which is intentional. Zapier does not log authentication credentials in plain text.
zapier team:add user@example.com admin
to invite a team member as an admin for the app.zapier team:add user@example.com collaborator
to invite a team member as a collaborator for the app.zapier users:add user@example.com 1.0.0
to email this user to let them view and use the app version 1.0.0 in their Zaps.
Replace the example email address with the user you want to invite. You’ll see a confirmation prompt, type Y
.
The alternative way to invite anyone to use your app in their Zaps is via a link to the app. Run zapier users:links
to see a public sharing link per specific version or a link to all versions. The link looks something like https://zapier.com/platform/public-invite/1/222dcd03aed943a8676dc80e2427a40d/
. You can put this in your help docs, post it to your website, add it to your email campaign, etc. Access shared via these links cannot be revoked once shared with your users.
perform
functions