Build a Tarot Reading Chatbot with Voiceflow and an API

About the author: Valentina Alcantara is a Tarot Reader and Crystal Healing Practitioner with 15 years of experience in tarot reading, crystal healing, and spiritual education. She founded TarotVivo, an online school that has certified over 3,000 tarot readers across Latin America. Her interpretations draw on Rider-Waite symbolism, Mesoamerican cosmology, and the healing properties of crystals native to the Americas.

Tarot reading chatbots are one of the most engaging conversational experiences you can build. Users type a question, your bot draws cards from a full 78-card deck, and it delivers a personalized interpretation, complete with card imagery and reversal meanings. The problem is that building the tarot logic from scratch requires deep domain expertise: 78 unique cards, upright and reversed interpretations, multiple spread layouts, and position-specific meanings. That is months of content work before you write a single line of chatbot logic. A tarot reading API eliminates that entire layer. You configure your chatbot to call the API, and the response contains everything you need: card names, keywords, full interpretations, reversal status, and image URLs. This guide walks through building that chatbot in Voiceflow, step by step.

What you will build

You will create a conversational chatbot that offers three types of tarot readings. First, a general card draw where the user specifies how many cards they want pulled from the deck. Second, a yes or no oracle where the user asks a specific question and receives a definitive answer backed by a single tarot card. Third, structured spreads like the classic three-card Past, Present, Future layout. Each reading will display the card name, whether it appeared upright or reversed, the key themes associated with the card, a full narrative interpretation, and a link to the card image. The chatbot will handle the entire conversation flow: greeting the user, capturing their intent, calling the tarot API, parsing the response, and presenting the reading in a natural, engaging way. By the end, you will have a working prototype you can deploy as a web widget, embed on a website, or connect to a messaging platform.

Ready to build this? RoxyAPI Tarot API gives you the complete 78-card Rider-Waite-Smith deck with interpretations, spreads, and card images out of the box. See pricing.

Prerequisites you will need

You need two things before you start. First, a Voiceflow account. The free plan works for building and testing. Create a new Agent project in Voiceflow, which gives you a canvas for designing conversation flows. Second, a RoxyAPI API key. Get one at roxyapi.com/pricing. Instant delivery, no account creation required. Your API key authenticates every tarot API call using the X-API-Key header. Test your key immediately with a curl command to confirm it works:

curl -X POST https://roxyapi.com/api/v2/tarot/draw \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 1}'

You should receive a JSON response containing a drawn card with its name, meaning, keywords, reversal status, and image URL. If that works, you are ready to build.

Step 1: Create the project and conversation flow

