HTTP Integrations

Updated 1 month ago by Romain Lapeyre

If you wish to connect a platform with Gorgias, but we don't have a direct integration with this app just yet, there are still ways to integrate!

How it works

HTTP integrations allow you to connect any third-party app to Gorgias, that has an open API. Think of your company custom back-office, or an app that is not listed on our integration page. 

There are two main uses for HTTP integrations: 

  • Fetch customer data from a third-party to populate the user profile
  • Trigger an action in a third-party app when a ticket is created or updated

Gorgias for developers

Gorgias prides itself on being a developer-friendly helpdesk.

We expose a RESTful API to make it easy for you to get, create, update and delete many objects including customers, tickets, messages and events.

To find out more about our API, please consult our docs here: https://developers.gorgias.com

Also, in the REST API (Settings -> REST API) section of the Settings in your helpdesk, you will find a button to subscribe to the developer newsletter. We highly encourage you to subscribe to it, as it contains updates about upcoming changes and breaking changes to the API, new features and integrations.

If you'd like to check our latest updates now, you can follow this link: https://updates.gorgias.com/labels/developers and subscribe from there as well.

The rate limit of the API is 2 requests per second.

Setup instructions

Most support teams use a custom back-office, or admin, to look up customer profiles and perform actions on them. 

With Gorgias, you can:

  • Automatically fetch customer data when a ticket is created
  • Display it next to tickets
  • Use this data
  • We can also fetch the data on ticket updated and new message in ticket events as well

Step 1: before you start

In order to connect your back-office, you’ll need an endpoint from which Gorgias can fetch customer data given the address of a customer. For example:

GET https://yourcompany.com/api/users?email={{ticket.customer.email}}

Then, it would send some info about this email address to Gorgias:

{
"order":{
"id":4759226956,
"name":"#1002",
"note":"",
"tags":"",
"token":"56710ab7e3ebc4d1e16078290a1536ac"
}
}

Step 2: plug your back-office API to Gorgias

Once you have an endpoint such as the one above, follow these steps to fetch data on each ticket:

  1. In Gorgias, create an "HTTP Integration"
  2. Use the "GET" method and your back-office URL. It should look like this: https://company.com/api/users?email={{ticket.customer.email}}
    • Optional: use a header to pass the API key. For instance: "Authorization, Basic 5Nmy9Z1loPr0M45TVBVRqoKyccj1jI03aGAZEx2fkO4"
  3. Select a trigger
  4. Click "Save"

When a ticket is created or updated, Gorgias will automatically pull customer information from your back-office and display it in the sidebar to the right of your tickets.

Step 3: display the information in the sidebar

