SEO keyword chat assistant for voice or text

SEO keyword chat assistant for voice or text

An n8n workflow that serves as the back end of an SEO chat. Your app posts a typed question or a voice note, with a
country and a language. Gemini turns a voice note into text, and a Gemini agent answers in Markdown with tables. Its
tools look up keywords, a competitor's rankings, Google's results and Google's AI Mode through a sub-workflow you build
on DataForSEO, and Firecrawl reads any page it names. The answer goes back in the same web request, and the chat keeps
its last 12 exchanges for each caller.

What is inside

• workflow.json: the workflow as n8n exports it, 27 nodes, eight of them sticky notes. It holds no credential.
• README.md: these notes.

What we changed from the original copy

• ranked_keywords, related_keywords, keyword_ideas, serp_search, ai_mode and internal_links called a
  sub-workflow in its author's own n8n. They arrive empty, so you build that sub-workflow and pick it in all six
  (below).
• The Firecrawl key in 🦺 Set Data was a placeholder in the author's own style. It now reads YOUR_FIRECRAWL_KEY,
  like the other kits.

Nothing else changed. The original copy had no backslashes missing.

Before you start

• An n8n instance, on n8n Cloud or your own server.
• A Gemini API key from Google AI Studio.
• A Firecrawl API key.
• A DataForSEO API login and password, for the sub-workflow.
• An app, a page or a tool such as Postman that sends the requests and shows the Markdown answer.

Set it up

1. In n8n, create a workflow, open its menu and choose Import from File. Pick workflow.json.
2. Add a Google Gemini credential with your key. Select it in Transcribe Audio, 2.5 Flash and 2.5 Pro.
3. In 🦺 Set Data, replace YOUR_FIRECRAWL_KEY with your Firecrawl key.
4. Build the sub-workflow described below and save it.
5. Open each of the six tool nodes under Keyword AI Agent and pick your sub-workflow in its workflow field.
6. Look at Memory. Its key is the caller's IP address, read from the cf-connecting-ip header that Cloudflare adds.
   If your n8n is not behind Cloudflare, that header is missing and the run stops at Memory. Point the key at a value
   your app sends instead, such as {{ $('Webhook').first().json.body.session_id }}.
7. Open Webhook. Its path is keywordresearch and it takes POST. Add Header Auth there if anyone else could learn
   the address.
8. Save, send a test request to the test address, then publish and use the production address.

The sub-workflow

All six tools call one sub-workflow, and function says which job is wanted. Start yours with a When Executed by
Another Workflow trigger that accepts these six fields:

{
  "function": "ranked_keywords, related_keywords, keyword_ideas, serp_search, ai_mode or internal_links",
  "keyword": "<the agent's search words>",
  "url": "<a domain such as example.com, or a page address>",
  "country_code": "<DataForSEO's location number, such as 2840>",
  "language_code": "<DataForSEO's language code, such as en>",
  "firecrawl_api": "<your Firecrawl key>"
}

Every tool sends function and the two codes. ranked_keywords adds url, which the agent is told to give as a bare
domain. internal_links adds url and the Firecrawl key. The other four add keyword. Despite its name,
country_code carries DataForSEO's location number. Return text or JSON the agent can read.

The file says nothing about what its author's version did, so here is one way to build it, from DataForSEO's and
Firecrawl's API pages read on 2 November 2026. A Switch on function leads to one HTTP Request each, with your
DataForSEO login as HTTP Basic Auth:

ranked_keywords   POST https://api.dataforseo.com/v3/dataforseo_labs/google/ranked_keywords/live
related_keywords  POST https://api.dataforseo.com/v3/dataforseo_labs/google/related_keywords/live
keyword_ideas     POST https://api.dataforseo.com/v3/dataforseo_labs/google/keyword_ideas/live
serp_search       POST https://api.dataforseo.com/v3/serp/google/organic/live/advanced
ai_mode           POST https://api.dataforseo.com/v3/serp/google/ai_mode/live/advanced
internal_links    POST https://api.firecrawl.dev/v2/map

