# parcelLab Gorgias Integration Guide ## 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. {% hint style="info" %} 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. {% endhint %} ## 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 with 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](https://docs.gorgias.com/en-US/user-permissions-196938) 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](https://app.parcellab.com). 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: * [Create an API token in the Admin module of the parcelLab App](https://how.parcellab.works/guides/admin-and-settings/api-tokens#create-an-api-token) * [Generate an API token via API](https://app.gitbook.com/s/m5MUhYrMmT0cei4QdxGn/api-access/tokens#post-create-a-new-token)
## Configuring the parcelLab Gorgias Integration {% stepper %} {% step %} ### 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](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}}](https://api.parcellab.com/gorgias?recipient_id={{ticket.customer.email}}\&lang=en) 7. In the **HTTP Method** field, select **GET**. 8. In the **Headers** section, you will need to create one header for parcelLab API authentication:
KeyValue
AuthorizationParcellab-API-Token {encoded parcelLab token}
9. 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](https://developers.gorgias.com/reference/create-integration), you can use the following cURL. {% hint style="success" %} Replace the variables in the following snippet with the actual values: * `location`: [https://**your-domain**.gorgias.com/api/integrations](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 {% endhint %} ```html 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 }, "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.
{% endstep %} {% step %} ### 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](https://your-domain.gorgias.com/api/widgets). {% hint style="success" %} Replace the variables in the JSON body with the actual values: * `integration_id`: the ID for the integration you created in the previous step. {% endhint %} Alternatively, you can use the following cURL example and replace the variables for your actual values. {% tabs %} {% tab title="JSON" %} {% code overflow="wrap" expandable="true" %} ```json { "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" } ``` {% endcode %} {% endtab %} {% tab title="cURL" %} {% code overflow="wrap" expandable="true" %} ```html curl --location 'https://domain.gorgias.com/api/widgets' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic base64encode(USERNAME:API_KEY)' \ --data '{ "context": "ticket", "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" }' ``` {% endcode %} {% endtab %} {% endtabs %} :party-horn: If you receive a `201 CREATED` success message, the widget is created and visible in Gorgias. {% endstep %} {% endstepper %}