Build with

Overview

Voiceflow integrates with Chatwoot so your AI agents can look up contacts, create and manage support conversations, answer from Help Center articles and connect customers with your support team.

Connect data through custom API tools, index approved public Help Center articles in Knowledge, and use a Custom Handoff relay for human replies. These are separate paths; live handoff requires your own deployed relay. The downloadable handoff pilot provides a starting point for that service.

Examples of when to use Chatwoot

Studio

Use an editable Voiceflow project and a Chatwoot account whose resources you can access. Before testing contact tools, have your developer map the signed-in customer to a verified Chatwoot contact ID and supply it to the session. API tools and Knowledge are configured in Agent studio; live support additionally needs a deployed relay.

Code

Use Voiceflow’s management API or CLI for tools and the Knowledge API for imports. Your backend supplies verified customer IDs, prepares write payloads and runs the optional relay. Keep Chatwoot tokens on the server.

Connecting Chatwoot

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

In Chatwoot, open Profile Settings and copy your personal API access token. Replace https://CHATWOOT_HOST in request URLs with your workspace URL’s origin (for example https://app.chatwoot.com), and take ACCOUNT_ID from /app/accounts/ACCOUNT_ID/ in that URL. The Account/Application API uses the api_access_token header; its routes and credential differ from Chatwoot’s public inbox API and Platform administration API.

On Chatwoot Cloud, the account must have API and webhooks enabled. Otherwise token-authenticated requests return 403 with API access is not enabled for this account.

The token acts as its user. Confirm membership in the account and access to the intended inbox; webhook registration requires an account administrator. Store the token in the restricted Secret chatwoot_token. Use a test project and test inbox for writes.

Prepare and test a contact lookup

Studio

1

Store the credential

Open the project in Agent studio. In the left sidebar, open More → Secrets and create chatwoot_token with the Chatwoot token. 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 Chatwoot contact. Choose GET and set the URL to https://CHATWOOT_HOST/api/v1/accounts/ACCOUNT_ID/contacts/{contact_id}. Add the header api_access_token with input {api_access_token} and Accept: application/json.

3

Bind trusted inputs and test

First create chatwoot_contact_id in More → Variables, leaving its default empty. Have your developer pass variables: {"chatwoot_contact_id":"VERIFIED_CHATWOOT_ID"} with the authenticated backend’s initial launch action; creating a session alone does not populate it. Obtain a verified test contact ID from them. Return to the tool, set the api_access_token input’s default to the Secret chatwoot_token, and bind contact_id to that identity variable rather than asking the model to choose a customer. Test that contact ID, inspect the response and capture only the fields your support task needs.

Bind the contact lookup to an identity verified by your application. Photo:

Before publishing a tested tool, select the target Environment and open chatwoot_token in More → Secrets. Set its Default value to the credential that Environment’s published agent should use; Draft value alone does not supply it. Follow Secret publication behavior, then publish the tested agent.

Code

Create a personal or service key with access to the project and set it as VF_TOKEN. Set PROJECT_ID to that project’s ID and ENVIRONMENT to the alias shown on its Environments page. Use a test Environment. Set CHATWOOT_TOKEN to your personal Chatwoot API token and CHATWOOT_CONTACT_ID to a contact ID verified by your application. Use a current Voiceflow CLI with API-tool and tool commands; it reads VF_TOKEN.

Save this definition as chatwoot-tool.json, replacing CHATWOOT_HOST and ACCOUNT_ID. Braced names declare API-tool inputs, not project Secrets:

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:

Save secret.id as SECRET_ID:

Send variables: {"chatwoot_contact_id":"VERIFIED_CHATWOOT_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 contact ID as the variable default.

2

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.

3

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.payload.id, payload.name and payload.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 contact ID. Confirm that the correct record was used. Publish the tested Environment after preparing its published Secret value.

Code

Save this as chatwoot-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

Check the provider response and update the credential slot that actually executes the request.
  • 401: verify the host and token. Update the selected Draft Secret, test a read, then update the Published value when ready. Revoke the previous token after switching consumers.
  • 403: if the error is API access is not enabled for this account, enable that account capability first. Otherwise verify account membership and permission for the inbox or operation. Retrying with the same token does not add access.
  • 429: wait for the provider’s rate-limit window before retrying. Do not retry writes blindly after a lost response; inspect the conversation first.

Finding and updating contacts

Use a verified contact to retrieve support context and keep customer details current.

The lookup configured above reads GET /api/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID. The record is in payload, including payload.id, name, email, phone_number and identifier. Chatwoot contact IDs differ from your application’s user IDs.

Establish the identity mapping

Studio

  • Create chatwoot_contact_id in More → Variables, leaving its default empty. Your authenticated application must populate it for the session.
  • In Find Chatwoot contact, bind contact_id to this variable. Test a known contact and an absent ID, then inspect the returned payload.
  • Capture only the support fields the agent needs. A customer typing someone else’s email is not proof they own that contact.

Code

Resolve the authenticated user to a stored Chatwoot contact ID on your backend. If you need a lookup, GET /api/v1/accounts/ACCOUNT_ID/contacts/search?q=QUERY&page=1 returns payload[] and meta.has_more. Search is a substring match across name, email, phone and identifier, not an identity check. Follow pages and verify the match against your own identity record.

To create a missing contact, POST /api/v1/accounts/ACCOUNT_ID/contacts with approved name, email, phone_number or identifier values. Save payload.contact.id from the create response. Subsequent GET and PUT responses use payload.id. Persist this mapping instead of creating a contact on every turn.

Update confirmed contact details

Use PUT /api/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID with only the fields the customer has confirmed. This example changes the display name:

Studio

Create a separate API tool with that method and a URL ending in /contacts/{contact_id}. Add api_access_token: {api_access_token}, Content-Type: application/json and a raw JSON body containing {payload}. Bind the token input to the chatwoot_token Secret and contact_id to the chatwoot_contact_id variable from Connecting Chatwoot.

In More → Variables, create chatwoot_contact_update_payload with an empty default. Have your developer JSON-serialize the customer-confirmed changes using the literal-safe preparation rules, then supply that string in the next action’s variables before this tool runs. Bind payload to {chatwoot_contact_update_payload}. For a Studio test, paste the developer’s prepared string into the test input. Verify payload.name by reading the contact again. Keep identity fields and permission-sensitive attributes outside model control.

Code

Copy chatwoot-tool.json from the API/CLI setup, keep /contacts/{contact_id}, change httpMethod to "put", and add body: {"type":"raw-input","contentType":"json","content":"{payload}"} plus Content-Type: application/json. Prepare the confirmed fields using the literal-safe encoder; pass that string as inputs.payload for standalone execution.

Create chatwoot_contact_update_payload with the earlier variable API or CLI command, changing name and leaving defaultValue empty. Supply its serialized value in the next action’s variables before the agent uses it. Discover this new tool’s input IDs and attach it with defaults api_access_token: {chatwoot_token}, contact_id: {chatwoot_contact_id} and payload: {chatwoot_contact_update_payload}, each required: false. Read the contact back after success and verify payload.name.

Creating conversations

Open a support case in the right inbox and preserve its conversation ID.

Use a Chatwoot API inbox when Voiceflow will relay customer messages. Incoming message creation through the Account API is supported for API inboxes; a token alone does not turn another channel into one.

Prepare the contact and inbox

Create an API inbox in Chatwoot → Settings → Inboxes → Add inbox → API, and give the responding teammates access. Open that inbox’s settings and take inbox_id from /app/accounts/ACCOUNT_ID/settings/inboxes/INBOX_ID in the URL. Associate the verified contact with it using POST /api/v1/accounts/ACCOUNT_ID/contacts/CONTACT_ID/contact_inboxes and {"inbox_id":12}. Save the returned root source_id; it identifies this contact-inbox relationship, not the contact or your user.

Backend prerequisite: your developer provisions this association for the authenticated customer and keeps it in a server-side mapping. For Studio setup, ask for the resulting account ID, API inbox ID, verified contact ID and contact-inbox source_id before testing the conversation tool or relay. Do not collect these IDs from the customer or substitute an email address for them. If the contact does not exist, the backend creates it through Chatwoot’s Contacts API first.

The IDs must belong together. A conversation’s returned id is the account-scoped display ID used by subsequent API routes and webhooks.

Studio

Use the developer-provided mapping in your test request below. Have the application supply the complete prepared payload for each signed-in customer; a shared default or manually entered production contact ID would send different customers into the same case.

Code

Set CHATWOOT_URL to the instance origin, CHATWOOT_ACCOUNT_ID to the account and CHATWOOT_INBOX_ID to its API inbox. With the verified CHATWOOT_CONTACT_ID and token from connection setup, provision or retrieve the association:

Save the root source_id with that account, inbox and contact. Use this trusted mapping when serializing each customer’s conversation payload. The handoff pilot uses it as CHATWOOT_SOURCE_ID for its single test customer.

Create and test the conversation tool

This illustrative payload opens a case and gives teammates a private note. Replace the IDs and source ID using the mapping above. It does not yet connect live replies to Voiceflow.

Studio

1

Add the request

Open Agent → Global tools → + → API and create Create Chatwoot conversation. Choose POST https://CHATWOOT_HOST/api/v1/accounts/ACCOUNT_ID/conversations. Add api_access_token bound to chatwoot_token and Content-Type: application/json. Use the raw JSON body input {payload}.

Prepare the conversation for a verified contact and inbox. Photo:
2

Bind the confirmed request

Create chatwoot_conversation_payload in More → Variables, leaving its default empty. Your backend builds its JSON from verified contact/inbox IDs and the customer-confirmed issue, then supplies the resulting string in an action’s variables before creation runs. Bind the tool’s payload default to that variable; do not ask the model to construct identity or authorization fields. Make literal-safe serialization part of the backend preparation: JSON-serialize the request, then encode { and } inside JSON strings as \u007b and \u007d, leaving object braces unchanged. Ask the developer to verify that quotes, newlines and text such as {customer_name} arrive unchanged after JSON decoding. Paste the returned prepared payload when testing in Studio; do not insert free text into quoted JSON by hand.

3

Confirm the result

Run once in a test inbox. Inspect the root id, inbox_id, status and meta.sender.id, then open the conversation in Chatwoot. Confirm the summary is a private note and retain the conversation ID for subsequent updates.

Code

Save the payload above as chatwoot-conversation-payload.json, replacing the illustrative IDs on your backend. Save chatwoot-conversation-tool.json with your host and account ID:

Serialize dynamic strings before execution. The standalone binder can interpret {name} or Secret-shaped text inside serialized input; this encoder escapes braces inside JSON strings, leaving object braces intact. Chatwoot receives the original text after JSON decoding:

Save apiTool.id as CONVERSATION_TOOL_ID:

Require success: true, a successful output.status and a root output.body.id. Verify output.body.inbox_id and meta.sender.id before storing the conversation mapping. Inspect error and truncated too; a management HTTP 200 is not proof of provider success.

For agent use, create chatwoot_conversation_payload with the variable pattern, leaving its default empty. Send its serialized confirmed request in the next action’s variables before this tool runs, then attach the tool. Discover this tool’s input IDs and bind api_access_token to {chatwoot_token} and payload to {chatwoot_conversation_payload}, both required: false. Test routing and the prepared data before publishing.

Supply verified case IDs

Before enabling case reads, routing or notes, have your backend developer map the signed-in customer’s support request to a Chatwoot conversation display ID. Store the root id returned by conversation creation with its account, inbox and verified contact. For an existing case, GET it and check meta.sender.id against that contact before using it. Do not accept an arbitrary case ID from the customer or model.

Studio

Create chatwoot_conversation_id in More → Variables with an empty default. Have the developer supply the verified display ID in the customer’s next action variables before a case tool runs. Obtain a disposable case ID for Studio tests and check that its contact and inbox match the intended customer. This mapping is application setup, not something the token connection creates.

Code

Create chatwoot_conversation_id using the variable API/CLI command, changing its name and leaving the default empty. Populate it from the backend’s verified case record in the next action’s variables. When your backend creates the case through standalone tool execution, persist output.body.id before sending it to the session; for an agent-created case, verify its ownership through the provider before later operations. Test a different customer’s case and reject it before tool execution.

Prevent duplicate conversations

Reuse the stored case and reconcile uncertain create responses before retrying.

Store the returned conversation ID with your own stable support-request ID. Do not assume POST is idempotent: a lost response can leave a case open. Inspect the contact’s conversations before retrying. An inbox configured to lock a contact to one conversation can reuse that conversation instead of creating a new one; verify its returned status and identity. The Chatwoot Conversation API describes the provider operation.

Reading and routing conversations

Review a customer’s case, assign support and update its priority or status.

Read GET /api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID using the stored display ID. Confirm meta.sender.id matches the verified contact before returning its status, priority, meta.assignee or meta.team.

Read the message history

GET /api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/messages returns payload[] with the latest 20 messages. Use before=MESSAGE_ID for older pages or after=MESSAGE_ID for up to 100 later messages. The conversation response’s messages[] seeds only its latest message; it is not the full history. API message types are numeric (0 incoming, 1 outgoing, 2 activity), while webhook message types are strings.

Studio

First complete the case-ID handoff. Add a GET API tool for each read, replacing CONVERSATION_ID in its URL with {conversation_id}. Reuse api_access_token: {api_access_token}, bind that input to the chatwoot_token Secret and bind conversation_id to {chatwoot_conversation_id}. Map only customer-visible fields into the response. Private notes and activity messages must not be returned as customer replies.

Code

Complete the case-ID handoff, then copy the lookup definition and API/CLI sequence. Change its URL to the desired conversation route, using {conversation_id} in place of CONVERSATION_ID. Execute with the verified display ID in inputs.conversation_id. Discover this tool’s input IDs and attach it with api_access_token: {chatwoot_token} and conversation_id: {chatwoot_conversation_id}, both required: false; do not reuse the contact tool’s input IDs. Fetch further message pages on the backend when building a history and filter private/activity messages before returning it to the customer.

Assign and update the case

All routes below start with /api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID. These are distinct requests; use the case ID stored for this customer.

  • Assign a team: POST /assignments with {"team_id":4}.
  • Assign a teammate: POST /assignments with {"assignee_id":9}. If both assignments are needed, send the team request first and the teammate request second; combining both fields selects the assignee branch and does not apply the team change.
  • Change priority: PATCH the conversation URL with {"priority":"high"}. Supported values are low, medium, high, urgent, or null to clear it.
  • Resolve or reopen: POST /toggle_status with {"status":"resolved"} or {"status":"open"}. Always pass an explicit status; do not rely on toggling the current value.

Studio

1

Configure the permitted change

Create a separate API tool for each permitted change. Use the shown method and path, with {conversation_id} bound to {chatwoot_conversation_id} from case setup. Reuse the token Secret and set Content-Type: application/json. The shown JSON bodies are fixed values; obtain permitted team/user IDs from your Chatwoot administrator before replacing the illustrative IDs. Confirm before resolving an active customer request.

2

Verify the updated case

Test against a disposable case, then GET it again to verify the assigned team/user, priority or status. Do not treat an assignment response as the full conversation.

Code

Use the API/CLI create, execute and attach sequence with httpMethod: "post" or "patch" and the appropriate conversation URL containing {conversation_id}. Set the raw JSON body’s content to the shown fixed JSON, with Content-Type: application/json; these fixed examples do not need a payload variable. Replace the illustrative team/user IDs with IDs supplied by your Chatwoot administrator. Resolve this tool’s input IDs and bind the token and case as in the read tool above. Keep allowed targets server-controlled. Read the conversation back after a write; assignments return their own resource rather than a full conversation.

Adding internal notes

Share the customer’s issue and completed checks with support teammates.

POST /api/v1/accounts/ACCOUNT_ID/conversations/CONVERSATION_ID/messages with an outgoing private message. Leaving out private: true makes an outgoing message public.

Add and verify the note

Studio

Create Add Chatwoot note in Agent → Global tools → + → API. Choose POST, use the message URL with {conversation_id}, add Content-Type: application/json and use a raw JSON {payload} body. Bind the token to the chatwoot_token Secret and conversation_id to {chatwoot_conversation_id} from case setup.

Create chatwoot_note_payload in More → Variables with an empty default. Have your developer serialize the confirmed note with private: true using the literal-safe preparation rules, and supply that string in the next action’s variables. Bind payload to {chatwoot_note_payload}. Use the developer’s prepared string in a Studio test; inspect the returned message id and private, then check that it appears as an internal note in Chatwoot.

Code

Use the write-tool definition and encoder, changing the URL to /conversations/{conversation_id}/messages. Add the verified case ID to standalone inputs alongside the token and encoded payload. Create chatwoot_note_payload with the variable API/CLI pattern, leaving the default empty; your backend supplies its serialized value in the next action before the note tool runs. Attach using this tool’s own input IDs and defaults api_access_token: {chatwoot_token}, conversation_id: {chatwoot_conversation_id} and payload: {chatwoot_note_payload}, each required: false.

Verify the root message id and private: true. The REST response uses numeric message_type: 1 for outgoing. A private note must never be forwarded by your relay as message.received.

Import help articles

Answer from approved public Chatwoot 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 conversation tools or create a managed Chatwoot 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.

Import approved public Help Center articles into Knowledge. Photo:
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.

Code

Obtain the target project’s project API key from its administrator (Settings → API keys) and set it as the server-side VF_PROJECT_API_KEY. This Knowledge route derives the project from that key; the management bearer token is not interchangeable. Set ENVIRONMENT to the target alias from the project’s Environments page. Replace the illustrative URL with a public article that opens in a signed-out browser:

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 contact and conversation 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 a Chatwoot inbox.

Use the downloadable text-only Chatwoot pilot in the Custom Handoff starter. It creates a Chatwoot conversation, forwards incoming customer text, accepts signed public teammate replies and resolves the mapped conversation.

The pilot fixes one test contact and API inbox, and keeps mappings and duplicate IDs in memory. Before serving multiple customers, implement verified per-customer contact mapping, durable storage and a queued callback outbox. Restarting the pilot loses its mappings. File transfer and queue routing are not implemented; keep files disabled and use the configured test inbox.

Prepare Chatwoot and deploy the pilot

Studio

1

Arrange the test inbox and relay

Have your developer deploy the Chatwoot Custom Handoff starter for one dedicated contact and API inbox. Give them the target Voiceflow project ID and the Chatwoot administrator who can prepare the contact-inbox mapping. The administrator must confirm that a teammate can reply in that test inbox.

2

Obtain the connection values

Before opening Voiceflow’s connection form, obtain the relay’s HTTPS Base URL, its Authorization header value (Bearer …), the separate Voiceflow callback Webhook secret of at least 32 characters, and the dedicated test contact ID. Have the developer confirm the relay is running for your project, the contact/inbox association exists, and one Chatwoot account webhook subscribes to both message_created and conversation_status_changed with its signing secret configured on the relay. The Chatwoot webhook signing secret stays on the relay; it is not the Voiceflow Webhook secret.

Code

1

Prepare the API inbox and contact

Complete the contact-inbox mapping. In Chatwoot, create a manual test conversation in that API inbox and verify that an assigned teammate can reply. Use a dedicated test contact, not a shared production customer.

2

Download and configure the service

Download all four files into one folder: server.mjs, protocol.mjs, chatwoot.mjs and test.mjs. Use Node.js 22 or later.

Set these environment variables on the server:

  • PROVIDER=chatwoot, CHATWOOT_URL (instance origin), CHATWOOT_ACCOUNT_ID and CHATWOOT_TOKEN.
  • CHATWOOT_INBOX_ID, CHATWOOT_CONTACT_ID and CHATWOOT_SOURCE_ID from the same contact-inbox mapping.
  • HANDOFF_TOKEN for Voiceflow’s requests to your relay, and a separate EVENT_TOKEN for the starter’s normalized /events endpoint.
  • WEBHOOK_SECRET, a random secret of at least 32 characters for callbacks to Voiceflow; VOICEFLOW_PROJECT_ID for the one allowed project; and VOICEFLOW_WEBHOOK_URL set to https://general-runtime.voiceflow.com/handoff/webhook/custom.

Run node --test test.mjs, then node server.mjs (port 8787 by default). Expose it through an HTTPS reverse proxy. Keep tokens outside source control. Local tests use mock requests; they do not create or verify a real Chatwoot conversation.

3

Register the signed provider webhook

An account administrator registers one account webhook for message_created and conversation_status_changed, pointing to https://YOUR_RELAY/provider-events. Its own Chatwoot-generated secret must be set as CHATWOOT_WEBHOOK_SECRET in the relay, separately from WEBHOOK_SECRET above.

Use Chatwoot’s Settings → Integrations → Webhooks, or create the account webhook through its API. Set CHATWOOT_URL, CHATWOOT_ACCOUNT_ID, CHATWOOT_TOKEN and RELAY_URL in your admin shell:

Read payload.webhook.secret from the response and configure the relay’s CHATWOOT_WEBHOOK_SECRET, then restart it. Do not paste this secret into public logs. Leave the API inbox’s own webhook URL blank when using the account webhook: that second delivery path has a different secret and would duplicate notifications. See Chatwoot webhooks.

Keep the deployed HTTPS origin as RELAY_URL. For Studio configuration, hand over that Base URL, Authorization: Bearer HANDOFF_TOKEN, the separate Voiceflow WEBHOOK_SECRET and the dedicated test contact ID through your team’s secret-sharing process. Confirm the service and signed provider receiver are configured before connecting Voiceflow. Two-way acceptance happens after the Workflow and customer client are ready below.

Connect and route the handoff

Studio

1

Connect the deployed service

Open your project in Agent studio → More → Integrations. Find Custom Handoff and select Connect. Enter the developer-provided HTTPS Base URL, Auth header name Authorization, Auth header value Bearer YOUR_HANDOFF_TOKEN, and the separate Voiceflow Webhook secret from the handoff above. This form connects your service, not Chatwoot directly.

Connect the deployed Chatwoot relay through Custom Handoff. Photo:
2

Configure a support Workflow

Create a Workflow, add a Handoff step and select Custom Handoff. For this single-contact pilot, set End user ID to the dedicated test contact ID provided by your developer. Select Full transcript under Handoff context so the relay can prepare private staff context without an undeclared summary variable. Keep files disabled and enable Return and Fail paths. The pilot uses its configured inbox; changing the editor’s queue does not route it to a different team.

Route the support Workflow through your Chatwoot relay. Photo:
3

Attach and test the Workflow

Add the Workflow to the agent and describe when to call it, such as a customer asking for a person. Publish to a test Environment and connect the customer chat to that Environment. Complete the conversation checks below with a teammate.

Code

Use the management credential and project ID from setup. Save chatwoot-handoff.json with your deployed HTTPS origin, HANDOFF_TOKEN and the same WEBHOOK_SECRET used by the relay for Voiceflow callbacks. The Chatwoot token and Chatwoot-generated signing secret stay on the relay:

A 200 confirms stored project default-slot configuration, not message delivery. Follow the headless Workflow creation, attachment and publication sequence with provider custom and Return/Fail paths. Preserve existing agent registrations when attaching it. Implement the Chat handoff traces and human-message contract in the customer client and test its published Environment.

Verify the complete conversation

  1. Escalate once from the test customer. Confirm one conversation in the intended Chatwoot API inbox and the correct contact. Its escalation summary must be a private note.
  2. Send customer text from Voiceflow and a public teammate reply from Chatwoot. Confirm each arrives once in the other interface.
  3. Add a private note and replay a signed provider event. Neither should produce an extra customer-visible reply. Reject invalid signatures and unmapped conversations.
  4. Resolve in Chatwoot and verify the Return path. Separately end from Voiceflow and confirm the same case resolves once; a reflected closure must not resume the agent twice.
  5. Stop the relay and verify the Fail path for a new handoff. Check provider deliveries and the signed Voiceflow callback response if a reply is missing.

Harden the relay before serving customers

Persist identity and delivery state and reconcile gaps in provider notifications.
  • Creation and privacy: the pilot posts to /conversations with its verified test mapping and status: "open". The initial outgoing, private: true message is staff context; it must not be sent as a public reply. Store the returned display ID before acknowledging creation.
  • Customer messages: POST /conversations/ID/messages with message_type: "incoming", private: false and the customer’s text. Deduplicate the Voiceflow message ID before writing. Keep uploads disabled until you implement both directions.
  • Human messages: verify X-Chatwoot-Timestamp within five minutes and X-Chatwoot-Signature against the raw body. Chatwoot signs TIMESTAMP + "." + RAW_BODY with HMAC-SHA256 and a sha256= hexadecimal prefix. Filter by account and mapped conversation; accept only message_created, message_type: "outgoing", non-private, non-empty messages whose sender.type is user. Exclude AgentBot and Captain assistant messages, missing or unknown sender types, incoming echoes and activity. Deduplicate by the stable message ID, not delivery ID alone.
  • Closure: POST /conversations/ID/toggle_status with explicit status: "resolved". A signed conversation_status_changed notification with root status: "resolved" becomes one conversation.ended callback. Persist the terminal state so your own close cannot loop.
  • Delivery: account webhooks have a default five-second timeout (configurable when self-hosted), without a guaranteed retry. Authenticate and queue promptly, then reconcile missed messages using the provider’s message history. This is separate from Chatwoot’s AgentBot retry behavior. Sign callbacks with the separate Voiceflow webhook secret and inspect their response.

Use the shared service durability checks for persistent mappings, an outbox and restart recovery. Verify signed delivery on your deployed Chatwoot version before accepting customer traffic.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.