Now that we have this customer data available, let's display it next to your tickets! 

  1. Go to a ticket. Make sure your API can return info about the email address of the ticket customer (otherwise, there's nothing we can display)
  2. Add a tag to the ticket, this will trigger ticket updated , and fetch the customer data from your API
  3. Click on the gear icon, at the top right of the page
  4. Drag & drop the yellow section into the sidebar, and build your own widgets!

Step 4: using the sidebar data in macros

You can use the content of the widgets in your macros. For this, refer to the back-office variables, in the Macro variables article.

Hookdeck

If the endpoint you're using in your integration is unreliable or you want to have more control as to what gets delivered - we recommend using Hookdeck:

Hookdeck offers a complete infrastructure to reliably deploy integrations that make handling and managing incoming webhooks you receive from Gorgias simple. They offer built-in scaling, failure recovery, monitoring and alerting without provisioning your own infrastructure or deploying new code.

You can avoid having to build your own infrastructure to successfully act on every webhook we send. It's generally recommended to implement logic to queue and asynchronously process webhooks and Hookdeck is the fastest and easiest way to accomplish this.

Slack

When a new ticket is created, you can connect Slack to post a notification in the Slack channel of your choice.

Setup instructions
  1. In Slack, click on "Apps & integrations"
  2. In the top right, click "Build" to add a custom integration
  3. Click "Incoming WebHooks"
  4. Select the channel where you want to see notifications of new tickets, then click "Add Incoming WebHooks Configuration"
  5. Copy the Webhook URL
  6. In Gorgias, create an "HTTP Integration"
  7. Paste the Webhook URL from Slack into the URL
  8. Paste the code below into the body (to pass the ticket information to Slack)
  9. Select "Ticket Created" as a trigger
  10. Click "Add Integration"

Here’s the Request Body (JSON) that you can paste:

{
"text": "New ticket <https://{{ticket.account.domain}}.gorgias.com/app/ticket/{{ticket.id}}|*{{ticket.subject}}*> from *{{ticket.customer.name}}*",
"attachments": [
{
"text": "{{ticket.first_message.body_text}}",
"title": "{{ticket.subject}}",
"title_link": "https://{{ticket.account.domain}}.gorgias.com/app/ticket/{{ticket.id}}"
}
]
}

Segment

You can send data about your tickets in Segment by adding Gorgias as a Source on your Segment account. By doing so, you can understand if customers who contacted support in the last year are generating more revenue.

First, add Gorgias as a Source to Segment:

  1. In your Segment account, click on "Sources"
  2. Click "Add Source"
  3. At the end of the list in the server section, click "HTTP API"
  4. Click "Connect"
  5. Type in "Gorgias" as a nickname & SQL schema name, then click "Create source"
  6. Open your newly created Gorgias source
  7. Locate the "Write Key" under installation and copy it
  8. Go to http://decodebase64.com/ and paste the "Write Key" under "ASCII Plain Text"
  9. After pating the "Write Key" make sure you add a colon character or :  at the end of the string.
  10. Copy the text that shows up in the "Base64" section

Nice job! Now you can send data to Segment! Next, we need Gorgias to notify Segment when a ticket is created.

  1. In your Gorgias account, click on "Integrations," then click "HTTP Integration," then click "Add HTTP Integration"
  2. Use the following configuration, and click "Add Integration"
Integration name: Send info to segment on Ticket created
Description: Segment
Trigger: Ticket created
URL: https://api.segment.io/v1/track
HTTP Method: POST
Headers: Key: Authorization, Value: Basic "paste Base64 code from step 9 here - without the quotes"
Request Body (JSON):
{
"timestamp": "{{ticket.created_datetime}}",
"properties": {
"subject": "{{ticket.subject}}",
"ticket_id": "{{ticket.id}}",
"status": "{{ticket.status}}",
"assignee": "{{ticket.assignee_user}}",
"channel": "{{ticket.channel}}",
"name": "{{ticket.customer.name}}",
"tags": "{{ticket.tags}}"
},
"userId": "{{ticket.customer.email}}",
"event": "Ticket created"
}

Nice job! Every time a ticket is created, data about the ticket will be sent to Segment. You can use the sent data in other apps.

Zapier

Using Zapier, you can trigger a zap when a ticket is created and/or updated.

  1. Create a zap in Zapier and choose a "webhook" as a trigger
  2. In your Gorgias account, click on "Integrations," then click "HTTP Integration," then click "Add HTTP Integration"
  3. Click "POST", then use the webhook URL from Zapier. You can pass arguments from Gorgias to Zapier using headers\
  4. Select a "Trigger" of your choice

Nice job! When the integration is triggered, your zap will run.

**Please note, this integration is available to all customers but will only be supported for Advanced and Enterprise plan customers. While any plan can set up the integration following the instructions,  due to the manual work it requires on our end, if you are on the Basic or Pro plan we will not be able to provide support in setting it up or fixing any issues with it should they arise.

Troubleshooting

Why did my HTTP integration get disabled?

If you received an email saying that your HTTP integration was disabled then you're probably wondering why.

It can happen for any number of reasons, for example: the service that's used in the HTTP integration is experiencing a downtime, there's latency issues and the HTTP requests time-out.

In the video below you can see how you can track the details of the issue:

I fixed the problem, but it keeps getting disabled!

If your HTTP endpoint has intermittent issues we still try to send up to 100 HTTP requests to it. We generally keep retrying individual requests if there are timeouts for example. However, if 100 requests fail in a row then we disable the integration. This is done to prevent abuse of our systems (and external services).

The good news is that If a couple of requests succeed (Ex: HTTP response code 200) then we reset the failure count back to zero.

To illustrate this:

- 100 requests fail in a row -> integration gets disabled.

- 90 requests fail, then a number of requests succeed -> the failure count gets reset to zero.

This way some intermittent failures will not lead to the deactivation of your HTTP integration.


What do you think? Yay or Nay?