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 — retrieve the verified customer’s record before discussing an order or support case.
- Create a support request — record the customer’s confirmed issue and retain its ticket ID.
- Follow up on a case — read its status or update its priority without creating another ticket.
- Brief your support team — leave an internal note with the issue and work already completed.
- Import help articles — retrieve approved public Help Center content from Knowledge.
- Human agent hand-off — 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.
Code
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.
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.
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
Store the credential
Open the project in Agent studio. 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.
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.
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.
Code
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 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:
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:
Save secret.id as SECRET_ID:
Send variables: {"gorgias_customer_id":"VERIFIED_GORGIAS_ID"} from your backend with the initial launch 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.
Save the request and discover its input IDs
Save apiTool.id as API_TOOL_ID, then inspect the schema and input IDs:
Match each variables[].name to its id; keep those IDs for the attachment below.
Execute against a test customer
Create the Secret and identity variable
This writes the project default and Main’s Published value. Save secret.id as SECRET_ID, then set the test Draft override:
Send variables: {"gorgias_customer_id":"VERIFIED_GORGIAS_ID"} from your backend with the initial launch action, which sets variables before processing the turn. Do not use a shared customer ID as the variable default.
Save the request and discover its input IDs
Save apiTool.id as API_TOOL_ID:
Match variables[].name to id for the attachment below.
Execute against a test customer
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.
Code
Save this as gorgias-attachment.json. Replace the tool ID and the input IDs using the returned variables[] values:
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 with versionVariant: "published", then publish the tested agent. Management and standalone execution use Draft; a named Environment’s Draft override does not set its Published value.
Repair authorization or replace a key
- 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-Afterheader. Do not loop immediate retries. See rate limits. - An uncertain write: retrieve the record before retrying. Ticket and message creation can duplicate work if the first response was lost.
Finding customers
Use a verified customer identity to retrieve relevant support context.
The lookup above retrieves GET /api/customers/{id}. Preserve the returned Gorgias id; it differs from your application’s customer ID. The customer record includes name, email, external_id, note and channels. Return only fields needed for the support request.
Establish the customer mapping
Studio
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.
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.
Code
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 and customer creation 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.
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.
Prepare the ticket request
Use your verified customer ID in both customer.id and messages[0].sender.id. This illustrative payload uses customer 3924:
Studio
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.
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.
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.
Code
Construct gorgias-ticket-payload.json on your backend from the verified ID and confirmed issue. jq preserves numeric IDs and escapes free text:
Save this request definition as gorgias-ticket-tool.json, substituting your domain:
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:
Save gorgias-ticket-inputs.json:
Save apiTool.id as TICKET_TOOL_ID:
Save apiTool.id as TICKET_TOOL_ID:
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, populate it from your backend’s serialized confirmed request, then attach this tool. 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 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.
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 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
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.
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.
Code
Use the same API-tool create, execute and attachment flow, 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 also accept assignee_team or assignee_user objects with the intended existing ID. Resolve those through Gorgias’s teams or 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.
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.
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:
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.
Code
Create a saved API tool using the ticket-tool pattern, 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 and confirm actual receipt before enabling the action.
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
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.
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.
Code
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:
Save data.documentID as DOCUMENT_ID, then poll with the same project key and Environment:
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 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.
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 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.
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/messageroute. - Status delivery: select Ticket status updated and use its
/gorgias/statusroute. 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 and integration template variables.
Verify the teammate reply route
Follow Gorgias’s third-party-channel setup 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.
Configure callbacks to Voiceflow
Your relay sends the normalized Handoff 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
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.
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.
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.
Code
Save gorgias-handoff.json with your deployed relay credentials. The relay holds the Gorgias key separately:
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; 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. Test its published Environment, not only standalone management requests.
Verify the complete conversation
- Escalate once and confirm one Gorgias ticket with the correct customer, summary and team.
- Send a customer message from Voiceflow and a public teammate reply from Gorgias. Each must appear once in the other interface.
- Add a private note and replay a provider event. The note must stay private and the replay must not duplicate the reply.
- 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/ticketswith the initial incoming message,status: "open"and your connection ID asexternal_id. Save the returned ticketidbefore acknowledging creation. Use your verified third-party reply-channel mapping, not the API-channel ticket example above. - Customer message: POST
/api/tickets/{ticket_id}/messageswithfrom_agent: false,public: true, the stored customer sender and the configured delivery channel/source. Omitreceiverfor 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 newfrom_agent: true,public: truemessages; excludeinternal-noteand customer echoes. Deduplicate by returned messageid, then use itscreated_datetime,body_textand sender for one normalizedmessage.receivedcallback. Use the current List messages endpoint, 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 actualstatus. When it isclosed, record the transition and send oneconversation.endedcallback so your own close cannot loop. A status-change notification is not aticket-closedEvent API object. - Files: start with
files: falsein 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. Configuration and mock tests do not certify delivery through a real Gorgias account.