Import a conversation from CSV or Excel

You can create a conversation in a spreadsheet and import it into ChatMapper. This is useful when your dialogue already lives in Excel, Google Sheets, or a similar tool.

You do not need to create a separate row for ChatMapper’s START node. ChatMapper creates the conversation root for you and turns each data row into a dialogue or choice node.

1. Create the spreadsheet

Start with one header row. The simplest useful spreadsheet has these columns:

actor,text,menu
Mirren,"Welcome to Bay Four.",
,,"Look around."
,,"Leave."
Mirren,"Come back when you have a key.",

This creates a line from Mirren followed by two choices. Because the two choice rows are next to each other, ChatMapper treats them as two branches from the previous line.

For anything beyond a simple conversation, use IDs and parent IDs so that the structure is explicit:

conversation,id,actor,text,menu,parent,goto,condition,script
Bay Four,n1,Mirren,"The vault is sealed.",,,,
Bay Four,c1,,,"Ask for the key.",n1,,,
Bay Four,c2,,,"Leave the vault.",n1,,,
Bay Four,n2,Mirren,"Only the warden can open it.",,c1,,,
Bay Four,n3,Mirren,"Goodbye.",,c2,,,

Use a plain text editor or spreadsheet application to save the file as .csv (preferably CSV UTF-8). ChatMapper also accepts .tsv files and .xlsx workbooks.

2. Use the column names

Column names are not case-sensitive and may be in any order. These are the supported columns:

Column	What to put in it
conversation	The conversation name. Use the same name on several rows to group them together.
id	A unique ID for the row, such as n1 or choice_left.
actor	The character who speaks the line.
text	Spoken dialogue.
menu	Text shown to the player as a choice. A row can have menu instead of text.
parent	The id of the node this row should follow. root, start, or 0 means the conversation start.
goto	The id of another node to link to after this node. This can create a loop or a jump.
condition	A ChatMapper condition, such as Variable["has_key"] == true.
script	A ChatMapper script, such as Variable["asked"] = true.
title	An optional title for the node.

Several familiar alternatives work too. For example, speaker or character means actor, dialogue or line means text, choice means menu, and parent_id or from means parent.

3. Understand how rows become links

There are two ways to describe the conversation structure:

• Simple structure: ordinary rows follow one another in spreadsheet order. A group of consecutive menu rows becomes choices from the preceding ordinary line.
• Explicit structure: put an id on each row and use parent and goto. This is the safer choice for branches, loops, reordered rows, or large files.

If an actor cell is blank on an ordinary dialogue row, ChatMapper continues the previous actor. A blank actor on a menu row becomes the Player actor. You can change that name after import if needed.

To create multiple conversations in one CSV, add a conversation column and give each group of rows a conversation name. In an .xlsx workbook, separate sheets are also treated as separate conversations when they do not contain a conversation column.

4. Format text correctly

Put double quotes around a cell when it contains a comma, a line break, or a double quote. Inside a quoted cell, write a double quote twice:

actor,text
Mirren,"She said, ""Keep out."""
Mirren,"This line can continue
on a second line."

Do not add extra blank lines inside an unquoted cell. Empty rows are ignored, but a row with no ID, title, dialogue, or choice text is skipped.

You may add your own columns, such as vo_file, notes, or emotion. ChatMapper keeps those values as custom fields on the imported node. It will show them as unrecognized columns in the import report so you can review them.

5. Import the file

1. Open the ChatMapper project where you want the conversation.
2. Choose Import in the toolbar.
3. Select your .csv, .tsv, or .xlsx file.
4. Review the import report, especially warnings and any listed unrecognized or unresolved values.
5. Apply the import, then use Validate and Simulate to check the result.

If you are importing into an existing project, make a copy or export a backup first. Importing can replace or seed project content depending on the import option you choose.

Troubleshooting

The file is not recognized. Make sure it has a header row containing at least one supported name, such as actor, text, menu, or id. Save it as CSV UTF-8 rather than as a formatted workbook export.

All dialogue appears as one straight line. Add menu values to choice rows, or add id and parent columns to describe the branches explicitly.

A link is missing. Check that the parent or goto value exactly matches an id in the same conversation. IDs are not case-sensitive, but spelling and spaces still matter.

A speaker is wrong. Fill in the actor cell on the first line spoken by each character. Blank ordinary rows intentionally continue the previous speaker.

Some columns are listed as unrecognized. This is normally safe: custom columns are retained as node fields. Review the report to confirm that the field names match what your project or engine expects.