Documentation API Reference

Building a custom ticket form with the Ticketing API

The Zendesk help center provides abuilt-in web formthat end users can use to submit support requests. Zendesk also offersweb widgetsthat let you embed customer service directly into your websites and web apps.

An alternative to these options is to build a custom ticket form that submits requests using the Ticketing API. Such forms are highly customizable and let users submit support requests directly from your website. However, they require server-side code to make the related API requests.

In this tutorial, you'll build a basic web app that provides a custom ticket form for end users. When users submit a request using the form, the app makes a call toCreate Requestendpoint. The API call creates a corresponding ticket in your Zendesk Support instance. You can use the app's code as a starting point for building your own custom ticket forms.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk doesn't provide support for the apps or example code. Zendesk doesn't support third-party technologies, such as Node.js, Python, or related libraries.

Differences between tickets and requests

The Ticketing API offers two ways to create and manage tickets:

When creating a ticket form for end users, Zendesk recommends using the request endpoints instead of the ticket endpoints. A request is an end user's perspective of a ticket.

For more information about the differences between tickets and requests, seeTickets vs Requests APIs: How to select the right option for your project.

What you'll need

To complete this tutorial, you'll need the following:

Protecting your form from spam attacks

Zendesk strongly recommends using CAPTCHA to protect your ticket forms from spam submissions and other attacks. Popular CAPTCHA options include:

This tutorial uses Google reCAPTCHA v2. Two keys are required to use reCAPTCHA: a site key and a secret key. For easier setup, the tutorial uses test keys provided by Google:

  • Site key: 6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
  • Secret key: 6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

Don't use the test keys in production. The test keys work on any domain and always pass verification. When using the test keys, the reCAPTCHA widget displays a related warning message.

Creating a web app for your ticket form

Next, create a web app that serves up a ticket form. If an end user submits a request using the form, the app should make a call to theCreate Requestendpoint. To prevent spam, the form should also validate submissions using Google reCAPTCHA.

Instructions for creating the app are provided for both Node.js and Python. Use the programming language you prefer:

Node.js

Use the following instructions to create the web app using Node.js.

To create the web app using Node.js

  1. In your terminal, create and navigate to a folder namedticket_form_example. Example:

                   
    
                
    mkdirticket_form_examplecdticket_form_example

  2. In the folder, use the following command to create an npm package.

                   
    
                
    npminit -y

  3. Install dependencies for the project.

                   
    
                
    npminstallexpress body-parser axios express-recaptcha

    This project requires the following libraries:

  4. In theticket_form_examplefolder, create anapp.jsfile. Paste the following code into the file.

                   
    
                
    constexpress=require("express")constbodyParser=require("body-parser")constaxios=require("axios")constRecaptcha=require("express-recaptcha").RecaptchaV2constapp=express()constport=3000// In production, store credentials in environment variablesconstZENDESK_SUBDOMAIN="YOUR_ZENDESK_SUBDOMAIN"constZENDESK_EMAIL="YOUR_ZENDESK_EMAIL_ADDRESS"constZENDESK_PASSWORD="YOUR_ZENDESK_PASSWORD"constRECAPTCHA_SITE_KEY="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"constRECAPTCHA_SECRET_KEY="6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe"constrecaptcha=newRecaptcha(RECAPTCHA_SITE_KEY,RECAPTCHA_SECRET_KEY)app.use(bodyParser.urlencoded({extended:true}))app.get("/",recaptcha.middleware.render,(req,res)=>{constform=`


    <标签= "描述" > < / >标签描述< br >





    ${recaptcha.render()}
    `res.send(form)})app.post("/submit",recaptcha.middleware.verify,async(req,res)=>{if(!req.recaptcha.error){constoptions={method:"post",url:`https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/requests.json`,headers:{"Content-Type":"application/json"},auth:{username:ZENDESK_EMAIL,password:ZENDESK_PASSWORD},data:{request:{subject:req.body.subject,comment:{body:req.body.description},requester:{name:req.body.name,email:req.body.email}}}}try{awaitaxios(options)res.status(200).send("Form submitted successfully")}catch(error){res.status(500).send("Error")}}else{res.status(400).send("reCAPTCHA verification failed")}})app.listen(port,()=>{console.log(`Server running on port${port}. Visit http://localhost:${port}`)})

    In the code, replace the following placeholders:

    • "YOUR_ZENDESK_SUBDOMAIN"
    • "YOUR_ZENDESK_EMAIL_ADDRESS"
    • "YOUR_ZENDESK_PASSWORD"

  5. To start a local web server using the app, run the following terminal command from theticket_form_examplefolder:

                   
    
                
    node app.js

    To stop the server, press Ctrl+C.

  6. To test the app's ticket form, skip toTesting the ticket form.