Send location_code and language_code from the two codes in each DataForSEO body. ranked_keywords takes the domain
as target, related_keywords takes one keyword, and keyword_ideas takes a keywords list. The Firecrawl call
takes the address as url and the key as a Bearer header.

Calling it

A typed question is a JSON body:

{
  "type": "text",
  "message": "Keyword ideas for a bike repair shop in Leeds",
  "country": "United Kingdom",
  "language": "English"
}

A voice note is a multipart form, with the recording in a field called audio:

curl -X POST "https://<your n8n>/webhook/keywordresearch" -F type=voice -F country=Germany -F language=German -F audio=@question.mp3

type must be voice or text, in lower case. country and language must match a name in the lists inside the
Code node exactly, such as United States, Turkiye or Chinese (Simplified). It knows 94 countries and 46
languages.

How a run goes

1. Webhook takes the request and waits for Respond to Webhook before it answers.
2. Code looks up DataForSEO's location number and language code for the country and the language.
3. Switch sends a voice note to Transcribe Audio, where Gemini turns it into text, and a typed question
   to Set Message.
4. 🦺 Set Data gathers the question, the Firecrawl key, the two codes and the caller's IP address.
5. Keyword AI Agent answers with its long system prompt, the recent exchanges in Memory and its tools. It may
   call several tools before it writes.
6. Respond to Webhook sends the agent's answer back as JSON, in a field called output.

Change the look

• The assistant's voice and format: the system prompt in Keyword AI Agent. It sets the persona, the tables each kind
  of answer must hold, and the three suggestion lines at the end.
• More countries or languages: the two lists at the top of Code.
• How much the chat remembers: Context Window Length in Memory, 12 in the file.
• The fallback model: 2.5 Pro, which the agent uses when 2.5 Flash fails.
• How fresh a scraped page must be: maxAge in the body of URL_search, four hours in the file.

Good to know

• Billing: Gemini bills every agent round, and the system prompt alone runs to some 18,000 characters, sent each time.
  Firecrawl counts every scrape, and a PDF page by page. DataForSEO bills every call your sub-workflow makes.
• Models: neither 2.5 Flash nor 2.5 Pro names a model, so both run the node's default, Gemini 2.5 Flash. Pick
  models/gemini-2.5-pro in 2.5 Pro if you want Pro as the fallback.
• As of 2 November 2026: Google's deprecations page gives Gemini 2.5 no shutdown date. It limits those models to users
  who used them before, so a new key may need gemini-3.8-flash in all three Gemini nodes. Firecrawl's docs still list
  the v1 scrape that URL_search calls, with a note that v2 is out.
• The prompt tells the model to sound sure of itself and never to hedge, to cite experience it does not have, and to
  give click-through potential, readability scores and keyword density that no tool measures. Treat those figures as
  guesses, or take those lines out of the prompt.
• One section of the prompt is dated 2025 and quotes traffic figures with no source. The prompt names two tools a little
  differently from their nodes (url_search and AI_Mode), and asks for a domain where internal_links takes an
  address.
• Suggestions: every answer ends with three lines that start with [SUGGESTION]. The prompt meant them for a front end
  that turns them into buttons, so your app should show them that way or strip them.
• Wrong names: a country or language that is not in the Code lists leaves the codes empty, and the DataForSEO calls
  then fail. A type other than voice or text stops the run before any answer.
• Shared memory: callers behind one IP address, such as an office, share one conversation. The memory lives in n8n
  itself, so a restart clears it.
• Open webhook: once it is published, anyone with the address can run it on your keys until you add Header Auth.
• Your data: questions and voice notes go to Google, pages go to Firecrawl, and keywords and domains go to DataForSEO.
  Each caller's IP address is the memory key. Every execution also saves the Firecrawl key, since 🦺 Set Data holds
  it, so keep the executions list private.