Build a ticket form with Tickets API

In this tutorial, we'll walk you through building a custom web form that will allow your users to submit tickets directly to Intercom, via Tickets API.

Prerequisites

An Intercom workspace. You can use your paid workspace, or a free Intercom development workspace
Ticket Types of "Bug", "Feature request" and "Other". Create the required Ticket Types via the API or in the UI.

Step 1: Create an app for your ticket form

In this tutorial, we'll use Sinatra (Ruby) to power the ticket form on your website. You can refer to official Sinatra docs to learn how to set up a basic Sinatra app.

For this app, you'll need two endpoints: get /index to display the form and post /tickets to create the ticket. To create a ticket, the app will make a call to Tickets API:

require 'sinatra'
require 'json'
require 'httparty'

# To create a ticket in Intercom, you need to provide the id of the corresponding Ticket Type.
# This is a simplified way to map user selection to a Ticket Type id:

TICKET_TYPES = {
  '1' => 'Bug',
  '2' => 'Feature request',
  '3' => 'Other'
}

get '/' do
  # This endpoint displays the `index` template, i.e. the ticket web form itself:

  erb :index
end

post '/tickets' do
  # This endpoint gets called when the form is submitted.

  # First, we parse the payload we receive from the form:
  ticket_type_id  = params['ticket_type']
  ticket_title = params['ticket_title']
  ticket_body = params['ticket_body']
  email = params['email']

  # Then we prepare the payload that will be sent to Intercom Tickets API:
  intercom_api_token = 'your_intercom_api_access_token'
  intercom_ticket_endpoint = "https://api.intercom.io/tickets"
  token_string= "Token token = #{intercom_api_token}"

  data = { 
    ticket_type_id: "#{ticket_type_id}",
    contacts: [{ email: "#{email}" }],
    ticket_attributes: { _default_title_: "#{ticket_title}", _default_description_: "#{ticket_body}" }
  }
  
  HTTParty.post(intercom_ticket_endpoint, body: data.to_json, headers: { 'Content-Type': 'application/json', 'Authorization': token_string, 'Intercom-Version': 'Unstable'})
end

The code above maps Ticket Types to hardcoded numbers for simplicity sake. In a real world app, you'll likely need to query Ticket Types API to match customer's selection to an id of a Ticket Type in your system.

Step 2: Create a ticket form

Add the following code to index.erb template to display the ticket form:

<!DOCTYPE html>
<html>
  <head>
    <meta charset='UTF-8' />
    <title> Create an Intercom ticket </title>
  </head>
  <body class='container'>
    <h2> Create a ticket </h2>
    <form action='tickets' method='post'>
    <label>Choose the type of the ticket you wish to submit:</label><br>
      <ul>
        <% TICKET_TYPES.each do |id, text| %>
          <li>
            <label>
              <input type='radio' name='ticket_type' value='<%= id %>' id='ticket_type_<%= id %>' required/>
              <%= text %>
            </label>
          </li>
        <% end %>
      </ul>
      <label>Subject</label><br>
      <input type="text" name="ticket_title"><br>
      <label>Description</label><br>
      <textarea name="ticket_body" rows="6" required></textarea><br>
      <label>Your email</label><br>
      <input type="text" name="email" required><br>
      <button type='submit'>Submit</button>
    </form>
  </body>
</html>

Step 3: Fill out ticket details

Fill out the necessary details and click "submit":

Create ticket webform

You should now see this ticket in your Intercom Inbox:

Webform Intercom ticket

Congrats! You are done.

Next steps

Learn more about Tickets as a product.
Explore Ticket webhook topics.
Explore Ticket API.
Build an integration between Intercom tickets and GitHub issues.