In Voiceflow, create a new Agent project. Open the workflow editor and drag a Message step onto the canvas as your starting point. Configure it with a greeting that sets the mood for a tarot reading session. Something like: "Welcome to the Tarot Reading Room. I can draw cards for you, answer a yes or no question, or lay out a three-card spread. What would you like?" Next, create three variables in the Variables panel that you will use later: user_intent to capture the type of reading, user_question to store any question the user asks, and card_count to hold how many cards to draw. Variables in Voiceflow are referenced by typing { in any text input, which opens a searchable menu. These variables will carry user input through the flow and into your API calls.

Step 2: Capture the user intent

After the greeting message, you need to determine which type of reading the user wants. Add a Playbook step or use Voiceflow conditions to classify the user message into one of three intents: "draw cards", "yes or no", or "three-card spread". For a quick setup, use a Playbook with instructions like: "Classify the user message. If they want to draw cards or pull cards, set user_intent to draw. If they have a yes or no question, set user_intent to yesno. If they want a three-card or past present future spread, set user_intent to spread." Branch the flow based on the user_intent variable using condition steps. For the draw intent, add a follow-up message asking "How many cards would you like me to draw? (1 to 10)" and capture their response into the card_count variable. For the yes or no intent, ask "What is your question?" and store the response in user_question.

Step 3: Add the API tool for card drawing

Now create an API tool in Voiceflow for the tarot draw endpoint. Go to the Tools section and click New API tool. Configure it with the following settings. Set the method to POST and the URL to https://roxyapi.com/api/v2/tarot/draw. Add two headers: X-API-Key with your RoxyAPI key, and Content-Type with value application/json. For the request body, use this JSON structure:

{
  "count": 3,
  "allowReversals": true
}

The count field accepts any number from 1 to 78. Set allowReversals to true so cards can appear reversed, which adds depth to readings. Click Run in the API tool editor to test it. You should see a response like this:

{
  "cards": [
    {
      "id": "fool",
      "name": "The Fool",
      "arcana": "major",
      "position": 1,
      "reversed": false,
      "keywords": ["beginnings", "innocence", "spontaneity"],
      "meaning": "The Fool represents new beginnings and unlimited potential...",
      "imageUrl": "https://roxyapi.com/img/tarot/major/fool.jpg"
    }
  ]
}

Each card in the cards array contains everything your chatbot needs to present a reading.

Step 4: Map the response to variables

After testing the API tool, you need to capture the response data so your chatbot can use it. In the API step on your canvas, use the Capture response field to save the full API response to a variable called tarot_response. You can also extract specific fields using object path notation. For example, set cards.0.name to capture the first card name into a variable called first_card_name. Set cards.0.reversed to capture reversal status into first_card_reversed. Set cards.0.keywords to capture the keywords array into first_card_keywords. And set cards.0.meaning to capture the full interpretation into first_card_meaning. For multi-card draws, you can access each card by its array index: cards.0 for the first card, cards.1 for the second, and cards.2 for the third. The imageUrl field at cards.0.imageUrl gives you a direct link to the Rider-Waite-Smith card artwork that you can display in the chat.

Step 5: Build the response message

After the API step captures the data, add a Message step to present the reading. Use variables to build a dynamic, engaging response. For a single card draw, your message template might look like this: "Your card is {first_card_name}. This card appeared {first_card_reversed} in your reading. Key themes: {first_card_keywords}. {first_card_meaning}." For reversed cards, you can use a condition step to check the first_card_reversed variable and adjust the language. When true, say "reversed (upside down)" to explain the significance. When false, say "upright." You can also include the card image by adding an Image step or inserting the imageUrl variable in a card or carousel component. Connect a final message asking "Would you like another reading?" and loop back to the intent capture step to keep the conversation going.

How to extend with more spread types

Once the basic draw flow works, add the yes or no oracle and three-card spread as separate branches. For the yes or no reading, create a second API tool pointing to POST https://roxyapi.com/api/v2/tarot/yes-no with this request body:

{
  "question": "Should I accept the job offer?"
}

The response returns a clear answer along with the reasoning:

{
  "question": "Should I accept the job offer?",
  "answer": "Yes",
  "strength": "Strong",
  "card": {
    "id": "empress",
    "name": "The Empress",
    "arcana": "major",
    "reversed": false,
    "keywords": ["abundance", "nurturing", "fertility"],
    "imageUrl": "https://roxyapi.com/img/tarot/major/empress.jpg"
  },
  "interpretation": "A Strong Yes. The Empress appeared upright, signaling forward momentum..."
}

Map answer, strength, card.name, and interpretation to variables and build a response message. For the three-card spread, use POST https://roxyapi.com/api/v2/tarot/spreads/three-card. The response uses a positions array where each position has a name (Past, Present, Future), a card object, and a position-specific interpretation. For advanced users, the Celtic Cross endpoint at POST /spreads/celtic-cross returns 10 cards across positions like Challenge, Foundation, Crown, and Outcome.

Common pitfalls to avoid

The most frequent mistake is forgetting the Content-Type: application/json header. Without it, the API cannot parse your request body and returns a 400 validation error. Always include both X-API-Key and Content-Type headers on every API tool. Second, remember that spread endpoints return positions[].card not a flat cards[] array. The three-card spread response nests each card inside a position object with a name and interpretation. Use positions.0.card.name for object path extraction, not cards.0.name. Third, the reversed field is a boolean (true or false), not a string. Use a condition step to check its value rather than comparing it as text. Fourth, do not hardcode the card count for the draw endpoint. Use a variable like {card_count} so users can request the number of cards they want. Finally, test every API tool using the Run button before connecting it to your flow. The response panel shows status codes, response size, and timing, which helps you catch configuration issues early.

Frequently Asked Questions

Q: Do I need tarot knowledge to build this chatbot? A: No. The tarot API returns complete interpretations, keywords, and card meanings for all 78 cards in both upright and reversed orientations. Your chatbot simply displays the data the API provides. The domain expertise is built into the API.

Q: Can I show tarot card images in the chatbot? A: Yes. Every card response includes an imageUrl field with a direct link to the Rider-Waite-Smith card artwork. Use an image component in Voiceflow or embed the URL in a card layout to display it inline.

Q: How do I give the same user the same daily card each day? A: Use the POST /daily endpoint with a seed parameter tied to the user. Pass the Voiceflow built-in user_id variable as the seed value. The API guarantees the same seed on the same date returns the same card.

Q: What is the difference between the draw endpoint and the spread endpoints? A: The POST /draw endpoint returns raw cards without position-specific context. The spread endpoints like POST /spreads/three-card assign each card to a named position (Past, Present, Future) and provide a position-specific interpretation plus a summary connecting all cards.

Q: Can I use this with voice assistants or phone bots? A: Yes. Voiceflow supports deploying to voice channels including phone integrations. The tarot API returns text-based interpretations that work perfectly as spoken responses. Card images would not apply in voice-only contexts, but the meanings, keywords, and interpretations translate directly to speech.

Build your tarot chatbot today

A tarot reading chatbot combines the engagement of conversational AI with the richness of authentic card divination. The technical complexity lives in the tarot domain, not in the chatbot logic, and a tarot reading API handles that entirely. You configure the API calls, map the response fields, and build the conversation flow around them. With the RoxyAPI Tarot API, you get the complete 78-card deck, structured spreads, yes or no readings, daily cards, and card images. Start building at roxyapi.com/pricing.