Guides LoginApp

parcelLab Gorgias Integration Guide

This tutorial describes how to build a widget in Gorgias to display order and tracking data from parcelLab.

Overview

With the parcelLab Gorgias integration, your customer service agents can access order and tracking data from parcelLab directly in tickets within Gorgias. The widget can be configured to display the most important order information needed to resolve customer service inquiries.

In this tutorial, you will learn:

  • how to create a HTTP integration that connects Gorgias and parcelLab

  • how to create a widget in Gorgias that displays data from parcelLab in your helpdesk tickets.

A single Gorgias widget can only be connected to one integration using one set of credentials.

This guide is intended for the implementation of the parcelLab Gorgias integration for a setup comprising of one parcelLab account and one Gorgias account.

Requirements

Before you start, ensure the following prerequisites are met:

  • Gorgias

    • Access to create HTTP Integrations (that is: Admin user role)

    • REST API access

      • Credentials required: username (email address of your Gorgias account) and password (API key)

  • parcelLab

    • Account tracking data enabled

    • API access

      • Credentials required: parcelLab account ID and API token with read scope

How to get access to create HTTP integrations in Gorgias

To create a HTTP integration in Gorgias, you need the Admin user role that will allow you to manage settings in Gorgias. This will allow you to create and update a HTTP integration using the Gorgias UI.

How to get Gorgias API access

For Gorgias API access to create widgets, you will need the following credentials for authentication:

  • The email address of your Gorgias account

  • API key

To find your Gorgias credentials:

  1. Log in to Gorgias.

  2. Navigate to Settings > REST API. The REST API page will display your API access and credentials.

    Gorgias REST API credentials

To create an API key in Gorgias:

  1. Navigate to Settings > REST API.

  2. Click Create API Key.

    Numbered steps to create api key in gorgias

    The API key is created and can be used to authenticate requests to Gorgias API endpoints.

How to get parcelLab API access

For parcelLab API access, you will need the following credentials for authentication:

  • Your parcelLab account ID

  • API token with read scope

To find your parcelLab account ID:

  1. Log in to the parcelLab App.

  2. Navigate to Admin > Accounts. A list of accounts you have access to will display with the name and ID for each record.

    Accounts page in parcelLab admin module

If you do not have an API token with the required scope, you can create an API token using any of the following methods:

Configuring the parcelLab Gorgias Integration

1

Create a HTTP integration in Gorgias

You can create an integration in Gorgias using any of the following ways:

Create an integration using the Gorgias UI

To create an integration in Gorgias:

  1. Navigate to Settings > HTTP integration > Manage. Alternatively, access it directly from your HTTP integration page URL: https://YOUR- DOMAIN.gorgias.com/app/settings/integrations/http/integrations

  2. Click Add HTTP Integration.

    Add http integration button

    The Add a new HTTP integration page will display.

    Create http integration page

  3. In the Integration name field, enter a name for the integration (for example: parcelLab Order Tracking).

  4. In the Description field, enter a description for the parcelLab integration.

  5. In the Triggers section, select the following triggers:

    • Ticket created

    • Ticket updated

    • Ticket message created

  6. In the URL field, enter this URL: https://api.parcellab.com/gorgias?recipient_id= {{ticket.customer.email}}

  7. In the HTTP Method field, select GET.

  8. In the Headers section, you will need to create one header for parcelLab API authentication:

Key
Value

Authorization

Parcellab-API-Token {encoded parcelLab token}

  1. Click Add Integration. The HTTP integration for parcelLab is created. The integration ID can be found at the end of the URL.

    How to find gorgias integration id in the url
Create an integration using the Gorgias API

To create an integration via API, you can use the following cURL.

Replace the variables in the following snippet with the actual values:

  • location: https://your-domain.gorgias.com/api/integrations

  • Authorization in the header option: A base64-encoded string comprising your Gorgias user and password (that is: the components of your API credentials)

  • Authorization in the data option: Your encoded parcelLab API token

curl --location 'https://your-domain.gorgias.com/api/integrations' \
--header 'accept: application/json' \
--header 'authorization: Basic base64encode(USERNAME:API_KEY)' \
--header 'content-type: application/json' \
--data '
{
  "http": {
    "method": "GET",
    "request_content_type": "application/json",
    "response_content_type": "application/json",
    "triggers": {
      "ticket-created": true,
      "ticket-updated": true,
      "ticket-message-created": true,
      "ticket-self-unsnoozed": false,
      "ticket-message-failed": false,
      "ticket-assignment-updated": false,
      "ticket-status-updated": false
    },
    "headers": {
        "Authorization": Parcellab-API-Token <BASE64ENCODED userid:token>
    },
    "url": "https://api.parcellab.com/gorgias?recipient_id={{ticket.customer.email}}"
  },
  "type": "http",
  "managed": false,
  "name": "parcelLab",
  "description": "Fetching delivery status for customer and order from parcelLab"
}
'

From the API response, take note of the id value. This is the integration ID that must be referenced when creating the widget.

You can also locate the integration ID from the URL of your integration in Gorgias.

2

Create a widget to display order data from parcelLab

After creating the integration, you can proceed to creating the widget. The widget will display in the ticket sidebar on the right-hand side.

Gorgias ticket with parcelLab widget in sidebar

To create a widget, you will need to send a POST request to the Gorgias API at https://your-domain.gorgias.com/api/widgets.

Replace the variables in the JSON body with the actual values:

  • integration_id: the ID for the integration you created in the previous step.