Python

Use the following instructions to create the web app using Python.

To create the web app using Python

  1. In your terminal, create and navigate to a folder namedticket_form_example. Example:

                   
    
                
    mkdirticket_form_examplecdticket_form_example

  2. Install dependencies for the project.

                   
    
                
    pip3installflask requests google-recaptcha-flask

  3. In theticket_form_examplefolder, create anapp.pyfile. Paste the following code into the file.

                   
    
                
    fromflaskimportFlask,request,render_template_stringimportrequestsfromgoogle_recaptcha_flaskimportReCaptchaapp=Flask(__name__)PORT=3000# In production, store credentials in environment variablesZENDESK_SUBDOMAIN="YOUR_ZENDESK_SUBDOMAIN"ZENDESK_EMAIL="YOUR_ZENDESK_EMAIL_ADDRESS"ZENDESK_PASSWORD="YOUR_ZENDESK_PASSWORD"RECAPTCHA_SITE_KEY="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"RECAPTCHA_SECRET_KEY="6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe"recaptcha=ReCaptcha(app)app.config.update(dict(GOOGLE_RECAPTCHA_ENABLED=True,GOOGLE_RECAPTCHA_SITE_KEY=RECAPTCHA_SITE_KEY,GOOGLE_RECAPTCHA_SECRET_KEY=RECAPTCHA_SECRET_KEY,GOOGLE_RECAPTCHA_LANGUAGE="en",))recaptcha.init_app(app)@app.route("/",methods=["GET"])defform():returnrender_template_string("""


    <标签= "描述" > < / >标签描述< br >





    {{ recaptcha }}
    """)@app.route("/submit",methods=["POST"])defsubmit():ifrecaptcha.verify():subject=request.form["subject"]body=request.form["description"]requester_name=request.form["name"]requester_email=request.form["email"]headers={"Content-Type":"application/json"}data={"request":{"subject":f"{subject}","comment":{"body":f"{body}"},"requester":{"name":f"{requester_name}","email":f"{requester_email}",},}}response=requests.post(f"https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/requests.json",headers=headers,auth=(ZENDESK_EMAIL,ZENDESK_PASSWORD),json=data,)ifresponse.ok:return"Form submitted successfully",200else:return"Error",500else:return"reCAPTCHA verification failed",400if__name__=="__main__":app.run(debug=True,port=PORT)

    In the code, replace the following placeholders:

    • "YOUR_ZENDESK_SUBDOMAIN"
    • "YOUR_ZENDESK_EMAIL_ADDRESS"
    • "YOUR_ZENDESK_PASSWORD"

  4. To start a local web server using the app, run the following terminal command from theticket_form_examplefolder:

                   
    
                
    python app.py

    To stop the server, press Ctrl+C.

  5. To test the app's ticket form, skip toTesting the ticket form.

Testing the ticket form

Test the form to ensure it creates tickets as intended.

To test the ticket form

  1. Use your app to start a local web server.

  2. In a web browser, go tohttp://localhost:3000/.

    A blank ticket form opens.

  3. Fill out the form with test data, check the reCAPTCHA box, and clickSubmit.

  4. 在f Zendesk并亚博检查代理工作空间or a ticket related to your form. To view recently updated tickets, clickViews>Recently updated tickets.

    Registered end users can also manage their requests in the help center. SeeTracking your support requestsin Zendesk help.

Congratulations! You've created a custom ticket form using the Ticketing API. As a next step, you can expand the app and get it ready for production. Consider tackling the following tasks:

  • Replace the app'sRECAPTCHA_SITE_KEYandRECAPTCHA_SECRET_KEYvalues with reCAPTCHA keys for your production domain. You can create production keys using the Google reCAPTCHA Admin Console:https://www.google.com/recaptcha/admin/create. For instructions, see theSettingsguide in the Google reCAPTCHA docs.

  • Update the app to use a Zendesk OAuth access token to authenticate the Create Request call. OAuth access tokens give external apps limited permission to your Zendesk account and are easily revoked. SeeCreating and using OAuth tokens with the API.

  • Update the app's code to store credentials, such as your production reCAPTCHA keys and OAuth access token, in environment variables. This helps ensure you don't accidentally share them.

  • Update the form to better align with your website. For example, you can use HTML templates or add CSS for styling.

  • Integrate the form and its server-side logic into your site. For example, you can deploy the app to a server or app host, such as Heroku or AWS Elastic Beanstalk. You can then use an iframe or other method to embed the form onto your website.