:::note **TL;DR** - Connect Voiceflow to a tarot card API to build an interactive chatbot that draws cards, interprets spreads, and answers yes or no questions - The API returns card names, meanings, reversal status, keywords, and card images, so your chatbot delivers rich, authentic readings - No tarot knowledge required on your end. The API handles all 78 cards, interpretations, and spread logic - Build this in under an hour with [RoxyAPI Tarot API](/products/tarot-api) and a free Voiceflow account ::: **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](/products/tarot-api) gives you the complete 78-card Rider-Waite-Smith deck with interpretations, spreads, and card images out of the box. [See pricing](/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: ```bash 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: ```json { "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: ```json { "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: ```json { "question": "Should I accept the job offer?" } ``` The response returns a clear answer along with the reasoning: ```json { "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](/api-reference#tag/tarot) 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](/products/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](/pricing).