> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gorgias integration

> Connect Voiceflow to Gorgias so AI agents can manage support tickets, answer from Help Center articles and hand off conversations to your support team.

## Overview

Voiceflow integrates with Gorgias so your AI agents can use customer records and ticket history to resolve requests, answer from Help Center articles and connect customers with your support team.

Use **custom API tools** for Gorgias data. Public Help Center imports use **Knowledge**, and live chat handoff uses a **developer-built Custom Handoff relay**. These are separate connections; saving an API tool does not import articles or enable human replies.

### Examples of when to use Gorgias

- **[Recognize the customer](#finding-customers)** — retrieve the verified customer's record before discussing an order or support case.
- **[Create a support request](#creating-tickets)** — record the customer's confirmed issue and retain its ticket ID.
- **[Follow up on a case](#managing-tickets)** — read its status or update its priority without creating another ticket.
- **[Brief your support team](#adding-notes)** — leave an internal note with the issue and work already completed.
- **[Import help articles](#help-center)** — retrieve approved public Help Center content from Knowledge.
- **[Human agent hand-off](#live-agent)** — keep the customer in Voiceflow while a Gorgias teammate replies through your relay.

#### Studio

Start with an editable Voiceflow project and a Gorgias account you can authorize. Configure the data tools in Agent studio using your Gorgias API credentials. A developer must prepare the relay for live handoff.

#### Developer

Use Voiceflow's API or CLI to create, test and attach API tools, and the Knowledge API to import public articles. Your backend owns customer identity, JSON payload construction and the optional handoff relay. Keep provider credentials out of browser code.

<a id="connecting-gorgias"></a>

## Connecting Gorgias

Authorize requests to your Gorgias account and prepare a reusable API tool.

For a private integration, open **Gorgias → Settings → REST API → Create API key**. Requests use HTTP Basic authentication with the Gorgias user's email and API key. The key has that user's permissions: customer lookups require access to the customer, while ticket and note writes require permission to change those records. A distributed public app must use OAuth instead. See [Gorgias authentication](https://developers.gorgias.com/docs/access-tokens-api-keys).

Use your account's own host, `https://YOUR_DOMAIN.gorgias.com`. Prepare the full authorization value as `Basic ` followed by the Base64 encoding of `EMAIL:API_KEY`; Base64 does not encrypt the credential. Store that full value in the restricted Secret `gorgias_authorization`.

### Prepare and test a customer lookup

#### Studio

### 1. Store the credential

Open the project in [Agent studio](https://creator.voiceflow.com). In the left sidebar, open **More → Secrets** and create `gorgias_authorization` with the full authorization value above. Creating the default also sets Main's Published value, so use a test project. Set an override for your test Environment's Draft when it uses a different credential.

### 2. Create the API tool

Open **Agent → Global tools → + → API**, then create **Find Gorgias customer**. Choose **GET** and set the URL to `https://YOUR_DOMAIN.gorgias.com/api/customers/{customer_id}`. Add the header `Authorization` with input `{authorization}` and `Accept: application/json`.

### 3. Bind trusted inputs and test

First create `gorgias_customer_id` in **More → Variables**, leaving its default empty; your authenticated application supplies its value for the session. Return to the tool, set the authorization input's default to the Secret `gorgias_authorization`, and bind `customer_id` to that identity variable rather than asking the model to choose a customer. Test an existing customer ID, inspect the response and capture only the fields your support task needs.

Native Find Gorgias customer API tool with a verified customer ID input — Bind the customer lookup to an identity verified by your application.

#### Developer

Set `VF_TOKEN` to your Voiceflow management bearer token, `PROJECT_ID` to the project ID and `ENVIRONMENT` to a test Environment alias. Set `GORGIAS_AUTHORIZATION` to the complete Basic value and `GORGIAS_CUSTOMER_ID` to a customer ID verified by your application. Use a current [Voiceflow CLI](/docs/cli/install) with API-tool and tool commands; it reads `VF_TOKEN`.

Save this definition as `gorgias-tool.json`, replacing `YOUR_DOMAIN`. Braced names declare API-tool inputs, not project Secrets:

```json
{
  "name":"Find Gorgias customer",
  "description":"Retrieve the customer verified by the signed-in application.",
  "httpMethod":"get",
  "url":"https://YOUR_DOMAIN.gorgias.com/api/customers/{customer_id}",
  "headers":[
    {"key":"Authorization","value":"{authorization}"},
    {"key":"Accept","value":"application/json"}
  ]
}
```

#### API

### 1. Create the Secret and identity variable

Creating this Secret sets its project default and Main's Published value. Use a test project, then set the intended Draft override:

```sh
jq -n --arg value "$GORGIAS_AUTHORIZATION" \
  '{name:"gorgias_authorization",visibility:"restricted",defaultValue:$value}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/secret?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

Save `secret.id` as `SECRET_ID`:

```sh
jq -n --arg value "$GORGIAS_AUTHORIZATION" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' |
curl --fail-with-body --silent --show-error -X PUT \
  "https://realtime-api.voiceflow.com/v1/stable/secret/$SECRET_ID/value?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"gorgias_customer_id","color":"#515A63","defaultValue":""}'
```

Send `variables: {"gorgias_customer_id":"VERIFIED_GORGIAS_ID"}` from your backend with the initial `launch` [action](/docs/api-reference/v4interact/interact-non-stream#streaming-action). The action applies these variables before the turn; session creation alone does not set them. Do not set a shared customer ID as the variable default.

### 2. Save the request and discover its input IDs

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @gorgias-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`, then inspect the schema and input IDs:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/schema?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN"

curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT&apiToolID=$API_TOOL_ID" \
  -H "Authorization: Bearer $VF_TOKEN"
```

Match each `variables[].name` to its `id`; keep those IDs for the attachment below.

### 3. Execute against a test customer

```sh
jq -n --arg id "$GORGIAS_CUSTOMER_ID" \
  '{inputs:{authorization:"{gorgias_authorization}",customer_id:$id}}' |
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$API_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' --data-binary @-
```

#### CLI

### 1. Create the Secret and identity variable

```sh
jq -n --arg value "$GORGIAS_AUTHORIZATION" \
  '{name:"gorgias_authorization",visibility:"restricted",defaultValue:$value}' |
vf secret create --project-id "$PROJECT_ID" --output-format json
```

This writes the project default and Main's Published value. Save `secret.id` as `SECRET_ID`, then set the test Draft override:

```sh
jq -n --arg value "$GORGIAS_AUTHORIZATION" --arg env "$ENVIRONMENT" \
  '{value:$value,environmentAlias:$env,versionVariant:"draft"}' |
vf secret set-value --project-id "$PROJECT_ID" --secret-id "$SECRET_ID" --output-format json

vf variable create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --name gorgias_customer_id --color-param '#515A63' --default-value '' --output-format json
```

Send `variables: {"gorgias_customer_id":"VERIFIED_GORGIAS_ID"}` from your backend with the initial `launch` [action](/docs/api-reference/v4interact/interact-non-stream#streaming-action), which sets variables before processing the turn. Do not use a shared customer ID as the variable default.

### 2. Save the request and discover its input IDs

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < gorgias-tool.json
```

Save `apiTool.id` as `API_TOOL_ID`:

```sh
vf api-tool get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json

vf api-tool variable list --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --api-tool-id "$API_TOOL_ID" --output-format json
```

Match `variables[].name` to `id` for the attachment below.

### 3. Execute against a test customer

```sh
jq -n --arg id "$GORGIAS_CUSTOMER_ID" \
  '{inputs:{authorization:"{gorgias_authorization}",customer_id:$id}}' |
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$API_TOOL_ID" --output-format json
```

Check `success`, `error`, `truncated`, `output.status` and `output.body`. A successful lookup has HTTP 200 and the expected `output.body.id`, `name` and `email`. A Voiceflow HTTP 200 alone is not provider success.

### Make the lookup available to the agent

#### Studio

Keep the lookup in **Global tools**, write a trigger for authenticated customer questions, and run a conversation with your application-provided customer ID. Confirm that the correct record was used. Publish the tested Environment after preparing its published Secret value.

#### Developer

Save this as `gorgias-attachment.json`. Replace the tool ID and the input IDs using the returned `variables[]` values:

```json
{
  "type":"api",
  "apiToolID":"YOUR_VOICEFLOW_API_TOOL_ID",
  "target":{"global":true},
  "description":"Look up the signed-in customer before answering their account question.",
  "inputVariables":{
    "authorization":{"apiToolInputVariableID":"AUTHORIZATION_INPUT_ID","required":false,"defaultValue":"{gorgias_authorization}"},
    "customer_id":{"apiToolInputVariableID":"CUSTOMER_ID_INPUT_ID","required":false,"defaultValue":"{gorgias_customer_id}"}
  }
}
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @gorgias-attachment.json
```

#### CLI

```sh
vf tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < gorgias-attachment.json
```

Inspect `tool` and resolve `unresolvedReferences` before testing. Creating the request does not attach it. Test agent routing in Draft, [set the target Published Secret value](/docs/cli/commands/secret/set-value) with `versionVariant: "published"`, then [publish the tested agent](/docs/documentation/deploy/environments/publishing). Management and standalone execution use Draft; a named Environment's Draft override does not set its Published value.

### Repair authorization or replace a key

Check the provider response and update the credential slot that actually executes the request.

- **401:** check the account domain, user email, key and the complete Basic value. Replace the Secret in the selected Draft, test a read, then update the target Published value when ready. Revoke the old Gorgias key after switching consumers.
- **403:** check the Gorgias user's role and access to the specific resource; another copy of the same key does not add permission.
- **429:** honor Gorgias's `Retry-After` header. Do not loop immediate retries. See [rate limits](https://developers.gorgias.com/reference/limitations).
- **An uncertain write:** retrieve the record before retrying. Ticket and message creation can duplicate work if the first response was lost.

<a id="finding-customers"></a>

## Finding customers

Use a verified customer identity to retrieve relevant support context.

The [lookup above](#connecting-gorgias) retrieves `GET /api/customers/{id}`. Preserve the returned Gorgias `id`; it differs from your application's customer ID. The [customer record](https://developers.gorgias.com/reference/the-customer-object) includes `name`, `email`, `external_id`, `note` and `channels`. Return only fields needed for the support request.

### Establish the customer mapping

#### Studio

### 1. Bind the customer identity

Use the `gorgias_customer_id` variable created during connection setup. Have your authenticated application populate it with the Gorgias ID, and keep the lookup input bound to that variable.

### 2. Check the returned customer

Test a known customer and an absent ID, then inspect the captured response. Do not reveal an account because someone typed another person's email into chat.

#### Developer

Resolve your own authenticated identity to a Gorgias customer ID on your backend, then pass that ID to the session. Gorgias also exposes [customer listing](https://developers.gorgias.com/reference/list-customers) and [customer creation](https://developers.gorgias.com/reference/create-customer) for maintaining this mapping. Persist the ID returned by creation; do not create another customer for every conversation.

Use the saved API tool's execution flow with `customer_id` and `authorization`. On a merged-customer 301, reconcile the replacement customer from Gorgias and update your stored mapping before continuing. On a missing or inaccessible record, stop account-specific answers.

<a id="creating-tickets"></a>

## Creating tickets

Record a confirmed customer issue with an initial message and reusable ticket ID.

Create a ticket with **POST** `/api/tickets`. It needs an initial message, not just a subject. The example below records an incoming API-channel message. It does not start a live support relay. Gorgias's API-channel auto-replies do not run; keyword rules need `stripped_text`. See [ticket channel requirements](https://developers.gorgias.com/docs/create-a-ticket-using-api).

### Prepare the ticket request

Use your verified customer ID in both `customer.id` and `messages[0].sender.id`. This illustrative payload uses customer `3924`:

```json
{
  "customer":{"id":3924},
  "subject":"Delivery investigation · order 2086",
  "status":"open",
  "channel":"api",
  "via":"api",
  "from_agent":false,
  "messages":[{
    "sender":{"id":3924},
    "body_text":"My order shows delivered but has not arrived.",
    "stripped_text":"My order shows delivered but has not arrived.",
    "channel":"api",
    "via":"api",
    "from_agent":false,
    "public":true
  }]
}
```

#### Studio

### 1. Create a ticket API tool

In **Agent → Global tools → + → API**, create **Create Gorgias ticket** with **POST** `https://YOUR_DOMAIN.gorgias.com/api/tickets`. Reuse the Secret-backed authorization and add `Content-Type: application/json`. Choose a raw JSON body and paste the test payload above with your own test customer.

Native Create Gorgias ticket API tool and request inputs — Configure the ticket tool for the customer-confirmed issue.

### 2. Prepare dynamic data before enabling the tool

For dynamic free text, have your application's request builder serialize the complete JSON body into `gorgias_ticket_payload`. Encode braces inside JSON string values as `\u007b` / `\u007d` so token-shaped customer text stays literal during standalone execution. Use a single raw body input `{payload}` whose default is that variable. Keep the verified customer ID inside the application's payload; do not let the model select another customer. Plain substitution of unescaped text into quoted JSON can break messages containing quotes or newlines.

### 3. Confirm and verify the ticket

Require customer confirmation before the create call. Capture the returned ticket `id`, `status` and `subject`. Run once in the test account, open the ticket in Gorgias, and verify its customer and incoming message. Keep the ticket ID for subsequent updates.

#### Developer

Construct `gorgias-ticket-payload.json` on your backend from the verified ID and confirmed issue. `jq` preserves numeric IDs and escapes free text:

```sh
jq -n --argjson id "$GORGIAS_CUSTOMER_ID" \
  --arg subject 'Delivery investigation · order 2086' \
  --arg message 'My order shows delivered but has not arrived.' \
  '{customer:{id:$id},subject:$subject,status:"open",channel:"api",via:"api",from_agent:false,
    messages:[{sender:{id:$id},body_text:$message,stripped_text:$message,
      channel:"api",via:"api",from_agent:false,public:true}]}' > gorgias-ticket-payload.json
```

Save this request definition as `gorgias-ticket-tool.json`, substituting your domain:

```json
{
  "name":"Create Gorgias ticket",
  "description":"Create a ticket only after the customer confirms the prepared support request.",
  "httpMethod":"post",
  "url":"https://YOUR_DOMAIN.gorgias.com/api/tickets",
  "headers":[
    {"key":"Authorization","value":"{authorization}"},
    {"key":"Content-Type","value":"application/json"}
  ],
  "body":{"type":"raw-input","contentType":"json","content":"{payload}"}
}
```

Standalone execution interprets token-shaped text such as `{name}` as a Secret reference, including when it appears inside a serialized input. Before passing the payload, encode braces **inside JSON strings**. JSON object braces remain unchanged; Gorgias receives the original string after JSON decoding:

```sh
python3 - <<'PYTHON'
import json, pathlib, re
p = pathlib.Path("gorgias-ticket-payload.json")
original = json.loads(p.read_text())
serialized = json.dumps(original, ensure_ascii=True)
serialized = re.sub(r'"(?:\\.|[^"\\])*"',
    lambda m: m[0].replace("{", r"\u007b").replace("}", r"\u007d"), serialized)
assert json.loads(serialized) == original
p.write_text(serialized)
PYTHON
```

Save `gorgias-ticket-inputs.json`:

```sh
jq -n --rawfile payload gorgias-ticket-payload.json \
  '{inputs:{authorization:"{gorgias_authorization}",payload:$payload}}' > gorgias-ticket-inputs.json
```

#### API

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @gorgias-ticket-tool.json
```

Save `apiTool.id` as `TICKET_TOOL_ID`:

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/api-tool/$TICKET_TOOL_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @gorgias-ticket-inputs.json
```

#### CLI

```sh
vf api-tool create --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --output-format json < gorgias-ticket-tool.json
```

Save `apiTool.id` as `TICKET_TOOL_ID`:

```sh
vf api-tool execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" \
  --tool-id "$TICKET_TOOL_ID" --output-format json < gorgias-ticket-inputs.json
```

Expect `success: true`, `output.status: 201` and the new `output.body.id`. Confirm the ticket in Gorgias before treating it as created. For agent use, create `gorgias_ticket_payload` using the [variable-creation pattern](#connecting-gorgias), populate it from your backend's serialized confirmed request, then [attach this tool](#make-the-lookup-available-to-the-agent). Replace `apiToolID` and the input IDs: bind `authorization` to `{gorgias_authorization}` and `payload` to `{gorgias_ticket_payload}`, both with `required: false`. Resolve the inputs from this tool's schema and variable list, not the lookup tool's IDs. Publish after testing the agent with the prepared payload.

### Avoid duplicate support requests

Reconcile a lost response before repeating a create operation.

Store the Gorgias ticket ID when the create succeeds. Add your own stable request identifier as `external_id` when reconciliation is needed, and use Gorgias's [ticket listing](https://developers.gorgias.com/reference/list-tickets) to search it after an uncertain result. This field is not a provider idempotency guarantee. Your backend must suppress repeat submissions for the same confirmed request.

<a id="managing-tickets"></a>

## Managing tickets

Read the customer's existing cases and update the selected ticket.

Use **GET** `/api/tickets?customer_id=3924&trashed=false&limit=30` to list a verified customer's tickets and **GET** `/api/tickets/{ticket_id}` for a selected record. Check that its `customer.id` belongs to the current customer before making changes. [List tickets](https://developers.gorgias.com/reference/list-tickets) returns `data[]`; follow the provider's cursor pagination for additional pages rather than treating one page as the full history.

### Update a selected ticket

#### Studio

### 1. Configure a specific update

Create a **PUT** API tool for `https://YOUR_DOMAIN.gorgias.com/api/tickets/{ticket_id}`. Reuse the authorization Secret and JSON content type. Bind the ticket ID to the verified selected case. Use `{"priority":"high"}` to raise priority or `{"status":"closed"}` to close it; require confirmation before closing.

### 2. Verify the changed record

Test on a support ticket in your test account and retrieve it again to verify the changed field. Keep separate tools for raising priority and closing a case so their triggers describe the intended mutation.

#### Developer

Use the same [API-tool create, execute and attachment flow](#connecting-gorgias), with the method **`put`**, ticket URL and raw JSON body. For a priority tool, set `body` to `{"type":"raw-input","contentType":"json","content":"{\"priority\":\"high\"}"}` and add a trusted `ticket_id` URL input. Execute with `authorization` and `ticket_id`, then check `output.status: 202` and `output.body.priority`. Create a separate confirmed-close tool with `{"status":"closed"}` rather than giving the model an unrestricted mutation payload.

### Assignment and status choices

[Ticket updates](https://developers.gorgias.com/reference/update-ticket) also accept `assignee_team` or `assignee_user` objects with the intended existing ID. Resolve those through Gorgias's [teams](https://developers.gorgias.com/reference/list-teams) or [users](https://developers.gorgias.com/reference/list-users) listing. Supported status values are `open` and `closed`; priorities are `low`, `normal`, `high` and `critical`. Sending changed fields in a PUT does not require resending the entire ticket.

<a id="adding-notes"></a>

## Adding internal notes

Give support teammates useful context without sending it to the customer.

POST to `/api/tickets/{ticket_id}/messages` with `channel: "internal-note"`, `from_agent: true` and a sender referencing an existing **Gorgias user**. Omit `receiver`; the customer is not the note's sender. Retrieve the user ID through [List users](https://developers.gorgias.com/reference/list-users).

### Add and verify a note

This illustrative note uses user `1001`. Replace it with your support user, and serialize dynamic text as a complete JSON payload, as in [ticket creation](#creating-tickets):

```json
{
  "sender":{"id":1001},
  "body_text":"Customer verified order 2086. Delivery needs investigation; no refund has been issued.",
  "channel":"internal-note",
  "via":"api",
  "from_agent":true,
  "public":false
}
```

#### Studio

Create **Add Gorgias internal note** as a **POST** API tool with the ticket-message URL, Secret-backed authorization and JSON content type. Bind its ticket ID to the verified case and its raw `{payload}` input to your application's prepared note. Test once and inspect the Gorgias ticket: the summary must be private to the support team.

#### Developer

Create a saved API tool using the [ticket-tool pattern](#creating-tickets), changing its name and URL to `/api/tickets/{ticket_id}/messages`. Execute with `authorization`, the trusted `ticket_id` and the serialized note `payload`. Inspect `output.status: 201`, the new `output.body.id` and its `public: false` value. Attach it only with the correct input IDs and Secret/identity defaults, then test the agent. A repeated POST may create another note; reconcile the ticket's messages before retrying an uncertain write.

### Send a public email reply instead

Use a connected Gorgias email source when the message should actually reach the customer.

A public reply is a different action. Gorgias requires `from_agent: true`, a Gorgias user as sender, and the customer as receiver when specified. An outgoing email also needs `channel: "email"` and `source.from.address` set to an existing connected email integration, with the customer's address in `source.to`. Setting `public: true` on an internal note does not turn it into a working email delivery route. Follow [Gorgias's outgoing-message contract](https://developers.gorgias.com/docs/create-a-new-message-in-ticket-via-api) and confirm actual receipt before enabling the action.

<a id="help-center"></a>

## Import help articles

Answer from approved public Gorgias Help Center articles in Knowledge.

Import approved public article URLs with Voiceflow's Web page importer. This indexes article content for Knowledge; it does not authorize ticket tools or create a managed Gorgias account sync.

### Import and test a public article

#### Studio

### 1. Choose and import the article

Open its public URL in a signed-out browser and check the answer. In your Voiceflow project, open **Knowledge base → Add data source → Web page(s)** and paste the URL. Confirm the selection and import.

Native Web page importer with an approved public Help Center article URL — Import approved public Help Center articles into Knowledge.

### 2. Verify retrieval

Wait for processing to finish and inspect the imported content. Enable Knowledge on the agent, use **Run** to ask a question answered by that article and inspect the retrieved source. A URL in the list alone is not evidence that the agent used it.

#### Developer

Set `VF_PROJECT_API_KEY` to the project API key; the Knowledge API uses it separately from the management bearer token. Replace the illustrative article URL:

```sh
jq -n --arg env "$ENVIRONMENT" \
  '{data:{type:"url",url:"https://support.northstar.example/en/articles/shipping",refreshRate:"never",projectEnvironmentIDOrAlias:$env}}' |
curl --fail-with-body --silent --show-error \
  'https://realtime-api.voiceflow.com/v1alpha1/public/knowledge-base/document' \
  -H "Authorization: $VF_PROJECT_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

Save `data.documentID` as `DOCUMENT_ID`, then poll with the same project key and Environment:

```sh
curl --fail-with-body --silent --show-error --get \
  "https://realtime-api.voiceflow.com/v1alpha1/public/knowledge-base/document/$DOCUMENT_ID" \
  --data-urlencode "projectEnvironmentIDOrAlias=$ENVIRONMENT" \
  -H "Authorization: $VF_PROJECT_API_KEY"
```

Stop when `data.status` becomes `SUCCESS` or `ERROR`. Inspect the content and test actual agent retrieval in that Environment after success. An error is not a completed import; inspect and correct the source before retrying.

### Keep imported articles current

Maintain the indexed documents separately from ticket access.

Public URL imports support `daily`, `weekly`, `monthly` or `never` refresh. Choose the schedule that matches how often the policy changes. Remove obsolete documents and verify a new agent answer against the updated source. In Code, replace a document with **PUT** `/v1alpha1/public/knowledge-base/document/{documentID}`, using the same `data` body as creation and the selected `projectEnvironmentIDOrAlias`. Poll that ID until `SUCCESS` or `ERROR`. Delete obsolete content with **DELETE** on the same document URL and `projectEnvironmentIDOrAlias` query, using the project API key. The [Knowledge document reference](/docs/api-reference/kbpublicapidocument/create-document) describes the full lifecycle. For private articles, build an authorized export and upload approved content; do not expose it publicly just to use a URL importer.

<a id="live-agent"></a>

## Human agent hand-off

Keep the customer in Voiceflow while your team replies from Gorgias.

A developer must build and host a **Custom Handoff relay**. It creates and updates Gorgias tickets, receives support replies and sends signed callbacks to Voiceflow. The shared starter provides mock mode and a Chatwoot pilot; it does not include a Gorgias adapter.

### Prepare the relay and reply route

Implement the [Custom Handoff connection contract](/docs/developers/handoff/connection-api) for create, customer-message and close operations. Persist the Voiceflow connection ID, Gorgias customer/ticket IDs and processed delivery IDs. Keep the verified customer mapping and escalation summary with that conversation.

### 1. Configure two Gorgias HTTP integrations

An account owner or admin opens **Gorgias → Settings → Account → HTTP integration → Manage → Add HTTP integration**. Create two **POST** integrations with JSON content type and a private authorization header validated by your receiver:

- **Message delivery:** select **Ticket message created** and use your relay's `/gorgias/message` route.
- **Status delivery:** select **Ticket status updated** and use its `/gorgias/status` route. This trigger cannot be combined with the message trigger in one integration.

For each request body, use `{"ticket_id":"{{ticket.id}}"}`. The relay fetches the current ticket or messages itself; this payload does not provide an Event API envelope. See [Gorgias HTTP integration setup](https://docs.gorgias.com/en-US/connect-external-apps-to-gorgias-and-create-sidebar-widgets-81822) and [integration template variables](https://developers.gorgias.com/reference/the-integration-object).

### 2. Verify the teammate reply route

Follow [Gorgias's third-party-channel setup](https://developers.gorgias.com/docs/receive-and-respond-to-tickets-from-a-third-party-app) to connect a delivery address controlled by your relay and the HTTP integration. Create a manual test ticket and have a teammate reply. Confirm that the public reply reaches your receiver before connecting Voiceflow. Substituting the customer's real email can route replies to their mailbox instead of your Voiceflow conversation.

### 3. Configure callbacks to Voiceflow

Your relay sends the normalized [Handoff events](/docs/developers/handoff/webhook-events) to Voiceflow with the configured webhook secret. Keep this signing secret separate from the authorization used by Gorgias to call your receiver. Authenticate and durably queue each notification before acknowledging it; process and sign Voiceflow callbacks from that queue.

### Connect and route the handoff

#### Studio

### 1. Connect your deployed relay

Open the same project in **Agent studio → More → Integrations**. On **Custom Handoff**, select **Connect** and enter the relay's **Base URL**, **Auth header name**, **Auth header value** and **Webhook secret**. The webhook secret must be at least 32 characters.

### 2. Configure the support Workflow

Create a support **Workflow** and add a **Handoff** step. Choose **Custom Handoff**. Use verified customer fields and a queue ID that your relay maps to a Gorgias support team. Select the context to send and enable **Return** and **Fail** paths.

Native Handoff editor with Custom Handoff, customer identity, queue and return settings — Route the support Workflow through your Gorgias relay.

### 3. Make the Workflow reachable

Attach it to the agent and describe when to call it, such as a customer requesting a person. Publish to a test Environment and connect the customer chat to that Environment. Then verify the full conversation below with a teammate.

#### Developer

Save `gorgias-handoff.json` with your deployed relay credentials. The relay holds the Gorgias key separately:

```json
{
  "integration":"custom_handoff",
  "credentials":{
    "baseUrl":"https://support-bridge.example.com",
    "authHeaderName":"Authorization",
    "authHeaderValue":"Bearer YOUR_RELAY_TOKEN",
    "webhookSecret":"REPLACE_WITH_AT_LEAST_32_RANDOM_CHARACTERS"
  }
}
```

```sh
curl --fail-with-body --silent --show-error \
  "https://realtime-api.voiceflow.com/v1/stable/integration/custom_handoff?projectID=$PROJECT_ID" \
  -H "Authorization: Bearer $VF_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @gorgias-handoff.json
```

A 200 response confirms stored default-slot configuration, not two-way delivery. Create and attach a Handoff Workflow with provider `custom`, verified customer fields, a `queueId` your relay resolves, and Return/Fail paths. Use the [headless Workflow creation and test publication sequence](/docs/developers/handoff/connect#configure-voiceflow-through-the-api); a Workflow is not reachable merely because it exists. Preserve existing agent registrations when attaching it.

The customer client must implement the [Chat handoff traces and human-message contract](/docs/api-reference/agent-runtime/chat/handoff). Test its published Environment, not only standalone management requests.

### Verify the complete conversation

1. Escalate once and confirm one Gorgias ticket with the correct customer, summary and team.
2. Send a customer message from Voiceflow and a public teammate reply from Gorgias. Each must appear once in the other interface.
3. Add a private note and replay a provider event. The note must stay private and the replay must not duplicate the reply.
4. Close the ticket in Gorgias and verify the Return path; separately make the relay unavailable and verify the Fail path.

### Implement the Gorgias relay mapping

Translate ticket operations, public replies and closure without message loops.

- **Create:** resolve or create the customer, then POST `/api/tickets` with the initial incoming message, `status: "open"` and your connection ID as `external_id`. Save the returned ticket `id` before acknowledging creation. Use your verified third-party reply-channel mapping, not the API-channel ticket example above.
- **Customer message:** POST `/api/tickets/{ticket_id}/messages` with `from_agent: false`, `public: true`, the stored customer sender and the configured delivery channel/source. Omit `receiver` for incoming messages. Suppress duplicate Voiceflow delivery IDs before posting.
- **Human reply:** authenticate the message receiver and look up the mapped `ticket_id`. Fetch **GET** `/api/messages?ticket_id=TICKET_ID&order_by=created_datetime:asc&limit=100`, following cursor pages. Forward only new `from_agent: true`, `public: true` messages; exclude `internal-note` and customer echoes. Deduplicate by returned message `id`, then use its `created_datetime`, `body_text` and sender for one normalized `message.received` callback. Use the current [List messages endpoint](https://developers.gorgias.com/reference/list-messages), rather than the deprecated ticket-specific GET endpoint.
- **Close:** PUT `/api/tickets/{id}` with `{"status":"closed"}` for a Voiceflow-initiated close. On a status notification, GET `/api/tickets/{id}` and inspect its actual `status`. When it is `closed`, record the transition and send one `conversation.ended` callback so your own close cannot loop. A status-change notification is not a `ticket-closed` Event API object.
- **Files:** start with `files: false` in the relay's capabilities and keep uploads disabled until both directions and attachment limits are implemented. Text delivery does not establish file support.

Gorgias allows five seconds for the receiver. With header authentication, a timed-out request or an HTTP error response is not retried. Queue promptly, reconcile provider state after a delivery gap, and inspect **HTTP integration → Manage → Events** if delivery stops; repair and re-enable a disabled integration. Apply the [shared service durability and recovery checks](/docs/developers/handoff/connect#build-and-connect-the-service). Configuration and mock tests do not certify delivery through a real Gorgias account.