Alternatively, you can use the following cURL example and replace the variables for your actual values.

{
    "context": "ticket",
    "deactivated_datetime": null,
    "integration_id": ### INTEGRATION ID ###,
    "app_id": null,
    "order": 0,
    "template": {
        "type": "wrapper",
        "widgets": [
            {
                "meta": {
                    "link": "",
                    "color": "",
                    "pictureUrl": "https://config.gorgias.io/production/3RBN0xMVVqb649GJ/widget/59c27126-f8b0-472f-9678-2e00c138e201.jpg",
                    "displayCard": true
                },
                "path": "",
                "type": "card",
                "title": "{{title}}",
                "widgets": [
                    {
                        "meta": {
                            "limit": 3,
                            "orderBy": ""
                        },
                        "path": "orders",
                        "type": "list",
                        "widgets": [
                            {
                                "meta": {
                                    "link": "",
                                    "color": "",
                                    "pictureUrl": "https://config.gorgias.io/production/3RBN0xMVVqb649GJ/widget/9d1cb488-fd23-49ae-9840-92774ce0ea10.jpg",
                                    "displayCard": true
                                },
                                "type": "card",
                                "title": "{{title}}",
                                "widgets": [
                                    {
                                        "meta": {
                                            "limit": 3,
                                            "orderBy": ""
                                        },
                                        "path": "outboundTrackings",
                                        "type": "list",
                                        "order": 0,
                                        "widgets": [
                                            {
                                                "meta": {
                                                    "link": "",
                                                    "color": "",
                                                    "pictureUrl": "",
                                                    "displayCard": true
                                                },
                                                "type": "card",
                                                "title": "{{name}}",
                                                "widgets": [
                                                    {
                                                        "path": "address",
                                                        "type": "text",
                                                        "title": "Address"
                                                    },
                                                    {
                                                        "path": "status",
                                                        "type": "text",
                                                        "title": "Status"
                                                    },
                                                    {
                                                        "path": "statusTime",
                                                        "type": "date",
                                                        "title": "Status time"
                                                    },
                                                    {
                                                        "path": "checkpoints",
                                                        "type": "list",
                                                        "widgets": [
                                                            {
                                                                "type": "card",
                                                                "title": "{{status_details}}",
                                                                "widgets": [
                                                                    {
                                                                        "path": "city",
                                                                        "type": "text",
                                                                        "title": "City"
                                                                    },
                                                                    {
                                                                        "path": "country",
                                                                        "type": "text",
                                                                        "title": "Country"
                                                                    },
                                                                    {
                                                                        "path": "event_timestamp",
                                                                        "type": "date",
                                                                        "title": "Event timestamp"
                                                                    },
                                                                    {
                                                                        "path": "status",
                                                                        "type": "text",
                                                                        "title": "Code"
                                                                    },
                                                                    {
                                                                        "path": "status_details",
                                                                        "type": "text",
                                                                        "title": "Status details"
                                                                    },
                                                                    {
                                                                        "path": "matching",
                                                                        "type": "card",
                                                                        "title": "Matching",
                                                                        "widgets": [
                                                                            {
                                                                                "path": "DeliveryStatus",
                                                                                "type": "text",
                                                                                "order": 0,
                                                                                "title": "Status"
                                                                            },
                                                                            {
                                                                                "path": "DeliveryLocation",
                                                                                "type": "text",
                                                                                "order": 1,
                                                                                "title": " delivery location"
                                                                            }
                                                                        ]
                                                                    }
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                ]
                                            }
                                        ]
                                    },
                                    {
                                        "meta": {
                                            "limit": 3,
                                            "orderBy": ""
                                        },
                                        "path": "returnTrackings",
                                        "type": "list",
                                        "order": 1,
                                        "widgets": [
                                            {
                                                "meta": {
                                                    "link": "",
                                                    "color": "",
                                                    "pictureUrl": "",
                                                    "displayCard": true
                                                },
                                                "type": "card",
                                                "title": "{{name}}",
                                                "widgets": [
                                                    {
                                                        "path": "address",
                                                        "type": "text",
                                                        "title": "Address"
                                                    },
                                                    {
                                                        "path": "status",
                                                        "type": "text",
                                                        "title": "Status"
                                                    },
                                                    {
                                                        "path": "statusTime",
                                                        "type": "date",
                                                        "title": "Status time"
                                                    },
                                                    {
                                                        "meta": {
                                                            "limit": 3,
                                                            "orderBy": ""
                                                        },
                                                        "path": "articles",
                                                        "type": "list",
                                                        "widgets": [
                                                            {
                                                                "meta": {
                                                                    "link": "",
                                                                    "color": "",
                                                                    "pictureUrl": "",
                                                                    "displayCard": true
                                                                },
                                                                "type": "card",
                                                                "title": "{{articleName}}",
                                                                "widgets": [
                                                                    {
                                                                        "path": "articleNo",
                                                                        "type": "text",
                                                                        "title": "Article no"
                                                                    },
                                                                    {
                                                                        "path": "quantity",
                                                                        "type": "text",
                                                                        "title": "Quantity"
                                                                    },
                                                                    {
                                                                        "path": "returnable",
                                                                        "type": "boolean",
                                                                        "title": "Returnable"
                                                                    }
                                                                ]
                                                            }
                                                        ]
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "type": "http"
}

If you receive a 201 CREATED success message, the widget is created and visible in Gorgias.

PreviousGorgias

Last updated

Was this helpful?